PackagingTemplate

A Python Packaging Example that prrrrrrrrsss...

... and can be used as a template

Tailoring the template to your needs

The boilerplate

First of all, exchange the package itself with your own one, that is, the entire kittykittykitty directory :)

• README.rst will be shown in the PyPI page and it written in reStructuredText. Since fewer people look at the PyPI page, this is not that important...

• requirements.txt must contain the packages needed by your module.

The important stuff

Let's take a look at the provided setup.py and point out which parts must be modified.

setup(name='kittykittykitty',
      version='1.0',
      description='A nice kitty for your terminal',
      classifiers=[
        'Development Status :: 4 - Beta',
        'License :: OSI Approved :: MIT License',
        'Programming Language :: Python :: 3',
        'Topic :: Artistic Software',
      ],
      entry_points = {
        'console_scripts': ['kitty-lulz = kittykittykitty.lulz:main'],
      },
      keywords='programming kitty lulz wat',
      url='https://github.com/carlosgprado/PackagingTemplate',
      author='Carl OS',
      author_email='carlos.g.prado@gmail.com',
      license='MIT',
      install_requires=[
        'colorama',
      ],
      extras_require={
        'dev': [
          'pytest',
          'pytest-pycodestyle',
          'sphinx_rtd_theme',
        ]
      },
      packages=['kittykittykitty'],
      include_package_data=True,
      zip_safe=False)

First the obvious ones: name, version, description, license must match your module. The keywords, url (optional), author, author_email can be anything you want, it's just metadata.

The less obvious ones follow:

• classifiers: this is metadata for PyPI, kind of tags to index your package more efficiently. Be aware that these strings are not free form, there are a limited amount of them listed here

• install_requires: this is a list of Python packages, essentially replicating your requirements.txt

• extras_require: is a dictionary containing extra (optional) packages installed. The most common case for this is to specify additional packages for developing, not just using, the package. To instruct pip to install these, use $ pip install .[dev], where dev is the corresponding dictionary key.

• packages: this one is very important, specifies the package names to be installed. If omitted, no packages will be installed.

• entry_points: the most common use of this is to specify command line applications, see here

Installing

Once we have our package ready, we can install it using pip this way:

$ cd <your_package>
$ pip install .

if you want to install the package in development mode, you would use:

$ pip install -e .[dev]

This will install additional dependencies used for development (testing, linters, etc.) and create symbolic links in your Python installation instead of copying the package contents. This way you don't need to install the package every time you make a change.

After installing our example package, its contents and associated metadata can be found in the Python installation:

Directory: C:\Python36x64\Lib\site-packages\kittykittykitty

Mode                LastWriteTime         Length Name
----                -------------         ------ ----
d-----       03.12.2019     22:32                __pycache__
-a----       03.12.2019     22:32           1635 lulz.py
-a----       03.12.2019     22:32              0 __init__.py


Directory: C:\Python36x64\Lib\site-packages\kittykittykitty-1.0.dist-info


Mode                LastWriteTime         Length Name
----                -------------         ------ ----
-a----       03.12.2019     22:32             58 entry_points.txt
-a----       03.12.2019     22:32              4 INSTALLER
-a----       03.12.2019     22:32           1075 LICENSE
-a----       03.12.2019     22:32            656 METADATA
-a----       03.12.2019     22:32            973 RECORD
-a----       03.12.2019     22:32             16 top_level.txt
-a----       03.12.2019     22:32             98 WHEEL

Remember the entry_points setting for a command line application? The following script has been created and stored here: c:\python36x64\scripts\kitty-lulz.exe

Uploading to PyPI

NOTE: before starting you will need to create an account on PyPI here

Finally we can upload our package to PyPI. This is done in two steps: create a binary and source distribution of our package and the actual upload.

Creating the distribution

Make sure you have the setuptools and wheel packages installed (you probably have already).

$ pip install --user --upgrade setuptools wheel

Then run the following command:

$ python setup.py sdist bdist_wheel

This will create a source and a binary build on the dist directory.

Uploading the distribution

Make sure you have the twine package installed.

$ pip install --user --upgrade twine

Then use the twine command this way:

$ twine upload dist/*

You will need to enter your username and password for PyPI and that's it!