Reference`_ section below to see what commands you can give to this setup
script. For example, to produce a source distribution, simply invoke::
- python setup.py sdist
+ setup.py sdist
Of course, before you release your project to PyPI, you'll want to add a bit
more information to your setup script to help people find or learn about your
name="HelloWorld",
version="0.1",
packages=find_packages(),
- scripts=['say_hello.py'],
+ scripts=["say_hello.py"],
# Project uses reStructuredText, so ensure that the docutils get
# installed or upgraded on the target machine
- install_requires=['docutils>=0.3'],
+ install_requires=["docutils>=0.3"],
package_data={
# If any package contains *.txt or *.rst files, include them:
- '': ['*.txt', '*.rst'],
- # And include any *.msg files found in the 'hello' package, too:
- 'hello': ['*.msg'],
+ "": ["*.txt", "*.rst"],
+ # And include any *.msg files found in the "hello" package, too:
+ "hello": ["*.msg"],
},
# metadata to display on PyPI
"Source Code": "https://code.example.com/HelloWorld/",
},
classifiers=[
- 'License :: OSI Approved :: Python Software Foundation License'
+ "License :: OSI Approved :: Python Software Foundation License"
]
# could also include long_description, download_url, etc.
to compare different version numbers::
>>> from pkg_resources import parse_version
- >>> parse_version('1.9.a.dev') == parse_version('1.9a0dev')
+ >>> parse_version("1.9.a.dev") == parse_version("1.9a0dev")
True
- >>> parse_version('2.1-rc2') < parse_version('2.1')
+ >>> parse_version("2.1-rc2") < parse_version("2.1")
True
- >>> parse_version('0.6a9dev-r41475') < parse_version('0.6a9')
+ >>> parse_version("0.6a9dev-r41475") < parse_version("0.6a9")
True
Once you've decided on a version numbering scheme for your project, you can
imported. This argument is only useful if the project will be installed as
a zipfile, and there is a need to have all of the listed resources be
extracted to the filesystem *as a unit*. Resources listed here
- should be '/'-separated paths, relative to the source root, so to list a
+ should be "/"-separated paths, relative to the source root, so to list a
resource ``foo.png`` in package ``bar.baz``, you would include the string
``bar/baz/foo.png`` in this argument.
directory as the setup script. Some projects use a ``src`` or ``lib``
directory as the root of their source tree, and those projects would of course
use ``"src"`` or ``"lib"`` as the first argument to ``find_packages()``. (And
-such projects also need something like ``package_dir={'':'src'}`` in their
+such projects also need something like ``package_dir={"": "src"}`` in their
``setup()`` arguments, but that's just a normal distutils thing.)
Anyway, ``find_packages()`` walks the target directory, filtering by inclusion
setup(
name="namespace.mypackage",
version="0.1",
- packages=find_namespace_packages(include=['namespace.*'])
+ packages=find_namespace_packages(include=["namespace.*"])
)
Another option is to use the "src" layout, where all package code is placed in
setup(name="namespace.mypackage",
version="0.1",
- package_dir={'': 'src'},
- packages=find_namespace_packages(where='src'))
+ package_dir={"": "src"},
+ packages=find_namespace_packages(where="src"))
.. _PEP 420: https://www.python.org/dev/peps/pep-0420/
setup(
# other arguments here...
entry_points={
- 'console_scripts': [
- 'foo = my_package.some_module:main_func',
- 'bar = other_module:some_func',
+ "console_scripts": [
+ "foo = my_package.some_module:main_func",
+ "bar = other_module:some_func",
],
- 'gui_scripts': [
- 'baz = my_package_gui:start_func',
+ "gui_scripts": [
+ "baz = my_package_gui:start_func",
]
}
)
setup(
# other arguments here...
entry_points={
- 'setuptools.installation': [
- 'eggsecutable = my_package.some_module:main_func',
+ "setuptools.installation": [
+ "eggsecutable = my_package.some_module:main_func",
]
}
)
name="Project-A",
...
extras_require={
- 'PDF': ["ReportLab>=1.2", "RXP"],
- 'reST': ["docutils>=0.3"],
+ "PDF": ["ReportLab>=1.2", "RXP"],
+ "reST": ["docutils>=0.3"],
}
)
name="Project-A",
...
entry_points={
- 'console_scripts': [
- 'rst2pdf = project_a.tools.pdfgen [PDF]',
- 'rst2html = project_a.tools.htmlgen',
+ "console_scripts": [
+ "rst2pdf = project_a.tools.pdfgen [PDF]",
+ "rst2html = project_a.tools.htmlgen",
# more script entry points ...
],
}
name="Project-A",
...
extras_require={
- 'PDF': [],
- 'reST': ["docutils>=0.3"],
+ "PDF": [],
+ "reST": ["docutils>=0.3"],
}
)
name="Project",
...
install_requires=[
- 'enum34;python_version<"3.4"',
- 'pywin32 >= 1.0;platform_system=="Windows"'
+ "enum34;python_version<'3.4'",
+ "pywin32 >= 1.0;platform_system=='Windows'"
]
)
...
package_data={
# If any package contains *.txt or *.rst files, include them:
- '': ['*.txt', '*.rst'],
- # And include any *.msg files found in the 'hello' package, too:
- 'hello': ['*.msg'],
+ "": ["*.txt", "*.rst"],
+ # And include any *.msg files found in the "hello" package, too:
+ "hello": ["*.msg"],
}
)
from setuptools import setup, find_packages
setup(
...
- packages=find_packages('src'), # include all packages under src
- package_dir={'':'src'}, # tell distutils packages are under src
+ packages=find_packages("src"), # include all packages under src
+ package_dir={"": "src"}, # tell distutils packages are under src
package_data={
# If any package contains *.txt files, include them:
- '': ['*.txt'],
- # And include any *.dat files found in the 'data' subdirectory
- # of the 'mypkg' package, also:
- 'mypkg': ['data/*.dat'],
+ "": ["*.txt"],
+ # And include any *.dat files found in the "data" subdirectory
+ # of the "mypkg" package, also:
+ "mypkg": ["data/*.dat"],
}
)
If datafiles are contained in a subdirectory of a package that isn't a package
itself (no ``__init__.py``), then the subdirectory names (or ``*``) are required
-in the ``package_data`` argument (as shown above with ``'data/*.dat'``).
+in the ``package_data`` argument (as shown above with ``"data/*.dat"``).
When building an ``sdist``, the datafiles are also drawn from the
``package_name.egg-info/SOURCES.txt`` file, so make sure that this is removed if
from setuptools import setup, find_packages
setup(
...
- packages=find_packages('src'), # include all packages under src
- package_dir={'':'src'}, # tell distutils packages are under src
+ packages=find_packages("src"), # include all packages under src
+ package_dir={"": "src"}, # tell distutils packages are under src
include_package_data=True, # include everything in source control
# ...but exclude README.txt from all packages
- exclude_package_data={'': ['README.txt']},
+ exclude_package_data={"": ["README.txt"]},
)
The ``exclude_package_data`` option is a dictionary mapping package names to
lists of wildcard patterns, just like the ``package_data`` option. And, just
-as with that option, a key of ``''`` will apply the given pattern(s) to all
+as with that option, a key of ``""`` will apply the given pattern(s) to all
packages. However, any files that match these patterns will be *excluded*
from installation, even if they were listed in ``package_data`` or were
included as a result of using ``include_package_data``.
setup(
# ...
- entry_points={'blogtool.parsers': '.rst = some_module:SomeClass'}
+ entry_points={"blogtool.parsers": ".rst = some_module:SomeClass"}
)
setup(
# ...
- entry_points={'blogtool.parsers': ['.rst = some_module:a_func']}
+ entry_points={"blogtool.parsers": [".rst = some_module:a_func"]}
)
setup(
To build a setuptools project, run this command from the same directory where
setup.py is located::
- python3 setup.py sdist bdist_wheel
+ setup.py sdist bdist_wheel
This will generate distribution archives in the `dist` directory.
setup(
# ...
- namespace_packages=['zope']
+ namespace_packages=["zope"]
)
because it contains a ``zope.interface`` package that lives in the ``zope``
packages), in a normal Python package layout. These ``__init__.py`` files
*must* contain the line::
- __import__('pkg_resources').declare_namespace(__name__)
+ __import__("pkg_resources").declare_namespace(__name__)
This code ensures that the namespace package machinery is operating and that
the current package is registered as a namespace package.
setup.py egg_info -rbDEV bdist_egg rotate -m.egg -k3
-to build an egg whose version info includes 'DEV-rNNNN' (where NNNN is the
+to build an egg whose version info includes "DEV-rNNNN" (where NNNN is the
most recent Subversion revision that affected the source tree), and then
delete any egg files from the distribution directory except for the three
that were built most recently.
Alternately, if you are not branching for releases, you can override the
default version options on the command line, using something like::
- python setup.py egg_info -Db "" sdist bdist_egg
+ setup.py egg_info -Db "" sdist bdist_egg
The first part of this command (``egg_info -Db ""``) will override the
configured tag information, before creating source and binary eggs. Thus, these
Of course, if you will be doing this a lot, you may wish to create a personal
alias for this operation, e.g.::
- python setup.py alias -u release egg_info -Db ""
+ setup.py alias -u release egg_info -Db ""
You can then use it like this::
- python setup.py release sdist bdist_egg
+ setup.py release sdist bdist_egg
Or of course you can create more elaborate aliases that do all of the above.
See the sections below on the `egg_info`_ and `alias`_ commands for more ideas.
of your pyproject.toml::
[build-system]
- requires=[..., 'cython']
+ requires=[..., "cython"]
Built with pip 10 or later, that declaration is sufficient to include Cython
in the build. For broader compatibility, declare the dependency in your
the ``sdist``, ``bdist_egg``, ``develop``, and ``test`` commands in order to
update the project's metadata, but you can also specify it explicitly in order
to temporarily change the project's version string while executing other
-commands. (It also generates the``.egg-info/SOURCES.txt`` manifest file, which
+commands. (It also generates the ``.egg-info/SOURCES.txt`` manifest file, which
is used when you are building source distributions.)
In addition to writing the core egg metadata defined by ``setuptools`` and
how the resulting version numbers will be interpreted by automated tools
like pip. See the section above on `Specifying Your Project's Version`_ for an
explanation of pre- and post-release tags, as well as tips on how to choose and
-verify a versioning scheme for your your project.)
+verify a versioning scheme for your project.)
For advanced uses, there is one other option that can be set, to change the
location of the project's ``.egg-info`` directory. Commands that need to find
Creating a dated "nightly build" snapshot egg::
- python setup.py egg_info --tag-date --tag-build=DEV bdist_egg
+ setup.py egg_info --tag-date --tag-build=DEV bdist_egg
Creating a release with no version tags, even if some default tags are
specified in ``setup.cfg``::
- python setup.py egg_info -RDb "" sdist bdist_egg
+ setup.py egg_info -RDb "" sdist bdist_egg
(Notice that ``egg_info`` must always appear on the command line *before* any
commands that you want the version changes to apply to.)
from setuptools.config import read_configuration
- conf_dict = read_configuration('/home/user/dev/package/setup.cfg')
+ conf_dict = read_configuration("/home/user/dev/package/setup.cfg")
By default, ``read_configuration()`` will read only the file provided
argname = os.path.splitext(basename)[0]
value = getattr(cmd.distribution, argname, None)
if value is not None:
- value = '\n'.join(value) + '\n'
+ value = "\n".join(value) + "\n"
cmd.write_or_delete_file(argname, filename, value)
As you can see, ``egg_info.writers`` entry points must be a function taking