Publish your python package to PyPi so the world can import your package in their project.
Thousands of libraries created by diligent devs make Python project easy to start, and as a Python player, I use pip install
and import
thousands times a year.
Recently I create a simple plugin and want to publish it to PyPi, because may be someone would find it helpful.
I find this official instruction helpful on how to packaging a project.
Initially my project structure looks like this:
1 |
|
I’d like to publish my child class MyAppPlugin as my-app-plugin, therefore anyone want to use the package simply run pip install my-app-plugin
and add import MyAppPlugin
in their Python file.
To create the package, a folder with a __init__.py file is first created to wrap the module:
1 |
|
To make the package import controlled by __init__.py and prevent direct import of the modules, a prefix underscore is added to MyAppPlugin.
The import statement uses the following convention: if a package’s __init__.py code defines a list named __all__, it is taken to be the list of module names that should be imported when from package import * is encountered.
In short, __init__.py controls what content to exports, it can be empty (means export all as default).
The Python 3 document for packages provides more information.
1 |
|
Setuptools is a collection of enhancements to the Python distutils that allow developers to more easily build and distribute Python packages, especially ones that have dependencies on other packages.
setup.py is the script used to install the package, it has the information about the package like author, version, dependencies. It usually contains a setup function.
The setup function can be imported from two packages, setuptools or distutils.core. I prefer setuptools.setup.
Setuptools is a collection of enhancements to the Python distutils that allow developers to more easily build and distribute Python packages, especially ones that have dependencies on other packages.
1 |
|
1 |
|
It is just an example, the document of setuptools describes the usage in detail.
In some simple project it is okay to hard code the version string in the setup.py like the above code snippet. However, if the version string is used in multiple places, it will be difficult to change them later one by one. In practice, a file, usually named version.py or _version.py, which declares version as a global variable, is often used. Any module, including setup.py, import the version string from this version file. By using this technique, when the version changes only the version file needs to be modified.
1 |
|
1 |
|
1 |
|
Make the project friendly by creating a well structured README or wiki.
I generally include the following section in a README file:
Frankly speaking, I am still struggled to write a document for my project, because I am the the developer who know the it too well to imagine what a user would encounter when attempt to use the tool for the first time.
Use Choose an open source license to help decide which license to use.
Constructing tests is exhausting, and it usually takes even more time. However, it helps you to deliver your code with confident, without diving to debug-fix loop again and again for each update. Plus watching the green ticks is pure satisfaction. ✅
I use unittest in Python and keep all my test instances under tests folder.
1 |
|
1 |
|
Now run this command from the same directory where setup.py is located:
1 |
|
Now you will have a dist folder contains a .whl file and a tarball.
You can try distribution tools and processes without affecting the real index on TestPyPI.
Create a PyPI account at Python Package Index, if you don’t have one yet.
Install twine, it’s the tool used for uploading.
1 |
|
Upload to TestPyPI:
1 |
|
The username and the password will be prompted.
After uploading to TestPyPI, the package can be installed by using the following command:
1 |
|
After test the package on TestPyPI, now it’s time to bring it to the real world.
Create a PyPI account at Python Package Index, if you don’t have one yet.
1 |
|
Enter your username and password for pypi.org and complete the upload.
Congratulations, you have successfully published your python package.