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
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
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
- make it a module by adding an
mkdir zoochory
cd zoochory/
wget https://raw.githubusercontent.com/pypa/sampleproject/master/sample/__init__.py
tweak
setup.py
to your liking, then:
# 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
# this will prompt for your pypi.python.org username and password
twine upload dist/*
Confirm that it worked
-
check the pypi website
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 :-)