This repository contains a basic python package example with the aim of showing how a good python package should look like.
Install:
pip install helloworld-mkmenta
Install locally:
git clone https:/mkmenta/python-package-example.git
cd python-package-example
pip install -e .
You will find an usage example here.
This project has a documentation in readthedocs.io generated using sphinx
: documentation.
Find the tutorial on how it was created here.
To install the package along with the tools you need to develop it run the following (local installation with the "dev"
extras:
git clone https:/mkmenta/python-package-example.git
cd python-package-example
pip install -e ."[dev]"
Why install the package in editable mode (-e
option)?
Without the editable mode, the package is first built and then installed. This means that any change in the code would
require to re-install the package (i.e. run pip install ."[dev]"
). With the editable mode instead of building and
installing the package the code is "linked", so all the updates in the code are automatically applied everywhere.
The requirements needed to run the package should go in the install_requires
argument of setup()
in the setup.py
.
The requirements needed to develop the package should go in the extras_require
argument dict (under the "dev"
key) of setup()
in the setup.py
.
This is preferred to a requirements.txt
file, because this is code and it can be understood directly during the installation of the package itself.
The requirements.txt
should be used to recreate enviroments with specific versions (e.g.requests==2.22.0
), not to share software.
Build without install i.e. build wheel:
python3 setup.py bdist_wheel
Source distribution:
python3 setup.py sdist
For the source distribution, remember to:
- Check out the warnings of
python3 setup.py sdist
. - Check that every file from the repo is packed in the tar file (
tar tzf dist/helloworld-X.X.X.tar.gz
) as written in theMANIFEST.in
. A useful tool ischeck-manifest
.
python3 setup.py bdist_wheel sdist
twine upload dist/*
In order to check the code format and test it, this project runs a GitHub action defined in .github/workflows/main-action.yml
.
You can check the execution of this action here.
This allows blocking any merge of a pull request if the code is not correcly formatted or tests are not passing. In order to do that you can go to Settings -> Branches -> Add rule
- This repo is prepared for PyCharm and it has some run configurations (in
.idea/runConfigurations
).
- Mark Smith - Publish a (Perfect) Python Package on PyPI (video)
.gitignore
file from https://gitignore.io/- License from https://choosealicense.com/
- PyPI classifiers from https://pypi.org/classifiers/
- Autodocumenting your Python code with Sphinx( part1 part2) )
- A Simple Tutorial on How to document your Python Project using Sphinx and Rinohtype ( post )