How to write a Python module/package?

python

module-structure

best-practices

testing

byAlex Kataev·Nov 22, 2024

Kick-off a Python package by creating a directory that contains an __init__.py file. This turns a regular folder into a recognizable Python package and is where you can import methods for external use. Your Python code should be neatly tucked into .py files:

mymodule/
├── __init__.py
└── core.py

Fill core.py with your functions or classes:

def high_five():
    return "Give me five!"

Within __init__.py, pull in your code:

from .core import high_five

Now you can use your package like this:

from mymodule import high_five

Use setup.py to make your package shareable! It contains all the metadata about your package. Use setuptools and twine to package your module for distribution.

Proper file structure

Choose short, all-lowercase filenames for your modules. House related functions together to keep it straightforward. Keep everything tidy with docstrings that clarify what each module, class, or function does. If you're creating a larger package, use namespaces for better organization.

Dependencies and virtual environments

Before distributing your package, test it within an isolated virtual environment to pinpoint any undisclosed dependencies. Only after this should you place dependencies in setup.py.

Community best practices

Maintain a GitHub repository with a sensible .gitignore that can duck stuff you don't need in your repo. Include a LICENSE.txt file to set usage boundaries and create a README file to clue users in on what your module does.

Keep your code in check (unit testing)

Test your package in the local environment and on PyPI's test repository before uploading. Introduce unit testing with pytest to ensure that your functions are rock stars that perform well under pressure.

For the user

Ensure your package installs with just pip install. This way, getting up and running with your package is a breeze! For this to happen, manage dependencies thoughtfully and keep setup.py in top shape.