👋 About the project

Have you ever dreamed of contributing to the development of your favorite language?

If so, you’ve come to the right place!

Indeed, it’s not uncommon to come up against a problem that requires hours of research when working on a project. Fortunately, these hours of development can be shared to make life easier for everyday language users.

In this article, I’ll do my best to keep things simple for the most novice of you, so that anyone can share their research with the world through a Python library!

Are you ready? Let's get started!

📦 Creating the package structure

This tutorial will uses a simple project named “mypackage”.

You can use any name for your project, as long as it’s not already in use by another Pypi user.

💡 To find out whether your package name is available, please search for it directly on Pypi at the following address : https://pypi.org/

🚀 Project components

In this project we will use different directories and files necessary to compile your :

  • LICENCE : This file contains the license you wish to use in your project. There are a multitude of them, so I’ll let you do your own research on the subject! (We’ll talk more about this in the licensing section).
  • pyproject.toml : This file allows you to configure your compilation process
  • README.md : Documentation of your research on the subject, and how it works. Also visible on Pypi when the package is published.
  • setup.cfg : This file allows you to configure your project metadata, which will be displayed on the Pypi website.
  • src/mypackage : This directory will contain all your function files. We’ll also use a __init__.py file that allows it to access your functions directly from the root.
  • tests/ : The test directory, where you can create and use test functions.

👷 Global architecture

python_package/
├── LICENSE
├── pyproject.toml
├── README.md
├── setup.cfg
├── src/
│   └── mypackage/
│       ├── __init__.py
│       └── example.py
└── tests/

(back to top)

🧾 Configuring your metadata

⚙️ Pyproject.toml

In this section, you’ll choose your backend for compiling your project.

To put it simply: This part will enable you to determine how the compiler will understand your metadata and source files, so as to extract the information required for compilation.

In this example, we’ll use setuptools, capable of interpreting your [project] metadata and integrating it directly into your Pypi library.

💡 - There are a multitude of backends for compiling your project.
For the more advanced, I’ll leave it to you to do your own research on the subject, so that it corresponds as closely as possible to your needs!

We will use two main elements in this section:

  • requires : This section lets you specify the various libraries external to your project that are necessary for it to function properly. You can add as many libraries as you like, as long as you respect the import format. (You can specify a specific version of the project by indicating the following element after your lib ”>=x.x”).

    Example : requires = [“setuptools>=61.0”, “YourExternalLib”, …].

💡 - The libraries specified in this table will be automatically installed when your package is installed.

  • build-backend : Element you’ll use to compile the file. By default, use “setuptools.build_meta ”.

💡 - For the more advanced: You can specify the file to be compiled directly in this section. Please refer to this article on PEP 517 !

Finally, your file will look like this:

[build-system]
requires = ["setuptools>=61.0", "wheel"]
build-backend = "setuptools.build_meta"

(back to top)

⚙️ Setup.cfg

In this section, you will fill in the information that will be used to present your package on the Pypi! website.

Nothing could be simpler: Follow the variable names and enter your information in the [metadata] section.

The other two sections are as follows:

  • [options] : Package_dir is used to specify the directory to be compiled, containing the files in which your functions are stored.
    Packages = find: allows you to list your external packages, so that you can install them at the same time as your own package to ensure it runs smoothly.
    python_requires = >=3.9.5 allows you to choose a specific version of python from which your package is guaranteed to work.

  • [options.packages.find] is a complement to the “find:” option mentioned above, specifying the directory to be scanned in order to retrieve library imports.

[metadata]
name = mypackage
version = 0.0.1
author = Your name
author_email = YourEmail@example.com
description = Your (small) description
long_description = file: README.md
long_description_content_type = text/markdown
url = https://github.com/YourAccount/YourRepository
project_urls =
    Bug Tracker = https://github.com/YourAccount/YourRepository/issues
classifiers =
    Programming Language :: Python :: 3
    License :: OSI Approved :: <Your license>
    Operating System :: OS Independent

[options]
package_dir =
    = src
packages = find:
python_requires = >=3.9.5

[options.packages.find]
where = src

(back to top)

📝 Creating your documentation

Open README.md and enter the following content. You can customize this as you want, let your imagination flow !

💡 - If you’re not familiar with Markdown, here’s a Cheat Sheet that might come in handy!

# My package

This is a simple example package. 

to write your content.

(back to top)

✍️ Select your Licence

Open LICENCE.txt and paste the licence of your choice.

All development projects have a distribution license. This file allows you to specify whether your project is royalty-free, whether you can use it for free without modifying it, etc…

Generally speaking, we use the MIT license, which is simple and permissive, allowing people who install your package to use it, modify it and market it if need be.

💡 - If you’re not familiar with distribution licenses, here’s a site that lists licenses by need!

MIT License

Copyright (c) [year] [fullname]

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in 
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

(back to top)

🔨 Create your distribution archives

The next step is to generate distribution packages for the package. These are archives that are uploaded to the Python Package Index and can be installed by pip.

Make sure you have the latest version of build installed:

python -m pip install --upgrade build

⚙️ Building your archive

This command should output a lot of text and once completed should generate two files in the dist directory (automaticaly generated by the command):

💡 - Make sure you run this command in the same directory as your pyproject.toml file.

python -m build

After running this command, you should see a new directory in your project root containing your archive and the whl file used for uploading to Pypi.

dist/
├── mypackage-0.0.1-py3-none-any.whl
└── mypackage-0.0.1.tar.gz

(back to top)

✈️ Uploading the distribution archives

You’re almost there!

You can now create your account on TestPypi!

When you have finished registering, you can go to this link to create your API Token, which will be required to host your package.

⚠️ - Don’t close the page until you have copied and saved the token, you won’t see that token again !

Now that you’ve got your environment ready, you can take the plunge and host your first lib !

pip install twine
# or
pip install --upgrade twine

📡 Upload to TestPypi

First, you can test your package on the Pypi test servers. To do this, you’ll need to use the following command, which will allow you to take the entire contents of your dist directory and send it as a package:

💡 - In this step, your order guest will ask you for a username and password. You can enter the following information: For the username __token__ and for the password, use the token value, including the pypi- prefix.

twine upload --repository testpypi dist/*

Normally, if all goes well, you should have a link in your command prompt that redirects you to your librarie! (The line for installing your librarie will be updated in the production version of Pypi, so don’t worry!)

📡 Upload to Pypi

In the same way as for the Pypi Test version, you can upload your package to the Pypi production servers (ideally, after you’ve tested and verified it)!

twine upload dist/*

At this point, the tutorial is over! That’s it, your first librarie is online !

CONGRATULATIONS 🎉

(back to top)

⬇️ Installing your uploaded package

You can use pip to install your package and verify that it works !

💡 You can create a virtual environment and install your package from TestPyPI

# On TestPypi
pip install --index-url https://test.pypi.org/simple/ --no-deps mypackage

# On Pypi
pip install mypackage

You can now use your own package in your python files, Enjoy 😉 !

from mypackage import *

(back to top)