Tag: packaging

At Blackpool Raspberry Jam today, I taught @all_about_code the basics about turning his EduPython Python module into a Python Package on PyPi. This guide is written assuming you are using Python 3 under Raspbian or Debian Jessie.

Here is the ‘Hello, World’ of Python Packaging guides:

• Make sure your module contains docstrings for every function, and for the module itself.  This is very useful for many reasons as we will see later – after all people need to know how to use your Python module.
• Create a directory for your package which will contain the following files:

mypackage/
   README.txt
   LICENCE.txt
   CHANGELOG.txt
   MANIFEST.in
   setup.py
   mymodule/
      __init__.py

• Choose a licence for your module.  (For American readers, note that in the USA you spell it ‘license’ instead).  Store a copy of your licence in the file LICENCE.txt.  There are many licences to choose from, but my personal favourite is the MIT licence because it does not have many restrictions and it is simple.  Other suitable licences for Python modules would be BSD, Apache or LGPL.  I would not use the GPL licence for a Python package because any projects that use it are forced to use the GPL licence too.  This may prevent some people from being able to use your library.
• Create a README.txt file containing a summary of what your Python package is all about
• Create a CHANGELOG.txt file to list all the changes in every release of your package.  That way when you release the next version, people will know what has changed. Here is a simple template to start with:

Change Log
==========

0.0.1 (dd/mm/yyyy)
------------------
- First release

• Create a MANIFEST.in file containing the following – this tells the Python packaging mechanism which files belong to your package:

global-include *.txt *.py

• Create a setup.py file.  This is a script that is used to compile your package and submit it to PyPi.  Here is a very simple example:

"""
Your licence goes here
"""

from setuptools import setup, find_packages

# See note below for more information about classifiers
classifiers = [
  'Development Status :: 5 - Production/Stable',
  'Intended Audience :: Education',
  'Operating System :: POSIX :: Linux',
  'License :: OSI Approved :: MIT License',
  'Programming Language :: Python :: 2.7',
  'Programming Language :: Python :: 3'
]

setup(
  name='mymodule',
  version='0.0.1',
  description='A short summary about your package',
  long_description=open('README.txt').read() + '\n\n' + open('CHANGELOG.txt').read(),
  url='',  # the URL of your package's home page e.g. github link
  author='John Smith',
  author_email='john.smith@gmail.com',
  license='MIT', # note the American spelling
  classifiers=classifiers,
  keywords='', # used when people are searching for a module, keywords separated with a space
  packages=find_packages(),
  install_requires=[''] # a list of other Python modules which this module depends on.  For example RPi.GPIO
)

For the list of classifiers that you can use, see https://pypi.python.org/pypi?%3Aaction=list_classifiers. Use as many as you think is relevant to your package.

• Rename your module to be __init__.py within the ‘mymodule’ directory.
• We are nearly finished now. This is probably a good point to place your package in source code control on something like Github or similar.
• Check that a few dependencies are installed (pip and setuptools). From the command line:

pip3 list

If you need to install pip:

sudo apt-get install python3-pip

If you need to install setuptools:

sudo pip3 install setuptools

• If this is your first time creating a Python package, you will need to create an account on PyPi. If you are creating a new Python package, you will also need to register it. You can do both by entering the following at the command line in the package directory:

python3 setup.py register

• Finally publish your Python package. To do this, enter the following at the command line in the package directory:

python3 setup.py sdist upload

Anyone can now install and use your package using the command:

pip3 install mymodule

In future I hope to add information on:

• Unit testing and code coverage
• Virtual environments
• Using docstrings, sphinx and readthedocs.org

There is obviously a lot more to it but this guide should get you started. For further reading:
https://python-packaging-user-guide.readthedocs.org/

Tweet