PyPI¶

Python is a language supported by an exceptionally large number of libraries. Some of them are included in the installation package, and the rest are ready to download if necessary. In the second group there are functionalities that allow e.g.:

• operate on data in formats such as .txt, .yml, .csv, .json or .xml,
• create network communication or set up servers,
• implement advanced artificial intelligence algorithms.

Everything described above and much more had to be written and shared globally with programmers. The global packet registry, which stores all external libraries, is Python Package Index, in short known as PyPI.

What is it PyPI?¶

Simply, PyPI is the place from which the programmer - using the pip install command, is able to download any library (of course if such a library exists). Formerly this register was known under the name Cheeseshop.

Since PyPI is a package registry from which you can download libraries, it is obvious that there must also be a way to put these external libraries in it. Interestingly, this is not only possible for a few - everyone has the opportunity to show off to the world their programming work by uploading their package on the server. Since registering your code in PyPI, we have made it available for download to developers from around the world.

Project registration in PyPI¶

We've created our perfect project. It works as it should, what's more - we decided to show it to the rest of Pythonists by sharing it in the PyPI registry. What you need to register your own package?

To register your package in PyPI you must first pack it properly.

You will need:

• library setuptools,
• file setup.py,
• file MANIFEST.in,
• file README,
• tool twine.

setuptools library¶

setuptools is a library that makes it possible to properly package a package and prepare it for sending to the server. According to the information on website, it makes it easy to download, build, install, update and remove python packages.

In setuptools there are several important functions that make package construction possible and easier:

• setup() - a function that collects information about a package and collects modules,
• find_packages() - function to search for python packages. It allows to specify which packages should go to the package and which should not. Default appends the entire directory (including subdirectories).

With functions from the setuptools library, they can be used in a special file called setup.py.

File setup.py¶

In setup.py file, being the entry to the script that builds the package that can be shared, it is necessary to call the two functions discussed above.

The main block is the setup function call with arguments determining project data and metadata. The most important informations about the created package are passed through arguments:

• name: parameter name (required!)

  It is the name under which our library will be visible in PyPI. Note: the name cannot cover another, with the same name; due to the large number of libraries in PyPI, sometimes it is not easy to find the right, unique name.

• version: parameter version (required!)

  Current package version; any versioning method: v.0.0.1, ver.01, etc.

• shared packages within the project: parameter packages (required!)

  These are packages created for our program that we want to include in the library before sending it to the server. Please note that if important source elements are omitted, the package after downloading by pip will not be able to work properly. Most often, the argument is the value returned by the function find_packages. You can use it to include or exclude selected packages. If you call the function without parameters, the entire directory will be included in the package from the level where the setup.py file is located.

  What is worth to remove from the project? For example, folders containing tests - no one needs to view them.

• license: parameter license,

• short description: parameter description

  A brief description summarizing the purpose and functionality of the created package.

• author: parameter author

  You can proudly enter your name, team or company name where the project was created.

• information about external libraries used in the project: parameter install_requires

  An important parameter. If our program is advanced, it probably uses the downloaded libraries and is unable to work without them. By providing a list with package names as this argument, we will contribute to the fact that if someone downloads our package and installs with the pip install command, other required libraries will also be automatically downloaded.

• information whether the project also contains other files besides sources in Python: parameter include_package_data.

Here is an example of the content of a file setup.py:

More about the library setuptools and the parameters of the setup function can be found in official documentation.

File MANIFEST.in¶

CSometimes it is important to attach files to the library that do not contain source code. Such files can be:

• text files with documentation,
• data files in various formats (.xml, .csv, .json),
• configuration files.

To inform the setup function from the setup.py file that there are files other than the .py extension that should be included in the package, you must create a file called MANIFEST.in. The file specifies the rules for attaching individual files using the include keyword.

The following screenshot illustrates how to attach to a project:

• README.rst file located in the same directory as MANIFEST.in,
• all text files from the docs directory,
• data.json file from the funniestcs directory.

The manifest file is essentially a table of contents. It is worth remembering that if a file is not found in it, it will not be accepted into the package. To tell the setup function to read this file, call it by adding an include_package_data=True argument.

File README¶

The README file is a place of friendly documentation of our program made available to anyone who wants to download our library. The good content of the file may encourage outsiders to reach for our product. When our package is registered in PyPI, it will get its own website, and its content will be the content of the README file. Due to the fact that the README file is not Python code, it must be included in the MANIFEST.in file.

README can be written in two formats:

• rst - reStructuredText - it will be called README.rst or
• md - Markdown - it will be called README.md.

Both formats allow you to create rich content and formatting - adding links, paragraphs, graphics, but Markdown is much more popular and is the recommended format.

Uploading file to PyPI¶

twine is a tool for publishing Python packages. If the package has a proper structure with all required files, it can be registered in PyPI.

An example of the root directory structure may look like the one below:

All required sources are in the top directory:

• file README,
• file setup.py,
• file MANIFEST.IN,
• proper python code.

Now all you have to do is register the project in PyPI using the twine tool.

Registering the package in PyPI¶

Registering a package (which already has the required structure) is a three-step process:

1. Creating an account on https://pypi.org/account/register/

2. Use the setuptools library in connection with the supplemented setup.py file and execute the command:

python setup.py sdist

• A package will be created ready to be sent to PyPI servers.
• The package will be saved in the dist directory and will have the format of an archive with the extension tar.gz.
• The package name will be the project name with the version suffix.

3. Having generated the package, you can share it globally with the twine tool, using the command:

twine upload dist/project_name-0.1.0.tar.gz

twine in the meantime asks for PyPI login details and if everything is okay send and register our package.

From now on, the project can be installed on any computer using the pip tool.