setup.py cheatsheet

Welcome to the setup.py cheatsheet!

This is an interactive guide for exploring various important parameters of the setup.py packaging script format for python applications.

You can access information about parameters by hovering over or clicking the property name.

Thanks to Nodejitsu for their package.json cheatsheet which inspired me to create this page.

The Python shebang

Use this in the first line of the script to tell Unix-like system to start it with the Python interpreter by default.

The setuptools import

setup.py is a standard python script that calls a setup() function. You have to import the function from the setuptools module before you can use it.

The `setup()` call

Most information that you supply to the setuptools package is supplied as keyword arguments to the setup() function.

Hover over or click on the individual arguments to see the details.

The unique name of your package

(Required)

This will indicate the name of the package in the Python Package Index (if you choose to publish it).

Keep it short and try not to use any special characters.

The package version

(Required)

This field describes the version of your package. It should use the format described by PEP386.

Try to follow the rules of Semantic Versioning.

Examples:

0.4

0.4.1

0.5a1

0.5b3

0.9.6

1.0

1.0.4a4

1.0.4b1

The description of the project

Try to keep it short, concise and in one line.

The long description of the project

This usually contains the content of your README file and should be written in reStructuredText markup.

It is common to use the following code to include the README and possible other files directly:


import os

def read(*paths):
    """Build a file path from *paths* and return the contents."""
    with open(os.path.join(*paths), 'r') as f:
        return f.read()

setup(
    ...
    long_description=read('README.rst'),
    ...
)

Project URL

The website of the project or a link to the repository.

A common usage is to set this to the URL of your project on GitHub.

Download URL

The location where the package may be downloaded.

License information

Use this argument if you haven't used a license classifier below or if there is no official classifier for your license.

Always define a license for your project if you want to enable others to use it!

The project author

The name and email address of the package author.

The current project maintainer

The name and email address of the current package maintainer.

This should only be used if the information is different from the package author. For example for forks or projects that are no longer maintained by their original author.

Project classifiers

This list helps the Python Package Index to classify and filter projects by their most important attributes.

Only string from the official list must be used. Including custom classifiers will result in package rejection.

Dependencies

If your project depends on other packages then use this list to declare those dependencies.

Format: packagename[extra1,extra2]>=0.5a,<=1.0

packagename: name of the other package
[extra1,extra2]: optional list of "extras"
>=0.5a,<1.0: optional list of version specifiers

More information is available in the setuptools documentation.

Dependency Links

If any of your project dependencies are not registered on PyPI you can use this list to tell setuptools how to resolve them.

Format: [vcs+]proto://host/path@revision#egg=packagename-version