Skip to content

Python module creation

Package creation

To make a package publish-ready, there are a few steps to follow.

  • Creating a README (not required, but you'll want that)
  • Creating __init__.py module declaration files
  • Creating the setup files

I'll use the following package structure as example.

1
2
3
4
5
.
├── my_package
│   ├── __init__.py
│   └── module.py
└── README.md

Creating the README

This is self-explanatory, document your module as much as you can.

Creating the __init__.py module declaration files

There is a nice constant we can define in our init file, which will automatically include every module file and folder.

I'm talking about __all__, which is expected to be an array containing the file and folder names (without the .py extension, for files).

Here, we want to automatically import my_package.module when we do import my_package.

1
2
3
__all__ = [
    'module'
]

It is also the place in which you'd want to initialize your module-specific stuff.

Creating the setup files

We'll need two files:

  • setup.cfg, which holds some metadata pieces
  • setup.py, which holds the package setup script
1
2
[metadata]
description-file=README.md
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
import setuptools

with open("README.md", "r") as f:
    long_description = f.read()

setuptools.setup(
    name="your package name (slug)",
    version="your package version",
    author="your username",
    author_email="your email",
    url="the repository url",
    long_description=long_description,
    long_description_content_type="text/markdown",
    packages=setuptools.find_packages(),
    classifiers=[
        "some classifiers", # see https://pypi.org/classifiers/
    ]
)

To specify pypi dependencies, you simply add the install_requires keyword argument, which expects a list of every required pypi package.

To specify a package which is not hosted on a pypi-compatible server (e.g. basic HTTP file), you simply add the dependency_links keyword argument, which expects a direct link to the setuptools-built tarball.

Build

To build the package, first make sure that your dist folder is empty, or simply remove it, to avoid conflicts on push.

Once it's done, run the command python setup.py sdist bdist_wheel to build the pakcage.

Publish

To publish it, you need the twine python package.

To use it, you run twine upload dist/*.

To point to a custom repository URL, use --repository-url.