Creating a Python Package
Create a Python Package
Creating a Python package is a great way to organize your code and make it reusable across different projects. A package is a collection of modules that can be imported and used in other programs. In this tutorial, we will go through the steps of creating a Python package.
What are we going to do?
- Create a package (with a setup.py script)
- Make it available on PyPI
What does this do?
- Allows us to easily install a Python script from a distribution:
1
python3 setup.py install
- Or install it from the Internet:
1
pip install package_name
What are we going to use?
- Python 3 (it’s nearly the same for Python 2)
- distutils (packaging framework)
- setuptools (Python Packaging Authority enhanced alternative)
- PyPI (Python Package Index)
Getting Started
Directory Structure
Simple Mode
If you have a simple tool with only 1 Python script file, you can place the .py
script file under the root folder.
1
2
3
4
5
└── example
├── example.py
├── LICENCE
├── README.md
└── setup.py
Lib Mode
If you have a more complex tool with several Python script files, place the .py
script files under a “lib” folder.
1
2
3
4
5
6
7
8
└── example
├── example
│ ├── __init__.py
│ ├── script.py
│ └── main.py
├── LICENCE
├── README.md
└── setup.py
Make sure to include a __init__.py
file.
Setup Script
- The distutils setup script is a Python script!
- Keep it simple to avoid bugs; exoticism is not needed.
- It describes the project’s metadata.
The First Line
The first line of the distutils setup script will always be the same:
1
from distutils.core import setup
This imports the setup()
function, which takes some parameters.
Minimal Parameters
Only 3 fields are required:
- name: must be unique to publish on PyPI
- version: keeps track of different releases
- url: the home page address of the project (e.g., GitHub, Bitbucket, website, PyPI page, …)
Other Parameters
You can add additional parameters to the setup script:
- description: one-line summary of the project
- long_description: multi-line string in reStructuredText (PyPI converts it to HTML and displays it on the package page)
- author: author name
- author_email: author email
- maintainer: maintainer name
- maintainer_email: maintainer email
- license: license name
- keywords: keywords
- classifiers: list of PyPI categories (more details later)
Differentiate the source code from other files using:
- py_modules or packages: describes where the Python source code is located
- py_modules: for a single-file Python script
- packages: for a multi-file Python script
Additional metadata can be found in the Python documentation.
To classify the package, use the classifiers
parameter of the setup()
function. This contains a list of strings. All classifier strings must match the PyPI classifiers list.
Manifest
By default, Distutils only includes certain files in the release package. To include additional files (e.g., LICENCE
, NOTICE
, README.md
, or a docs/
documentation folder), create a MANIFEST.in
file in the project’s root directory.
The Manifest file is not a Python script and allows you to include or exclude files and directories. It maintains the directory structure.
Setup.cfg
If you’re using a Markdown readme file, create a setup.cfg
file in the project’s root directory. This file is not a Python script. It allows you to specify the path to the README.md
file.
Checking the Setup Script
Distutils has a built-in validation command:
1
python3 setup.py check
Creating a Source Distribution
To create a source distribution containing the source code, setup script, README file, and additional files from the MANIFEST, run the following command:
1
python3 setup.py sdist
This will create a dist/
folder in your project directory with a package_name.tar.gz
archive inside it (or a .zip
file for Windows users).
PyPI
PyPI is the Python Package Index, which contains thousands of Python libraries and tools. Publishing your package on PyPI allows easy distribution and installation.
To make it easier to upload packages, create a ~/.pypirc
file in your home directory with your PyPI account information.
Register the Package
To register the package project, run the following command:
1
python setup.py register -r pypi
Upload the Package
To upload the package distribution, run the following command:
1
python setup.py sdist upload -r pypi
You can also upload the package to PyPI’s test server first:
1
2
python setup.py register -r pypitest
python setup.py sdist upload -r pypitest
Git Tips
If your package’s source code is hosted on a Git repository:
- Use a
.gitignore
file to avoid uploading unnecessary files (e.g.,dist/
orbuild/
folders) to the remote Git repository. - If your Git remote repository is GitHub, you can use
git tag
to generate and host the package:1 2
git tag 0.1 -m "message" git push --tags origin master
Conclusion
In this tutorial, we learned how to create a Python package. We also learned how to make it available on PyPI. We hope you found this tutorial helpful. If you have any questions, please feel free to reach out to us on Twitter.