Overview: Creating Python Packages
In the previous tutorial, you learned how Python packages help organize related modules into a structured collection. Now it is time to create one yourself.
In this tutorial, you will learn Creating Python Packages from the ground up. You will understand how a package is organized, how to add modules, why the __init__.py file is used and how to import and use your package in a Python program.
By the end of this tutorial, you will be able to build a simple Python package and use it confidently in your own projects.
Quick Navigation
Use the links below to jump directly to any topic covered in this tutorial.
- Introduction: Creating Python Packages
- What Is a Python Package Structure?
- Creating Your First Python Package
- Adding Modules to a Python Package
- Adding an
__init__.pyFile - Using a Python Package in Your Program
- Example: Creating and Using a Python Package
- Common Mistakes When Creating Python Packages
- Key Takeaways: Creating Python Packages
Introduction: Creating Python Packages
As Python projects become larger, storing every module in the same folder can make the project difficult to organize. Python packages solve this problem by grouping related modules into a single directory.
A package helps organize code into logical sections, making projects easier to understand, maintain, and expand. Instead of searching through many unrelated files, you can keep modules that serve the same purpose together.
Creating a Python package is straightforward. In most cases, it involves creating a folder, placing related modules inside it, and adding an __init__.py file to identify the folder as a package.
Real-World Analogy
Imagine a filing cabinet with separate folders for finance, employees, and customer records. Each folder stores documents related to one topic, making everything easier to find.
A Python package works in a similar way. It groups related Python modules inside one folder so they remain organized and easy to manage.
What Is a Python Package Structure?
A Python package follows a simple folder structure. The package itself is a directory that contains one or more Python modules and usually an __init__.py file.
For example, a package named calculator might be organized like this.
calculator/
│
├── __init__.py
├── arithmetic.py
├── geometry.py
└── conversions.py
Understanding the Structure
- calculator/ is the package folder.
- __init__.py identifies the directory as a Python package.
- arithmetic.py, geometry.py, and conversions.py are modules that contain related code.
Organizing modules this way keeps projects cleaner and makes related functionality easier to locate.
Creating Your First Python Package
Creating a Python package requires only a few simple steps.
- Create a new folder that will become your package.
- Create one or more Python module files inside the folder.
- Add an
__init__.pyfile.
Suppose you want to create a package named calculator.
calculator/
│
├── __init__.py
└── arithmetic.py
At this stage, the folder is ready to hold reusable modules that can be imported into other Python programs.
Adding Modules to a Python Package
A package becomes useful when it contains modules that perform related tasks. Each module should focus on one specific responsibility.
Suppose the arithmetic.py module contains the following function.
arithmetic.py
def add(a, b):
return a + b
You can continue adding more modules as your project grows.
calculator/
│
├── __init__.py
├── arithmetic.py
├── geometry.py
└── conversions.py
Keeping related modules together makes the package easier to maintain and reuse.
Adding an __init__.py File
The __init__.py file is placed inside the package directory. Traditionally, it tells Python that the folder should be treated as a package.
For many beginner projects, the file can simply be empty.
__init__.py
# Empty file
As you learn more about Python packages, you will discover that this file can also be used for package initialization and controlling what gets imported.
For now, creating an empty __init__.py file is enough to understand the basic package structure.
Using a Python Package in Your Program
Once the package has been created, its modules can be imported into another Python file.
Suppose the project has the following structure.
project/
│
├── main.py
└── calculator/
├── __init__.py
└── arithmetic.py
main.py
from calculator.arithmetic import add
print(add(10, 5))
# Output
15
Code Explanation
The statement from calculator.arithmetic import add imports the add() function from the arithmetic module inside the calculator package.
The function is then called directly to add two numbers, and the result 15 is displayed.
Example: Creating and Using a Python Package
The following example combines everything learned in this tutorial.
project/
│
├── main.py
└── calculator/
├── __init__.py
└── arithmetic.py
arithmetic.py
def multiply(a, b):
return a * b
main.py
from calculator.arithmetic import multiply
print(multiply(6, 7))
# Output
42
Code Explanation
The multiply() function is stored inside the arithmetic.py module, which belongs to the calculator package.
The program imports the function, calls it with the values 6 and 7, and prints the result 42.
Common Mistakes When Creating Python Packages
Beginners often encounter a few common problems while creating Python packages. Understanding these mistakes will help you avoid unnecessary errors.
- Creating modules outside the package folder.
- Misspelling the package or module name during import.
- Forgetting to create the
__init__.pyfile in beginner projects. - Placing unrelated modules inside the same package.
- Using package names that conflict with Python’s standard library modules.
Following a clear package structure makes projects easier to understand and maintain.
Key Takeaways: Creating Python Packages
Here are the key points to remember:
- A Python package is a folder that groups related modules.
- Packages help organize larger Python projects.
- A package usually contains one or more modules and an
__init__.pyfile. - Modules inside a package can be imported into other Python programs.
- Keeping related modules together makes code easier to maintain and reuse.
You now know how to create a Python package, organize modules inside it, and use the package in your programs. In the next tutorial, you will learn how Python imports packages and how package imports work in larger projects.