Problem:
You have created some code that solves a specific problem and think others probably have the same problem. To help them you want to create and publish your own python package that can be installed with pip. But you don’t know how?
Solution:
To create your own python package you need to do the following steps:
- Register on PyPi.org
- Install requirements
- Setup folder structure
- Compile your package
- Test on your local machine
- Upload
Register on PyPi.org
Many packages are hosted on pypi.org. To be able to easily share your package and give others the option to install it like any other package, you need to host it on PyPi.
To be allowed to do so you need to register there. Jump to https://pypi.org/account/register/, register your account and finish the email validation.
Install requirements
Setuptools: The standard package development process library for python
Wheel: The package to create the .whl files that pip installs.
Twine: Have a secure, authenticated, and verified connection with pypi.org for uploading your package.
Tqdm: Progress meter internally used by Twine
To install them run:
python -m pip install –upgrade pip setuptools wheel
python -m pip install tqdm
python -m pip install –upgrade twine
You can run this in your virtualenv if you want and don´t need to handle system or user level problems.
Setup folder structure
To use the best practice from https://packaging.python.org/tutorials/packaging-projects/, create a main folder for your project, e.g. my-package.
Change into the directory, with cd my-package
Inside of it create the following files:
LICENSE
README.md
setup.py
In the same folder create the subfolders:
tests
my-package
Finally create a file __init__.py inside of my-package\my-package. This will contain (some of) your source code.
LICENSE
Go to https://choosealicense.com/ and select a license. Then copy the provided license text into your LICENSE file. That´s it.
README.md
This file can contain the longer explanation and examples for your code in MarkDown. Fill as required.
setup.py
This file describes the details of your package, requirements, category, etc. It is equivalent to package.json for nodejs.
The following template is a copy with many thanks from https://packaging.python.org/tutorials/packaging-projects/ :
import setuptools
with open("README.md", "r", encoding="utf-8") as fh:
long_description = fh.read()
setuptools.setup(
name="example-pkg-YOUR-USERNAME-HERE", # Replace with your own username
version="0.0.1",
author="Example Author",
author_email="[email protected]",
description="A small example package",
long_description=long_description,
long_description_content_type="text/markdown",
url="https://github.com/pypa/sampleproject",
packages=setuptools.find_packages(),
classifiers=[
"Programming Language :: Python :: 3",
"License :: OSI Approved :: MIT License",
"Operating System :: OS Independent",
],
python_requires='>=3.6',
)
Fill in your data.
Author and author email need to match your PyPi.org account. Link it to your hosting.tests
This folder will contain the different ci/cd tests for your code. In the beginning it´s probably emptry.
my-package/__init__.py
This file will contain the part of your code that you want to expose, the functions you want the user to be able to call directly from your package.
It´s the entry point to your code, think def main().
Your remaining code will find it´s place inside my-package and subfolders.
final directory structure (user test and home directory in /home: /home/test as base):
/home/test/my-package/
/home/test/my-package/my-package/
/home/test/my-package/my-package/__init__.py
/home/test/my-package/setup.py
/home/test/my-package/LICENSE
/home/test/my-package/README.md
/home/test/my-package/tests/
Compile your package
To compile your package into a .whl file, execute:
python setup.py bdist_wheel
Test on your local Machine
To test your package before you upload, install it with:
python -m pip install dist/my-package*
Look into the dist folder and get the correct naming. It depends on the data you supplied setup.py.
Upload
As preparation for the upload of the package, you need to create a ~/.pypirc (in your home directory, not the local package directory)
Add this content inside of it (adjust username):
[distutils]
index-servers=pypi
[pypi]
repository = https://upload.pypi.org/legacy
username = my_pypi_username
Now run
python -m twine upload dist/*
It may ask you for your pypi.org password. In that case please enter it.
Result
You now have created your own python package. And if someone wants to use it, they can run pip install $yourPackageName as they are used to.
Try it!
Let me know when it helped you.
Best,
Frank
Sources:
https://docs.saleor.io/docs/developer/running-saleor/emails/
https://packaging.python.org/tutorials/packaging-projects/
https://betterscientificsoftware.github.io/python-for-hpc/tutorials/python-pypi-packaging/
