zoochory

A runnable tutorial on how to create and deploy a python module to the Python Package Index (and how to make it pip-installable).

Zoochory is a fancy name seeds piggybacking on animals, catching a ride to their new home.

Making the Package - Getting Started

• create an account at python.org and at pypi.

• RTFM for Packaging and Distributing Projects from the Python Packaging User Guide.

• make a new virtual environment

virtualenv venv
source venv/bin/activate

• install twine (and track dependencies)

pip install twine
pip freeze > requirements.txt

• take a look at this complete sample project from the pypi team

• update setuptools and install wheel

pip install -U pip setuptools
pip install wheel
pip freeze > requirements.txt

• learn about the setup.py

  • "The primary feature of setup.py is that it contains a global setup() function"

• learn about the other special purpose files in an installable package

  • setup.cfg
  • README.rst
  • MANIFEST.in

• download the example files so we can start tweaking them

wget https://raw.githubusercontent.com/pypa/sampleproject/master/setup.py
wget https://raw.githubusercontent.com/pypa/sampleproject/master/setup.cfg
wget https://raw.githubusercontent.com/pypa/sampleproject/master/README.rst
wget https://raw.githubusercontent.com/pypa/sampleproject/master/MANIFEST.in

• As suggested in the instructions, let's create a single top-level package that has the same name as the project.
  • make it a module by adding an __init__.py file

mkdir zoochory
cd zoochory/
wget https://raw.githubusercontent.com/pypa/sampleproject/master/sample/__init__.py

• tweak setup.py to your liking, then:

• start testing

# install the package locally
pip install -e .
# confirm that it worked via
pip freeze
# run an executable script if you made one
zoochory
hello-world
# uninstall
pip uninstall -y zoochory

Creating a Distribution

• now that we've tested locally are convinced the package behaves as expected, it's time for distribution

  • should probably write some tests before distribution :-)

• make a Source Distribution

python setup.py sdist

• and a universal wheel

python setup.py bdist_wheel --universal

Uploading to PyPi

• create an account

• I choose register via the recomended web form

  • form link

• time to upload

# this will prompt for your pypi.python.org username and password
twine upload dist/*

Confirm that it worked

• check the pypi website

  • https://pypi.python.org/pypi/zoochory

• start a new virtual environment, install the package, and try running a command

virtualenv venv
source venv/bin/activate
pip install zoochory
hello-world

• should result in a jolly response of:
  • Hello, from a pip installed world!

Congratulations!

• you've created and deployed a python package to PyPi

• it's now available publicly, far and wide, for all the world to see and use

• pretty neat :-)