navdeep-g / setup.py

📦 A Human's Ultimate Guide to setup.py.

📦 setup.py (for humans)

This repo exists to provide an example setup.py file, that can be used to bootstrap your next Python project. It includes some advanced patterns and best practices for setup.py, as well as some commented–out nice–to–haves.

For example, this setup.py provides a $ python setup.py upload command, which creates a universal wheel (and sdist) and uploads your package to PyPi using Twine, without the need for an annoying setup.cfg file. It also creates/uploads a new git tag, automatically.

In short, setup.py files can be daunting to approach, when first starting out — even Guido has been heard saying, "everyone cargo cults thems". It's true — so, I want this repo to be the best place to copy–paste from :)

Check out the example!

Installation

cd your_project

# Download the setup.py file:
#  download with wget
wget https://raw.githubusercontent.com/navdeep-G/setup.py/master/setup.py -O setup.py

#  download with curl
curl -O https://raw.githubusercontent.com/navdeep-G/setup.py/master/setup.py

To Do

• Tests via $ setup.py test (if it's concise).

Pull requests are encouraged!

More Resources

• What is setup.py? on Stack Overflow
• Official Python Packaging User Guide
• The Hitchhiker's Guide to Packaging
• Cookiecutter template for a Python package

License

This is free and unencumbered software released into the public domain.

Anyone is free to copy, modify, publish, use, compile, sell, or distribute this software, either in source code form or as a compiled binary, for any purpose, commercial or non-commercial, and by any means.

setup.py's Issues

suggestion: add example about using c/cpp extension?

(just a suggestion)

Would you like to consider make the example "more advanced", by showing how to use c/cpp extension (e.g, cython or cffi)? It's usually not easy to find "best practice" for such situations.

Thank you!

Use of a version tuple

If the version.py included a version tuple, and built the version string from it, it would make it easier for people to gate features based on versions.

Something like:

version = [ 0, 1, 0 ]

__version__ = '.'.join(map(str, version))

Remove reference to "The Hitchhiker's Guide to Packaging"

Should we point people directly to this? https://packaging.python.org/

The Hitchhiker's guide, although probably a great source of information, is outdated. Written in 2009, the last commit was in 2010.

I believe that given the state of python packaging, it is not a good reference to keep hanging around.

Support rendering project description from Markdown

As detailed here please update setup.py to support rendering the project description from Markdown.

Version bump as part of setup.py?

How can we do a nice version bump for major/minor/micro changes?

It might be nice as an extra possible command in setup.py? Would this be possible?

Or do you think it more fits in pipenv?

Dankeschön/Thanks

I genuinely wanted to thank you for this.

Absolute Legends.

Missing comma in setup kwargs

https://github.com/kennethreitz/setup.py/blob/71dc482c94749327732237746e24d1722705941f/setup.py#L92

Looks like there should be a comma here

How to include additional packages in setup.py

I am using Python-2.7 with windows-7 64 bit. Can anyone guide me how to modify setup.py. I want to add few packages in setup.py. I installed python-2.7 through anaconda. Thanks in advance

License file doesn't match description in readme

The README describes the software as public domain but the LICENSE included is actually an ISC license.

Use twine and wheel --universal

without a setup.cfg.

use_scm_version = True

https://github.com/pypa/setuptools_scm

Include multiple examples

For example a package that lives at ./src/package, a package that is only one python file, one with compiled extensions.

One of the parameters is missing a comma in the setup() call.

https://github.com/kennethreitz/setup.py/blob/71dc482c94749327732237746e24d1722705941f/setup.py#L92

PyPI upload appears to require 'wheel' installation

When attempting to upload a new project (using Python 3.5.1 in a virtualenv) to PyPI using the README (and inline comment) steps, the $ python setup.py upload command failed with the error message below.

$ python setup.py upload
running upload
Removing previous builds…
Building Source and Wheel (universal) distribution…
usage: setup.py [global_opts] cmd1 [cmd1_opts] [cmd2 [cmd2_opts] ...]
   or: setup.py --help [cmd1 cmd2 ...]
   or: setup.py --help-commands
   or: setup.py cmd --help

error: invalid command 'bdist_wheel'
Uploading the package to PyPi via Twine…
ValueError: Cannot find file (or expand pattern): 'dist/*'

An SO entry led me to running $ pip install wheel and following that step, the previous upload command did work as expected.

Would it be useful to open a PR with the example pip command updated to include wheel after twine?

Connection error on upload

I get the following error when trying to upload to PyPI:

ConnectionError: HTTPSConnectionPool(host='upload.pypi.org', port=443): Max retries exceeded with url: /legacy/ (Caused by NewConnectionError('<urllib3.connection.VerifiedHTTPSConnection object at 0x101f1b438>: Failed to establish a new connection: [Errno 8] nodename nor servname provided, or not known',))

Is the port used for uploading to PyPI being blocked on the network I'm on?

public domain

Please consider dedicating your work to the public domain so that others can safely copy & paste from your repo. You can use https://unlicense.org/ or https://creativecommons.org/publicdomain/zero/1.0/.

Should a license in the "license" and "classifiers" be the same?

https://github.com/kennethreitz/setup.py/blob/1a9be22205b3c47f040bfe5a59821e80f2325b37/setup.py#L95

Now the "license" is ISC, but the "classifiers" contains License :: OSI Approved :: MIT License.

FileNotFoundError not available in python2

FileNotFoundError is not defined in python2

$ python setup.py publish
running publish
Removing previous builds…
Traceback (most recent call last):
File "setup.py", line 101, in
'publish': PublishCommand,
File "/usr/lib/python2.7/distutils/core.py", line 151, in setup
dist.run_commands()
File "/usr/lib/python2.7/distutils/dist.py", line 953, in run_commands
self.run_command(cmd)
File "/usr/lib/python2.7/distutils/dist.py", line 972, in run_command
cmd_obj.run()
File "setup.py", line 60, in run
except FileNotFoundError:
NameError: global name 'FileNotFoundError' is not defined

[question] What about parsing requirements.txt?

https://github.com/kennethreitz/setup.py/blob/c5a82dc3670b5fa65e4d5da578d992c38b62d524/setup.py#L22

2 years ago I was playing with this http://j.mp/setup_py and one of the features is using pip.req.parse_requirements('requirements.txt') to populate the requires and avoid duplicity.

What do you think about this? on advantage of having a requirements.txt is to use pyup.io and satefy to check updates and audit the requirements for security failures.

Consider adding examples for extras_require

Perhaps the project could benefit from adding syntax examples for two useful features, commonly seen in the wild:

• extras, e.g. myproj[this,stuff]
• conditional deps, i.e. environment markers (e.g., requiring backports only when needed)

Additionally, I think the UploadCommand thing is feature bloat and should be removed. It doesn't really belong here directly in setup.py, being duplicated in each and every project. Maybe just add a comment or a link to a good guide about how to use twine?

How about automatically updating version?

How about custom command versioner for setup.py which automatically increment version string in __version__.py.

How it's works:

.travis.yml setup

It would be nice if you also provide .travis.yml for Travis CI.
In the script, it should test out a few commands with setup.py such as
python setup.py install, etc.

Non-universal wheel

This is question, not an issue report. I appreciate that this project is demystifying setup.py a bit.

One thing I find myself questioning: if I'm making a project that is meant to run only on Python 3, is it enough to just remove the "--universal" part from the UploadCommand class?

Cannot read the the version file

I have my directory structure like so

setup.py
MANIFEST.in
LICENSE
README.md
pipfile
pipfile.lock
cryptowatch:
    - cryptowatch
    - __version__.py
    - __init__.py
    - utlitiesFile.py

When I run python setup.py I am given this error:

Traceback (most recent call last):
  File "setup.py", line 25, in <module>
    with open(os.path.join(here, NAME, '__version__.py')) as f:
IOError: [Errno 2] No such file or directory: '/home/fsociety/git/bitbucket/cryptowatch/crypotowatch/__version__.py'

I know I have a file there and I even went as far as making it executable with chmod a+x __version__.py but sill no luck.

Is there something I am doing wrong here?

I have modified the setup.py a little but only information not the actual code, just in case I screwed something up while doing that here it is:

#!/usr/bin/env python
# -*- coding: utf-8 -*-

import codecs
import os
import sys

from setuptools import find_packages, setup

# Package meta-data.
NAME = 'crypotowatch'
DESCRIPTION = 'Track prices and account balaces bitcoin, ethereum, and litecoin'
URL = 'https://github.com/alexanderepstein/cryptowatch'
EMAIL = '[email protected]'
AUTHOR = 'Alexander Epstein'

here = os.path.abspath(os.path.dirname(__file__))

# Import the README and use it as the long-description.
with codecs.open(os.path.join(here, 'README.md'), encoding='utf-8') as f:
    long_description = '\n' + f.read()

# Load the package's __version__.py module as a dictionary.
about = {}
with open(os.path.join(here, NAME, "__version__.py")) as f:
    exec(f.read(), about)

# Support "$ setup.py publish".
if sys.argv[-1] == "publish":
    os.system("python setup.py sdist bdist_wheel upload")
    sys.exit()

# What packages are required for this module to be executed?
required = [
     'requests', 'Adafruit_GPIO'
]

# Dependencies only for versions less than Python 2.7:
# if sys.version_info < (2, 7):
#     required.append('requests[security]')

# Where the magic happens:
setup(
    name=NAME,
    version=about['__version__'],
    description=DESCRIPTION,
    long_description=long_description,
    author=AUTHOR,
    author_email=EMAIL,
    url=URL,
    packages=find_packages(exclude=('tests',)),
#     entry_points={
#         'console_scripts': ['mycli=mymodule:cli'],
#     },
    install_requires=required,
    include_package_data=True,
    license='MIT',
    classifiers=[
        'License :: OSI Approved :: MIT License',
        'Programming Language :: Python',
        'Programming Language :: Python :: 2.6',
        'Programming Language :: Python :: 2.7',
        'Programming Language :: Python :: Implementation :: CPython',
        'Programming Language :: Python :: Implementation :: PyPy'
    ],
)

Py

#84

Provide an avenue for zip_safe and keywords

Both zip_safe and keywords elements are missing from setup.py.

Consider providing a small section where users can opt-in to define them.

ZIP_UNSAFE = None # Modify this variable to declare the project as unsafe to be ran while zipped
KEYWORDS = ""  # Modify this string to include comma separated keywords defining your project



setup(
    ...
    zip_safe = ZIP_UNSAFE is None,
    keywords = KEYWORDS,
)

Py

https://github.com/IneededAnAccountToDoStuff

Unix dependencies

What would the setup.py look like for packages that rely on certain linux packages to also be installed via apt-get/yum/brew ?

Don't encourage Python2 support :)

It's probably better to comment out the Python2 classifiers (especially 2.6!) so you only show they're possible, rather than suggest they're desirable as a default.

remove unlicense from README.md

The section from the Unlicense is still in the README.md even though you switched to MIT

Introduce setup.cfg

The best development in the python packaging field in the last years is the introduction of the setup.cfg:

• declarative description
• simple to read
• easy to diff

It reduces the need for error prone, cargo cult boilerplate code in the setup.py.
A nice setup.py should look like this (if it should exist at all):

from setuptools import setup

if __name__ == "__main__":
    setup()

IMHO, the rest should be declaratively described without arbitrary code execution in the setup.cfg

Deprecated API?

I'm using the following setup.py file: https://gist.github.com/sieben/e7003fab39c201b902f9442d2b954a04

When I use the following command:

$ python2 setup.py publish
$ python3 setup.py publish

I get the following error:

HTTPError: 410 Client Error: Gone (This API has been deprecated and removed from legacy PyPI in favor of using the APIs available in the new PyPI.org implementation of PyPI (located at https://pypi.org/). For more information about migrating your use of this API to PyPI.org, please see https://packaging.python.org/guides/migrating-to-pypi-org/#uploading. For more information about the sunsetting of this API, please see https://mail.python.org/pipermail/distutils-sig/2017-June/030766.html) for url: https://pypi.python.org/pypi

What is `setup.py` and why would I want one?

I could probably answer this question with a web search.

That being said, the answer, or your answer, would probably make a nice addition to your README.rst.