Creating a Complete Package Structure
Now that we understand the basic principles of Python packages and the role of the __init__.py
file, let's create a more complete package structure that follows best practices. This will help you organize larger projects effectively.
Best Practices for Package Structure
A well-organized Python package typically follows this structure:
package_name/
├── __init__.py
├── module1.py
├── module2.py
├── subpackage1/
│ ├── __init__.py
│ └── module3.py
├── subpackage2/
│ ├── __init__.py
│ └── module4.py
├── README.md
├── setup.py
└── tests/
├── __init__.py
├── test_module1.py
└── test_module2.py
Let's implement a simplified version of this structure for our calculator package:
- Create a README.md file:
touch ~/project/calculator_package/README.md
- Open the README.md file in the WebIDE and add:
## Calculator Package
A simple Python package that provides basic and advanced calculator functions.
### Features
- Basic arithmetic operations (addition, multiplication)
- Advanced scientific operations (square root, power)
### Usage
```python
from calculator_package import add_two_numbers, multiply_two_numbers
from calculator_package.advanced import square_root, power
## Basic operations
result1 = add_two_numbers(5, 3)
result2 = multiply_two_numbers(4, 2)
## Advanced operations
result3 = square_root(16)
result4 = power(2, 3)
```
3. Create a tests directory:
```bash
mkdir ~/project/calculator_package/tests
touch ~/project/calculator_package/tests/__init__.py
- Create test files:
touch ~/project/calculator_package/tests/test_basic.py
- Open
test_basic.py
in the WebIDE and add:
import unittest
from calculator_package import add_two_numbers, multiply_two_numbers
class TestBasicOperations(unittest.TestCase):
def test_addition(self):
self.assertEqual(add_two_numbers(5, 3), 8)
self.assertEqual(add_two_numbers(-1, 1), 0)
def test_multiplication(self):
self.assertEqual(multiply_two_numbers(5, 3), 15)
self.assertEqual(multiply_two_numbers(-2, 3), -6)
if __name__ == '__main__':
unittest.main()
- Create a setup.py file for package distribution:
touch ~/project/setup.py
- Open
setup.py
in the WebIDE and add:
from setuptools import setup, find_packages
setup(
name="calculator_package",
version="0.1.0",
author="Your Name",
author_email="[email protected]",
description="A simple calculator package",
packages=find_packages(),
classifiers=[
"Programming Language :: Python :: 3",
"License :: OSI Approved :: MIT License",
"Operating System :: OS Independent",
],
python_requires=">=3.6",
)
- Let's run the unit tests:
cd ~/project
python3 -m calculator_package.tests.test_basic
You should see output similar to:
Calculator Package v0.1.0 initialized
..
----------------------------------------------------------------------
Ran 2 tests in 0.001s
OK
This confirms that our package is well-structured and the tests are working correctly.
Package Documentation with Docstrings
Good documentation is essential for any Python package. Let's add proper docstrings to our package:
- Update the
calculator_package/__init__.py
file to include a package-level docstring:
"""
Calculator Package - A collection of calculator functions.
This package provides various calculator functions including basic
arithmetic operations and advanced scientific operations.
"""
## Import functions from modules
from .addition import add_two_numbers, add_multiple_numbers
from .multiplication import multiply_two_numbers, multiply_multiple_numbers
## Define package-level variables
__version__ = "0.1.0"
__author__ = "Your Name"
## Print a message when the package is imported
print(f"Calculator Package v{__version__} initialized")
## Import the advanced subpackage
from . import advanced
- You can view the docstring using Python's help function:
cd ~/project
python3 -c "import calculator_package; help(calculator_package)"
This should display the package documentation:
Help on package calculator_package:
NAME
calculator_package - Calculator Package - A collection of calculator functions.
DESCRIPTION
This package provides various calculator functions including basic
arithmetic operations and advanced scientific operations.
PACKAGE CONTENTS
addition
advanced (package)
multiplication
tests (package)
DATA
__author__ = 'Your Name'
__version__ = '0.1.0'
FILE
/home/labex/project/calculator_package/__init__.py
This documentation helps users understand the purpose and capabilities of your package.