Packaging and Publishing Python Code



PyPI is the official third-party repository of Python software. At the time of this writing, PyPI already contains 95971 packages! 
pip uses PyPI as the default source for packages and their dependencies. So when you type:

 pip install package_name 

pip will look for that package in PyPI and, if found, will download and install the package on your local system.

In this article, I will show you how you can publish your own Python package to PyPI so that it can be installed on one line and easily accessible to all other Python users on the web! I`ll take an example of a sample package and show you the whole process. An example package is hosted at Github .

Step 1: Prepare Python Scripts

First step — this is of course preparing your Python program (which you want to publish to PyPI)!

This can be any python script. Here I am using my own Python script, which I named “ locator.py ” (I use this name for reference only. Feel free to save your Python scripts under any name.) This file is available here .

Step 2: Prepare the package directory structure

This is the most important step. Now we have to follow some predefined structure for our package directory. 
As a reference, feel free to check out the Github repository of the sample project used in this tutorial. You can clone this repository and make some changes to create your own package.

The directory structure should be like this:

Ok, let`s discuss what all these files will contain.

  • setup.py: this is the most important file. This is the file that configures various aspects of your project. The main feature of setup.py is that it contains a global setup () function. The key arguments to this function are how the specific details of your project are determined. 
    You will need to install this library setuptools using pip:
     pip install setuptools 

    This is what my setup.py looks like:

    from setuptools import setup

      
    # read long description from file

    with open ( `DESCRIPTION.txt` ) as file :

    long_description = file . read ()

      

      
    # specify your package requirements here

    REQUIREMENTS = [ `requests` ]

     
    # some more details

    CLASSIFIERS = [

      `Development Status :: 4 - Beta` ,

      ` Intended Audience :: Developers` ,

    `Topic :: Internet` ,

      ` License :: OSI Approved :: MIT License` ,

    `Programming Language :: Python` ,

    `Programming Language :: Python :: 2` ,

    `Programming Language :: Python :: 2.6` ,

    `Programming Language :: Python :: 2.7` ,

    `Programming Language :: Python :: 3` ,

    `Programming Language :: Python: : 3.3` ,

      `Programming Language :: Python :: 3.4` ,

      ` Programming Language :: Python :: 3.5` ​​ ,

    ]

     
    # call setup function

    setup (name = `mygmap` ,

      version = `1.0.0` ,

    description = `A small wrapper around google maps api` ,

      long_description = long_description,

      url = ` https://github.com/nikhilkumarsingh/mygmap ` ,

    author = `Nikhil Kumar Singh` ,

      author_email = `nikhilksingh97 @ gmail.com` ,

    license = `MIT` ,

      packages = [ `geo` ],

      classifiers = CLASSIFIERS,

      install_requires = REQUIREMENTS,

    keywords = ` maps location address`

    )

    Let`s see what the various arguments to the setup function do:

    1. name : This is the name of your project. Your package will be listed under this name in PyPI.
    2. version : This is a string where you can specify the current version of your project. 
      It is entirely up to you how you want to set the version series scheme (you can use "1.0" or "0.1" or even "0.0.1"). 
      This version shows up in PyPI for every release if you publish your project. Each time you download a new version, you will also need to change this argument.
    3. description: a short description of the package. You can use the long_description argument to write long descriptions.
    4. long_description: We can use rich text to better describe our files. The default file format is —  reStructuredText . You can take a look at DESCRIPTION.txt, to get an idea of ​​the syntax.
    5. URL: The home page URL for your project. This allows people to follow or contribute to your project.
    6. author, author_email: author details
    7. license: specify the type of license you are using.
    8. classifiers: is a list of strings in which we can specify more detailed information about our project, such as its development status, theme, license and supported Python version for your project. You can see more classifiers here .
    9. install_requires: it can be used to specify third party libraries that your package should run. These dependencies will be installed by pip when someone installs your package.
    10. keywords: a list of keywords to describe your project.

  • DESCRIPTION.txt : This file contains a detailed description of our package for display on the PyPI page. We are using the reStructuredText file format here. Check the file used in our package here .
  • LICENSE.txt : It is recommended to install a license to use your project. You can use any of the freely available templates. The most commonly used license is MIT
    The license I`m using for this project is available here . (You can change the author name to use this license in your projects)
  • README.md : This file has nothing to do with our PyPI package. It contains a description to display on the Github page. You can also use it for the PyPI page, but our code will need additional modifications. For now, let`s keep it simple.
  • __init__.py : Basic usage of __init__.py — python package initialization. 
    Including this file in a directory tells the Python interpreter that the directory should be treated as a Python package. 
    You can leave this file blank.

Step 3: Create your accounts
Now it`s time to create an account at PyPI and test PyPI . Test PyPI — this is just a test site that we will first upload our code to to see if everything is working correctly or not.

After creating the accounts, create this .pypirc file in your home directory system and enter your account credentials.

 [distutils] index-servers = pypi pypitest [pypi] repository = https://pypi.python.org/pypi username = your_username password = your_password [pypitest] repository = https://testpypi.python.org/pypi username = your_username password = your_password 

Note . If you are on a Windows system, simply enter echo% USERPROFILE% at the command line to find out your PC`s home directory. Place there .pypirc file.

Step 4: Download package

Finally, we are ready to upload our package to PyPI!

And you`re done! Your package is now publicly available on PyPI and can be easily installed with a simple pip command! 
The package we created with this tutorial is available here .

Just type in the terminal,

 pip install your_package_name 

check if the installation process completed successfully. 

Links:

This article contributed by Nikhil Kumar . If you like Python.Engineering and would like to contribute, you can also write an article using contrib.python.engineering, or email your article to [email protected] See my article appearing on the Python.Engineering homepage and help other geeks.

Please post comments if you find anything wrong or if you would like to share more information on the topic discussed above.