RasPi Banner

Python Package Publishing Checklist

Here is our short checklist, on how to publish packages to PyPI and to Read the Docs.

We don't have the ambition to repeat the reasoning and tutorials for publishing a package. If you require details, we find the following tutorial to be an excellent overview of how things work: How to Publish an Open-Source Package to PyPi.

Pre-Requisites

  • Package Ready for Publishing (check the RealPython article above for details)
    • We recommend to develop your package in a virtual environment. Check our article Python Development Environment for details.
    • Apart from the installed libraries required for your package, install also Sphinx (to build and validate your documentation) and twine (to do the publishing part)
pip install sphinx
pip install twine

Publishing a Package

  • publish the latest source with updated metadata (version) to GitHub. It's a good idea to also create a release with the new version provided
  • navigate to your package root directory
  • build the package locally
python -m build
  • locate the generated files in dist and check name/version. There should be 2 files for your specific version: a .whl file and a .tar.gz file; note that on Windows, you'll see a .zip file instead.
  • test your package
    • open the .tar.gz with 7-zip or similar: check that it contains files you require in your package
    • run the test feature of twine
twine check dist/*
  • upload the package to Test PyPI and see if things work correctly. You will be asked for your username and password
twine upload --repository-url https://test.pypi.org/legacy/ dist/*
  • upload the package to PyPI. Please double check your test installation from the step above. There is little room for fixing the upload later. You will be asked for your username and password
twine upload dist/*
  • you can install your package now (from a different virtual environment for example), it is available to pip
pip install yourpackagename
  • Navigate to Read the Docs and follow the wizard to generate new documentation for your release

Tips

PyPi not showing images

When you publish your package to PyPi, images might not be showing. This happens for example, if your README file contains relative links towards images in your GitHub repository. The solution? PyPi will only understand proper URLs. So, save your repo to GitHub, grab the URL and change it in README.