Creating Python Modules and Packages Guide

Python modules and packages help organize code. They make it reusable. This guide shows how to create them properly.

What Are Python Modules?

A module is a single Python file. It can contain functions, classes, and variables. You can import it into other scripts.

Here's a simple module example:

# mymodule.py
def greet(name):
    """Returns a greeting message"""
    return f"Hello, {name}!"

version = "1.0"

Creating a Basic Module

To create a module, save your code in a .py file. The filename becomes the module name. Follow these steps:

1. Create a new Python file

2. Add your functions and variables

3. Save it with a .py extension

You can then import it using import. Learn more in our Python Import Management Guide.

What Are Python Packages?

Packages are collections of modules. They help organize related modules together. A package is a directory with a special file.

The key file is __init__.py. It makes Python treat the directory as a package. It can be empty or contain initialization code.

Creating a Python Package

Follow these steps to create a package:

1. Create a directory for your package

2. Add an __init__.py file

3. Add module files to the directory

Here's a sample package structure:

mypackage/
│── __init__.py
│── module1.py
└── module2.py

Importing Modules from Packages

You can import package modules in several ways. Here are common patterns:

# Import entire module
import mypackage.module1

# Import specific items
from mypackage.module2 import some_function

# Import with alias
import mypackage.module1 as mod1

For more import patterns, see our Python Import Best Practices guide.

The __init__.py File

This special file can initialize your package. It runs when the package is imported. You can use it to:

- Set package-level variables

- Import key functions for easier access

- Execute setup code

Example __init__.py:

# mypackage/__init__.py
from .module1 import greet
from .module2 import calculate

__version__ = "1.0.0"

Relative Imports

Within packages, you can use relative imports. They help when modules need to import siblings.

Example of relative import:

# In module2.py
from .module1 import greet

The dot (.) means "current package". For complex cases, read our Python Import System Internals Explained.

Distributing Your Package

To share your package, create a setup.py file. This lets others install it with pip.

Basic setup.py example:

from setuptools import setup, find_packages

setup(
    name="mypackage",
    version="1.0.0",
    packages=find_packages(),
)

Install in development mode with:

pip install -e .

Best Practices

Follow these tips for better modules and packages:

- Use clear, descriptive names

- Keep modules focused on one purpose

- Document your code with docstrings

- Include a LICENSE file

- Add a README.md for documentation

Common Issues

Beginners often face these problems:

- Forgetting __init__.py in packages

- Circular imports between modules

- Incorrect PYTHONPATH settings

For solutions, check our Troubleshooting Python Import Errors guide.

Conclusion

Creating Python modules and packages is simple but powerful. It helps organize large projects and share code. Start with small modules and grow into packages as needed.

Remember to document your code and follow best practices. This makes your modules more useful to others and your future self.