Do you’ve gotten a Python bundle that you just’d wish to share with the world? It’s best to publish it on the Python Package deal Index (PyPI). The overwhelming majority of Python packages are revealed there. The PyPI workforce has additionally created intensive documentation that can assist you in your packaging journey. This text doesn’t purpose to exchange that documentation. As an alternative, it’s only a shorter model of it utilizing ObjectListView for instance.
The ObjectListView challenge for Python relies on a C# wrapper .NET ListView however for wxPython. You employ ObjectListView as a substitute for wx.ListCtrl as a result of its strategies and attributes are easier. Sadly, the unique implementation died out in 2015 whereas a fork, ObjectListView2 died in 2019. For this text, you’ll find out how I forked it once more and created ObjectListView3 and packaged it up for PyPI.
Making a Package deal Construction
Whenever you create a Python bundle, you need to comply with a sure sort of listing construction to construct all the pieces appropriately. For instance, your bundle recordsdata ought to go inside a folder named src. Inside that folder, you’ll have your bundle sub-folder that accommodates one thing like an __init__.py and your different Python recordsdata.
The src folder’s contents will look one thing like this:
package_tutorial/ | -- src/ | -- your_amazing_package/ | -- __init__.py | -- instance.py
The __init__.py file might be empty. You employ that file to inform Python that the folder is a bundle and is importable. However wait! There’s extra to making a bundle than simply your Python recordsdata!
You additionally ought to embody the next:
- A license file
- The
pyproject.tomlfile which is used for configuring your bundle whenever you construct it, amongst different issues - A
README.mdfile to explain the bundle, methods to set up it, instance utilization, and many others - A
checksfolder, when you’ve got any (and it is best to!)
Go forward and create these recordsdata and the checks folder. It’s okay if they’re all clean proper now. At this level, your folder construction will seem like this:
package_tutorial/ | -- LICENSE | -- pyproject.toml | -- README.md | -- src/ | -- your_amazing_package/ | -- __init__.py | -- instance.py | -- checks/
Selecting a Construct Backend
The packaging tutorial mentions that you could select numerous construct backends for whenever you create your bundle. There are examples for the next:
- Hatchling
- setuptools
- Flit
- PDM
You add this construct data in your pyproject.toml file. Right here is an instance you would possibly use in case you picked setuptools:
[build-system] requires = ["setuptools>=61.0"] build-backend = "setuptools.build_meta"
This part in your config is utilized by pip or construct. These instruments don’t truly do the heavy lifting of changing your supply code right into a wheel or different distribution bundle. That’s dealt with by the construct backend. You don’t have so as to add this part to your pyproject.toml file although. You will discover that pip will default to setuptools if there isn’t something listed.
Configuring Metadata
All of the metadata to your bundle ought to go right into a pyproject.toml file. Within the case of ObjectListView, it didn’t have one among these recordsdata in any respect.
Right here’s the generic instance that the Packaging documentation provides:
[project]
title = "example_package_YOUR_USERNAME_HERE"
model = "0.0.1"
authors = [
{ name="Example Author", email="author@example.com" },
]
description = "A small instance bundle"
readme = "README.md"
requires-python = ">=3.8"
classifiers = [
"Programming Language :: Python :: 3",
"License :: OSI Approved :: MIT License",
"Operating System :: OS Independent",
]
[project.urls]
Homepage = "https://github.com/pypa/sampleproject"
Points = "https://github.com/pypa/sampleproject/points"
Utilizing this as a template, I created the next for the ObjectListView bundle:
[project]
title = "ObjectListView3"
model = "1.3.4"
authors = [
{ name="Mike Driscoll", email="mike@somewhere.org" },
]
description = "An ObjectListView is a wrapper across the wx.ListCtrl that makes the listing management simpler to make use of."
readme = "README.md"
requires-python = ">=3.9"
classifiers = [
"Programming Language :: Python :: 3",
"License :: OSI Approved :: MIT License",
"Operating System :: OS Independent",
]
[project.urls]
Homepage = "https://github.com/driscollis/ObjectListView3"
Points = "https://github.com/driscollis/ObjectListView3/points"
Now let’s go over what the varied components are within the above metadata:
- title – The distribution title of your bundle. Be sure your title is exclusive!
- model – The bundle model
- authors – A number of authors together with emails for every
- description – A brief, one-sentence abstract of your bundle
- readme – A path to the file that accommodates an in depth description of the bundle. Chances are you’ll use a Markdown file right here.
- requires-python – Tells which Python variations are supported by this bundle
- classifiers – Provides an index and a few metadata for pip
- URLs – Additional hyperlinks that you just wish to present on PyPI. Generally, you’ll wish to hyperlink to the supply, documentation, situation trackers, and many others.
You’ll be able to specify different data in your TOML file in case you’d like. For full particulars, see the pyproject.toml information.
READMEs and Licenses
The README file is nearly all the time a Markdown file now. Check out different standard Python packages to see what it is best to embody. Listed here are some beneficial objects:
- The best way to set up the bundle
- Fundamental utilization examples
- Hyperlink to a information or tutorial
- An FAQ when you’ve got one
There are various licenses on the market. Don’t take recommendation from anybody; purchase a lawyer on that until quite a bit about this matter. Nonetheless, you may take a look at the licenses for different standard packages and use their license or one related.
Producing a Package deal
Now you’ve gotten the recordsdata you want, you’re able to generate your bundle. You will want to be sure you have PyPA’s construct put in.
Right here’s the command you’ll want for that:
python3 -m pip set up --upgrade construct
Subsequent, you’ll wish to run the next command from the identical listing that your pyproject.toml file is in:
python3 -m construct
You’ll see a bunch of output from that command. When it’s finished, you’ll have a dist A folder with a wheel (*.whl) file and a gzipped tarball inside it’s known as a constructed distribution. The tarball is a supply distribution , whereas the wheel file known as a constructed distribution. Whenever you use pip, it can attempt to discover the constructed distribution first, however pip will fall again to the tarball if vital.
Importing / Publishing to PyPI
You now have the recordsdata you have to publish to share your bundle with the world on the Python Package deal Index (PyPI). Nonetheless, you have to register an account on TestPyPI first. TestPyPI is a separate bundle index supposed for testing and experimentation, which is ideal when you’ve gotten by no means revealed a bundle earlier than. To register an account, go to https://check.pypi.org/account/register/ and full the steps on that web page. It should require you to confirm your e-mail tackle, however apart from that, it’s a really easy signup.
To securely add your challenge, you’ll want a PyPI API token. Create one out of your account and ensure to set the “Scope” to the “Total account”. Don’t shut the web page till you’ve gotten copied and saved your token otherwise you’ll must generate one other one!
The final step earlier than publishing is to put in twine, a software for importing packages to PyPI. Right here’s the command you’ll must run in your terminal to get twine:
python3 -m pip set up --upgrade twine
As soon as that has completed putting in, you may run twine to add your recordsdata. Be sure to run this command in your bundle folder the place the brand new dist folder is:
python3 -m twine add --repository testpypi dist/*
You will note a immediate to your TestPyPI username and/or a password. The password is the API token you saved earlier. The instructions within the documentation state that it is best to use __token__ as your username, however I don’t suppose it even requested for a username once I ran this command. I consider it solely wanted the API token itself.
After the command is full, you will notice some textual content stating which recordsdata have been uploaded. You’ll be able to view your bundle at https://check.pypi.org/challenge/example_package_name
To confirm you may set up your new bundle, run this command:
python3 -m pip set up --index-url https://check.pypi.org/easy/ --no-deps example-package-name
In case you specify the proper title, the bundle ought to be downloaded and put in. TestPyPI is just not meant for everlasting storage, although, so it can probably delete your bundle ultimately to preserve house.
When you’ve gotten totally examined your bundle, you’ll wish to add it to the true PyPI website. Listed here are the steps you’ll must comply with:
- Choose a memorable and distinctive bundle title
- Register an account at https://pypi.org. You’ll undergo the identical steps as you probably did on TestPyPI
- Remember to confirm your e-mail
- Create an API key and reserve it in your machine or in a password vault
- Use twine to add the dist folder like this:
python -m twine add dist/* - Set up the bundle from the true PyPI as you usually would
That’s it! You’ve simply revealed your first bundle!
Wrapping Up
Making a Python bundle takes time and thought. You need your bundle to be straightforward to put in and straightforward to grasp. Remember to spend sufficient time in your README and different documentation to make utilizing your bundle straightforward and enjoyable. It’s not good to lookup a bundle and never know which variations of Python it helps or methods to set up it. Make the method straightforward by importing your bundle to the Python Package deal Index.
