# Creating Python packages
Every package requires a
setup.py (opens new window) file which describes the package.
Consider the following directory structure for a simple package:
+-- package_name | | | +-- __init__.py | +-- setup.py
__init__.py contains only the line
def foo(): return 100.
setup.py will define the package:
from setuptools import setup setup( name='package_name', # package name version='0.1', # version description='Package Description', # short description url='http://example.com', # package URL install_requires=, # list of packages this package depends # on. packages=['package_name'], # List of module names that installing # this package will provide. )
virtualenv (opens new window) is great to test package installs without modifying your other Python environments:
$ virtualenv .virtualenv ... $ source .virtualenv/bin/activate $ python setup.py install running install ... Installed .../package_name-0.1-....egg ... $ python >>> import package_name >>> package_name.foo() 100
# Uploading to PyPI
# Setup a .pypirc File
This file stores logins and passwords to authenticate your accounts. It is typically stored in your home directory.
# .pypirc file [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
It is safer (opens new window) to use
twine for uploading packages, so make sure that is installed.
$ pip install twine
# Register and Upload to testpypi (optional)
Note: PyPI does not allow overwriting uploaded packages (opens new window), so it is prudent to first test your deployment on a dedicated test server, e.g. testpypi. This option will be discussed. Consider a versioning scheme (opens new window) for your package prior to uploading such as calendar versioning (opens new window) or semantic versioning (opens new window).
Either log in, or create a new account at testpypi (opens new window). Registration is only required the first time, although registering more than once is not harmful.
$ python setup.py register -r pypitest
While in the root directory of your package:
$ twine upload dist/* -r pypitest
Your package should now be accessible through your account.
Make a test virtual environment. Try to
pip install your package from either testpypi or PyPI.
# Using virtualenv $ mkdir testenv $ cd testenv $ virtualenv .virtualenv ... $ source .virtualenv/bin/activate # Test from testpypi (.virtualenv) pip install --verbose --extra-index-url https://testpypi.python.org/pypi package_name ... # Or test from PyPI (.virtualenv) $ pip install package_name ... (.virtualenv) $ python Python 3.5.1 (default, Jan 27 2016, 19:16:39) [GCC 4.2.1 Compatible Apple LLVM 7.0.2 (clang-700.1.81)] on darwin Type "help", "copyright", "credits" or "license" for more information. >>> import package_name >>> package_name.foo() 100
If successful, your package is least importable. You might consider testing your API as well before your final upload to PyPI. If you package failed during testing, do not worry. You can still fix it, re-upload to testpypi and test again.
# Register and Upload to PyPI
twine is installed:
$ pip install twine
Either log in, or create a new account at PyPI (opens new window).
$ python setup.py register -r pypi $ twine upload dist/*
That's it! Your package is now live (opens new window).
If you discover a bug, simply upload a new version of your package.
Don't forget to include at least some kind of documentation for your package. PyPi takes as the default formatting language reStructuredText (opens new window).
If your package doesn't have a big documentation, include what can help other users in
README.rst file. When the file is ready, another one is needed to tell PyPi to show it.
setup.cfg file and put these two lines in it:
[metadata] description-file = README.rst
Note that if you try to put Markdown (opens new window) file into your package, PyPi will read it as a pure text file without any formatting.
It's often more than welcome to put a
LICENSE.txt file in your package with one of the OpenSource licenses (opens new window) to tell users if they can use your package for example in commercial projects or if your code is usable with their license.
In more readable way some licenses are explained at TL;DR (opens new window).
# Making package executable
If your package isn't only a library, but has a piece of code that can be used either as a showcase or a standalone application when your package is installed, put that piece of code into
__main__.py in the
package_name folder. This way you will be able to run it directly from console:
python -m package_name
If there's no
__main__.py file available, the package won't run with this command and this error will be printed:
python: No module named `package_name.__main__;` 'package_name' is a package and cannot be directly executed.
The pypa sample project (opens new window) contains a complete, easily modifiable template
setup.py that demonstrates a large range of capabilities setup-tools has to offer.