[bumpversion]
-current_version = 62.4.0
+current_version = 62.5.0
commit = True
tag = True
+v62.5.0
+-------
+
+
+Changes
+^^^^^^^
+* #3347: Changed warnings and documentation notes about *experimental* aspect of ``pyproject.toml`` configuration:
+ now ``[pyproject]`` is a fully supported configuration interface, but the ``[tool.setuptools]`` table
+ and sub-tables are still considered to be in **beta** stage.
+* #3383: In _distutils_hack, suppress/undo the use of local distutils when select tests are imported in CPython.
+
+Documentation changes
+^^^^^^^^^^^^^^^^^^^^^
+* #3368: Added documentation page about extension modules -- by :user:`mkoeppe`
+* #3371: Moved documentation from ``/userguide/commands`` to ``/depracted/commands``.
+ This change was motived by the fact that running ``python setup.py`` directly is
+ considered a deprecated practice.
+* #3372: Consolidated sections about ``sdist`` contents and ``MANIFEST.in`` into a single page.
+
+ Added a simple ``MANIFEST.in`` example.
+* #3373: Moved remarks about using :pypi:`Cython` to the newly created page for
+ extension modules.
+* #3374: Added clarification that using ``python setup.py egg_info`` commands to
+ manage project versions is only supported in a *transitional* basis, and
+ that eventually ``egg_info`` will be deprecated.
+
+ Reorganized sections with tips for managing versions.
+* #3378: Updated ``Quickstart`` docs to make it easier to follow for beginners.
+
+Misc
+^^^^
+* #3385: Modules used to parse and evaluate configuration from ``pyproject.toml`` files are
+ intended for internal use only and that not part of the public API.
+
+
v62.4.0
-------
# https://foss.heptapod.net/pypy/pypy/-/blob/be829135bc0d758997b3566062999ee8b23872b4/lib-python/3/site.py#L250
return
import warnings
+
warnings.warn(
"Distutils was imported before Setuptools, but importing Setuptools "
"also replaces the `distutils` module in `sys.modules`. This may lead "
"to undesirable behaviors or errors. To avoid these issues, avoid "
"using distutils directly, ensure that setuptools is installed in the "
"traditional way (e.g. not an editable install), and/or make sure "
- "that setuptools is always imported before distutils.")
+ "that setuptools is always imported before distutils."
+ )
def clear_distutils():
if 'distutils' not in sys.modules:
return
import warnings
+
warnings.warn("Setuptools is replacing distutils.")
mods = [
- name for name in sys.modules
+ name
+ for name in sys.modules
if name == "distutils" or name.startswith("distutils.")
]
for name in mods:
def ensure_local_distutils():
import importlib
+
clear_distutils()
# With the DistutilsMetaFinder in place,
class DistutilsMetaFinder:
def find_spec(self, fullname, path, target=None):
- if path is not None:
+ # optimization: only consider top level modules and those
+ # found in the CPython test suite.
+ if path is not None and not fullname.startswith('test.'):
return
method_name = 'spec_for_{fullname}'.format(**locals())
return
class DistutilsLoader(importlib.abc.Loader):
-
def create_module(self, spec):
mod.__name__ = 'distutils'
return mod
Detect if pip is being imported in a build script. Ref #2355.
"""
import traceback
+
return any(
- cls.frame_file_is_setup(frame)
- for frame, line in traceback.walk_stack(None)
+ cls.frame_file_is_setup(frame) for frame, line in traceback.walk_stack(None)
)
@staticmethod
# some frames may not have __file__ (#2940)
return frame.f_globals.get('__file__', '').endswith('setup.py')
+ def spec_for_sensitive_tests(self):
+ """
+ Ensure stdlib distutils when running select tests under CPython.
+
+ python/cpython#91169
+ """
+ clear_distutils()
+ self.spec_for_distutils = lambda: None
+
+ sensitive_tests = (
+ [
+ 'test.test_distutils',
+ 'test.test_peg_generator',
+ 'test.test_importlib',
+ ]
+ if sys.version_info < (3, 10)
+ else [
+ 'test.test_distutils',
+ ]
+ )
+
+
+for name in DistutilsMetaFinder.sensitive_tests:
+ setattr(
+ DistutilsMetaFinder,
+ f'spec_for_{name}',
+ DistutilsMetaFinder.spec_for_sensitive_tests,
+ )
+
DISTUTILS_FINDER = DistutilsMetaFinder()
}
intersphinx_mapping.update({
- 'pypa-build': ('https://pypa-build.readthedocs.io/en/latest/', None)
+ 'pip': ('https://pip.pypa.io/en/latest', None),
+ 'build': ('https://pypa-build.readthedocs.io/en/latest', None),
+ 'PyPUG': ('https://packaging.python.org/en/latest/', None),
+ 'packaging': ('https://packaging.pypa.io/en/latest/', None),
+ 'twine': ('https://twine.readthedocs.io/en/stable/', None),
+ 'importlib-resources': (
+ 'https://importlib-resources.readthedocs.io/en/latest', None
+ ),
})
# Add support for linking usernames
extensions += ['sphinx_reredirects']
redirects = {
"userguide/keywords": "/deprecated/changed_keywords.html",
+ "userguide/commands": "/deprecated/commands.html",
}
# Add support for inline tabs
},
# rel="apple-touch-icon" does not support SVG yet
]
-
-intersphinx_mapping['pip'] = 'https://pip.pypa.io/en/latest', None
-intersphinx_mapping['PyPUG'] = ('https://packaging.python.org/en/latest/', None)
-intersphinx_mapping['packaging'] = ('https://packaging.pypa.io/en/latest/', None)
-intersphinx_mapping['importlib-resources'] = (
- 'https://importlib-resources.readthedocs.io/en/latest', None
-)
--- /dev/null
+===============================
+Running ``setuptools`` commands
+===============================
+
+Historically, ``setuptools`` allowed running commands via a ``setup.py`` script
+at the root of a Python project, as indicated in the examples below::
+
+ python setup.py --help
+ python setup.py --help-commands
+ python setup.py --version
+ python setup.py sdist
+ python setup.py bdist_wheel
+
+You could also run commands in other circumstances:
+
+* ``setuptools`` projects without ``setup.py`` (e.g., ``setup.cfg``-only)::
+
+ python -c "import setuptools; setup()" --help
+
+* ``distutils`` projects (with a ``setup.py`` importing ``distutils``)::
+
+ python -c "import setuptools; with open('setup.py') as f: exec(compile(f.read(), 'setup.py', 'exec'))" develop
+
+That is, you can simply list the normal setup commands and options following the quoted part.
+
+.. warning::
+ While it is perfectly fine that users write ``setup.py`` files to configure
+ a package build (e.g. to specify binary extensions or customize commands),
+ on recent versions of ``setuptools``, running ``python setup.py`` directly
+ as a script is considered **deprecated**. This also means that users should
+ avoid running commands directly via ``python setup.py <command>``.
+
+ If you want to create :term:`sdist <Source Distribution (or "sdist")>` or :term:`wheel`
+ distributions the recommendation is to use the command line tool provided by :pypi:`build`::
+
+ pip install build # needs to be installed first
+
+ python -m build # builds both sdist and wheel
+ python -m build --sdist
+ python -m build --wheel
+
+ Build will automatically download ``setuptools`` and build the package in an
+ isolated environment. You can also specify specific versions of
+ ``setuptools``, by setting the :doc:`build requirements in pyproject.toml
+ </build_meta>`.
+
+ If you want to install a package, you can use :pypi:`pip` or :pypi:`installer`::
+
+ pip install /path/to/wheel/file.whl
+ pip install /path/to/sdist/file.tar.gz
+ pip install . # replacement for python setup.py install
+ pip install --editable . # replacement for python setup.py develop
+
+ pip install installer # needs to be installed first
+ python -m installer /path/to/wheel/file.whl
+
+-----------------
+Command Reference
+-----------------
+
+.. _alias:
+
+``alias`` - Define shortcuts for commonly used commands
+=======================================================
+
+Sometimes, you need to use the same commands over and over, but you can't
+necessarily set them as defaults. For example, if you produce both development
+snapshot releases and "stable" releases of a project, you may want to put
+the distributions in different places, or use different ``egg_info`` tagging
+options, etc. In these cases, it doesn't make sense to set the options in
+a distutils configuration file, because the values of the options changed based
+on what you're trying to do.
+
+Setuptools therefore allows you to define "aliases" - shortcut names for
+an arbitrary string of commands and options, using ``setup.py alias aliasname
+expansion``, where aliasname is the name of the new alias, and the remainder of
+the command line supplies its expansion. For example, this command defines
+a sitewide alias called "daily", that sets various ``egg_info`` tagging
+options::
+
+ setup.py alias --global-config daily egg_info --tag-build=development
+
+Once the alias is defined, it can then be used with other setup commands,
+e.g.::
+
+ setup.py daily bdist_egg # generate a daily-build .egg file
+ setup.py daily sdist # generate a daily-build source distro
+ setup.py daily sdist bdist_egg # generate both
+
+The above commands are interpreted as if the word ``daily`` were replaced with
+``egg_info --tag-build=development``.
+
+Note that setuptools will expand each alias *at most once* in a given command
+line. This serves two purposes. First, if you accidentally create an alias
+loop, it will have no effect; you'll instead get an error message about an
+unknown command. Second, it allows you to define an alias for a command, that
+uses that command. For example, this (project-local) alias::
+
+ setup.py alias bdist_egg bdist_egg rotate -k1 -m.egg
+
+redefines the ``bdist_egg`` command so that it always runs the ``rotate``
+command afterwards to delete all but the newest egg file. It doesn't loop
+indefinitely on ``bdist_egg`` because the alias is only expanded once when
+used.
+
+You can remove a defined alias with the ``--remove`` (or ``-r``) option, e.g.::
+
+ setup.py alias --global-config --remove daily
+
+would delete the "daily" alias we defined above.
+
+Aliases can be defined on a project-specific, per-user, or sitewide basis. The
+default is to define or remove a project-specific alias, but you can use any of
+the `configuration file options`_ (listed under the `saveopts`_ command, below)
+to determine which distutils configuration file an aliases will be added to
+(or removed from).
+
+Note that if you omit the "expansion" argument to the ``alias`` command,
+you'll get output showing that alias' current definition (and what
+configuration file it's defined in). If you omit the alias name as well,
+you'll get a listing of all current aliases along with their configuration
+file locations.
+
+
+``bdist_egg`` - Create a Python Egg for the project
+===================================================
+
+.. warning::
+ **eggs** are deprecated in favor of wheels, and not supported by pip.
+
+This command generates a Python Egg (``.egg`` file) for the project. Python
+Eggs are the preferred binary distribution format for EasyInstall, because they
+are cross-platform (for "pure" packages), directly importable, and contain
+project metadata including scripts and information about the project's
+dependencies. They can be simply downloaded and added to ``sys.path``
+directly, or they can be placed in a directory on ``sys.path`` and then
+automatically discovered by the egg runtime system.
+
+This command runs the `egg_info`_ command (if it hasn't already run) to update
+the project's metadata (``.egg-info``) directory. If you have added any extra
+metadata files to the ``.egg-info`` directory, those files will be included in
+the new egg file's metadata directory, for use by the egg runtime system or by
+any applications or frameworks that use that metadata.
+
+You won't usually need to specify any special options for this command; just
+use ``bdist_egg`` and you're done. But there are a few options that may
+be occasionally useful:
+
+``--dist-dir=DIR, -d DIR``
+ Set the directory where the ``.egg`` file will be placed. If you don't
+ supply this, then the ``--dist-dir`` setting of the ``bdist`` command
+ will be used, which is usually a directory named ``dist`` in the project
+ directory.
+
+``--plat-name=PLATFORM, -p PLATFORM``
+ Set the platform name string that will be embedded in the egg's filename
+ (assuming the egg contains C extensions). This can be used to override
+ the distutils default platform name with something more meaningful. Keep
+ in mind, however, that the egg runtime system expects to see eggs with
+ distutils platform names, so it may ignore or reject eggs with non-standard
+ platform names. Similarly, the EasyInstall program may ignore them when
+ searching web pages for download links. However, if you are
+ cross-compiling or doing some other unusual things, you might find a use
+ for this option.
+
+``--exclude-source-files``
+ Don't include any modules' ``.py`` files in the egg, just compiled Python,
+ C, and data files. (Note that this doesn't affect any ``.py`` files in the
+ EGG-INFO directory or its subdirectories, since for example there may be
+ scripts with a ``.py`` extension which must still be retained.) We don't
+ recommend that you use this option except for packages that are being
+ bundled for proprietary end-user applications, or for "embedded" scenarios
+ where space is at an absolute premium. On the other hand, if your package
+ is going to be installed and used in compressed form, you might as well
+ exclude the source because Python's ``traceback`` module doesn't currently
+ understand how to display zipped source code anyway, or how to deal with
+ files that are in a different place from where their code was compiled.
+
+There are also some options you will probably never need, but which are there
+because they were copied from similar ``bdist`` commands used as an example for
+creating this one. They may be useful for testing and debugging, however,
+which is why we kept them:
+
+``--keep-temp, -k``
+ Keep the contents of the ``--bdist-dir`` tree around after creating the
+ ``.egg`` file.
+
+``--bdist-dir=DIR, -b DIR``
+ Set the temporary directory for creating the distribution. The entire
+ contents of this directory are zipped to create the ``.egg`` file, after
+ running various installation commands to copy the package's modules, data,
+ and extensions here.
+
+``--skip-build``
+ Skip doing any "build" commands; just go straight to the
+ install-and-compress phases.
+
+
+.. _develop:
+
+``develop`` - Deploy the project source in "Development Mode"
+=============================================================
+
+This command allows you to deploy your project's source for use in one or more
+"staging areas" where it will be available for importing. This deployment is
+done in such a way that changes to the project source are immediately available
+in the staging area(s), without needing to run a build or install step after
+each change.
+
+The ``develop`` command works by creating an ``.egg-link`` file (named for the
+project) in the given staging area. If the staging area is Python's
+``site-packages`` directory, it also updates an ``easy-install.pth`` file so
+that the project is on ``sys.path`` by default for all programs run using that
+Python installation.
+
+The ``develop`` command also installs wrapper scripts in the staging area (or
+a separate directory, as specified) that will ensure the project's dependencies
+are available on ``sys.path`` before running the project's source scripts.
+And, it ensures that any missing project dependencies are available in the
+staging area, by downloading and installing them if necessary.
+
+Last, but not least, the ``develop`` command invokes the ``build_ext -i``
+command to ensure any C extensions in the project have been built and are
+up-to-date, and the ``egg_info`` command to ensure the project's metadata is
+updated (so that the runtime and wrappers know what the project's dependencies
+are). If you make any changes to the project's setup script or C extensions,
+you should rerun the ``develop`` command against all relevant staging areas to
+keep the project's scripts, metadata and extensions up-to-date. Most other
+kinds of changes to your project should not require any build operations or
+rerunning ``develop``, but keep in mind that even minor changes to the setup
+script (e.g. changing an entry point definition) require you to re-run the
+``develop`` or ``test`` commands to keep the distribution updated.
+
+Here are some of the options that the ``develop`` command accepts. Note that
+they affect the project's dependencies as well as the project itself, so if you
+have dependencies that need to be installed and you use ``--exclude-scripts``
+(for example), the dependencies' scripts will not be installed either! For
+this reason, you may want to use pip to install the project's dependencies
+before using the ``develop`` command, if you need finer control over the
+installation options for dependencies.
+
+``--uninstall, -u``
+ Un-deploy the current project. You may use the ``--install-dir`` or ``-d``
+ option to designate the staging area. The created ``.egg-link`` file will
+ be removed, if present and it is still pointing to the project directory.
+ The project directory will be removed from ``easy-install.pth`` if the
+ staging area is Python's ``site-packages`` directory.
+
+ Note that this option currently does *not* uninstall script wrappers! You
+ must uninstall them yourself, or overwrite them by using pip to install a
+ different version of the package. You can also avoid installing script
+ wrappers in the first place, if you use the ``--exclude-scripts`` (aka
+ ``-x``) option when you run ``develop`` to deploy the project.
+
+``--multi-version, -m``
+ "Multi-version" mode. Specifying this option prevents ``develop`` from
+ adding an ``easy-install.pth`` entry for the project(s) being deployed, and
+ if an entry for any version of a project already exists, the entry will be
+ removed upon successful deployment. In multi-version mode, no specific
+ version of the package is available for importing, unless you use
+ ``pkg_resources.require()`` to put it on ``sys.path``, or you are running
+ a wrapper script generated by ``setuptools``. (In which case the wrapper
+ script calls ``require()`` for you.)
+
+ Note that if you install to a directory other than ``site-packages``,
+ this option is automatically in effect, because ``.pth`` files can only be
+ used in ``site-packages`` (at least in Python 2.3 and 2.4). So, if you use
+ the ``--install-dir`` or ``-d`` option (or they are set via configuration
+ file(s)) your project and its dependencies will be deployed in multi-
+ version mode.
+
+``--install-dir=DIR, -d DIR``
+ Set the installation directory (staging area). If this option is not
+ directly specified on the command line or in a distutils configuration
+ file, the distutils default installation location is used. Normally, this
+ will be the ``site-packages`` directory, but if you are using distutils
+ configuration files, setting things like ``prefix`` or ``install_lib``,
+ then those settings are taken into account when computing the default
+ staging area.
+
+``--script-dir=DIR, -s DIR``
+ Set the script installation directory. If you don't supply this option
+ (via the command line or a configuration file), but you *have* supplied
+ an ``--install-dir`` (via command line or config file), then this option
+ defaults to the same directory, so that the scripts will be able to find
+ their associated package installation. Otherwise, this setting defaults
+ to the location where the distutils would normally install scripts, taking
+ any distutils configuration file settings into account.
+
+``--exclude-scripts, -x``
+ Don't deploy script wrappers. This is useful if you don't want to disturb
+ existing versions of the scripts in the staging area.
+
+``--always-copy, -a``
+ Copy all needed distributions to the staging area, even if they
+ are already present in another directory on ``sys.path``. By default, if
+ a requirement can be met using a distribution that is already available in
+ a directory on ``sys.path``, it will not be copied to the staging area.
+
+``--egg-path=DIR``
+ Force the generated ``.egg-link`` file to use a specified relative path
+ to the source directory. This can be useful in circumstances where your
+ installation directory is being shared by code running under multiple
+ platforms (e.g. Mac and Windows) which have different absolute locations
+ for the code under development, but the same *relative* locations with
+ respect to the installation directory. If you use this option when
+ installing, you must supply the same relative path when uninstalling.
+
+In addition to the above options, the ``develop`` command also accepts all of
+the same options accepted by ``easy_install``. If you've configured any
+``easy_install`` settings in your ``setup.cfg`` (or other distutils config
+files), the ``develop`` command will use them as defaults, unless you override
+them in a ``[develop]`` section or on the command line.
+
+
+.. _egg_info:
+
+``egg_info`` - Create egg metadata and set build tags
+=====================================================
+
+This command performs two operations: it updates a project's ``.egg-info``
+metadata directory (used by the ``bdist_egg``, ``develop``, and ``test``
+commands), and it allows you to temporarily change a project's version string,
+to support "daily builds" or "snapshot" releases. It is run automatically by
+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
+is used when you are building source distributions.)
+
+In addition to writing the core egg metadata defined by ``setuptools`` and
+required by ``pkg_resources``, this command can be extended to write other
+metadata files as well, by defining entry points in the ``egg_info.writers``
+group. See the section on :ref:`Adding new EGG-INFO Files` below for more details.
+Note that using additional metadata writers may require you to include a
+``setup_requires`` argument to ``setup()`` in order to ensure that the desired
+writers are available on ``sys.path``.
+
+
+Release Tagging Options
+-----------------------
+
+The following options can be used to modify the project's version string for
+all remaining commands on the setup command line. The options are processed
+in the order shown, so if you use more than one, the requested tags will be
+added in the following order:
+
+``--tag-build=NAME, -b NAME``
+ Append NAME to the project's version string. Due to the way setuptools
+ processes "pre-release" version suffixes beginning with the letters "a"
+ through "e" (like "alpha", "beta", and "candidate"), you will usually want
+ to use a tag like ".build" or ".dev", as this will cause the version number
+ to be considered *lower* than the project's default version. (If you
+ want to make the version number *higher* than the default version, you can
+ always leave off --tag-build and then use one or both of the following
+ options.)
+
+ If you have a default build tag set in your ``setup.cfg``, you can suppress
+ it on the command line using ``-b ""`` or ``--tag-build=""`` as an argument
+ to the ``egg_info`` command.
+
+``--tag-date, -d``
+ Add a date stamp of the form "-YYYYMMDD" (e.g. "-20050528") to the
+ project's version number.
+
+``--no-date, -D``
+ Don't include a date stamp in the version number. This option is included
+ so you can override a default setting in ``setup.cfg``.
+
+
+(Note: Because these options modify the version number used for source and
+binary distributions of your project, you should first make sure that you know
+how the resulting version numbers will be interpreted by automated tools
+like pip. See the section above on :ref:`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 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
+the project's source directory or metadata should get it from this setting:
+
+
+Other ``egg_info`` Options
+--------------------------
+
+``--egg-base=SOURCEDIR, -e SOURCEDIR``
+ Specify the directory that should contain the .egg-info directory. This
+ should normally be the root of your project's source tree (which is not
+ necessarily the same as your project directory; some projects use a ``src``
+ or ``lib`` subdirectory as the source root). You should not normally need
+ to specify this directory, as it is normally determined from the
+ ``package_dir`` argument to the ``setup()`` function, if any. If there is
+ no ``package_dir`` set, this option defaults to the current directory.
+
+
+``egg_info`` Examples
+---------------------
+
+Creating a dated "nightly build" snapshot 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``::
+
+ 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.)
+
+.. _rotate:
+
+``rotate`` - Delete outdated distribution files
+===============================================
+
+As you develop new versions of your project, your distribution (``dist``)
+directory will gradually fill up with older source and/or binary distribution
+files. The ``rotate`` command lets you automatically clean these up, keeping
+only the N most-recently modified files matching a given pattern.
+
+``--match=PATTERNLIST, -m PATTERNLIST``
+ Comma-separated list of glob patterns to match. This option is *required*.
+ The project name and ``-*`` is prepended to the supplied patterns, in order
+ to match only distributions belonging to the current project (in case you
+ have a shared distribution directory for multiple projects). Typically,
+ you will use a glob pattern like ``.zip`` or ``.egg`` to match files of
+ the specified type. Note that each supplied pattern is treated as a
+ distinct group of files for purposes of selecting files to delete.
+
+``--keep=COUNT, -k COUNT``
+ Number of matching distributions to keep. For each group of files
+ identified by a pattern specified with the ``--match`` option, delete all
+ but the COUNT most-recently-modified files in that group. This option is
+ *required*.
+
+``--dist-dir=DIR, -d DIR``
+ Directory where the distributions are. This defaults to the value of the
+ ``bdist`` command's ``--dist-dir`` option, which will usually be the
+ project's ``dist`` subdirectory.
+
+**Example 1**: Delete all .tar.gz files from the distribution directory, except
+for the 3 most recently modified ones::
+
+ setup.py rotate --match=.tar.gz --keep=3
+
+**Example 2**: Delete all Python 2.3 or Python 2.4 eggs from the distribution
+directory, except the most recently modified one for each Python version::
+
+ setup.py rotate --match=-py2.3*.egg,-py2.4*.egg --keep=1
+
+
+.. _saveopts:
+
+``saveopts`` - Save used options to a configuration file
+========================================================
+
+Finding and editing ``distutils`` configuration files can be a pain, especially
+since you also have to translate the configuration options from command-line
+form to the proper configuration file format. You can avoid these hassles by
+using the ``saveopts`` command. Just add it to the command line to save the
+options you used. For example, this command builds the project using
+the ``mingw32`` C compiler, then saves the --compiler setting as the default
+for future builds (even those run implicitly by the ``install`` command)::
+
+ setup.py build --compiler=mingw32 saveopts
+
+The ``saveopts`` command saves all options for every command specified on the
+command line to the project's local ``setup.cfg`` file, unless you use one of
+the `configuration file options`_ to change where the options are saved. For
+example, this command does the same as above, but saves the compiler setting
+to the site-wide (global) distutils configuration::
+
+ setup.py build --compiler=mingw32 saveopts -g
+
+Note that it doesn't matter where you place the ``saveopts`` command on the
+command line; it will still save all the options specified for all commands.
+For example, this is another valid way to spell the last example::
+
+ setup.py saveopts -g build --compiler=mingw32
+
+Note, however, that all of the commands specified are always run, regardless of
+where ``saveopts`` is placed on the command line.
+
+
+Configuration File Options
+--------------------------
+
+Normally, settings such as options and aliases are saved to the project's
+local ``setup.cfg`` file. But you can override this and save them to the
+global or per-user configuration files, or to a manually-specified filename.
+
+``--global-config, -g``
+ Save settings to the global ``distutils.cfg`` file inside the ``distutils``
+ package directory. You must have write access to that directory to use
+ this option. You also can't combine this option with ``-u`` or ``-f``.
+
+``--user-config, -u``
+ Save settings to the current user's ``~/.pydistutils.cfg`` (POSIX) or
+ ``$HOME/pydistutils.cfg`` (Windows) file. You can't combine this option
+ with ``-g`` or ``-f``.
+
+``--filename=FILENAME, -f FILENAME``
+ Save settings to the specified configuration file to use. You can't
+ combine this option with ``-g`` or ``-u``. Note that if you specify a
+ non-standard filename, the ``distutils`` and ``setuptools`` will not
+ use the file's contents. This option is mainly included for use in
+ testing.
+
+These options are used by other ``setuptools`` commands that modify
+configuration files, such as the `alias`_ and `setopt`_ commands.
+
+
+.. _setopt:
+
+``setopt`` - Set a distutils or setuptools option in a config file
+==================================================================
+
+This command is mainly for use by scripts, but it can also be used as a quick
+and dirty way to change a distutils configuration option without having to
+remember what file the options are in and then open an editor.
+
+**Example 1**. Set the default C compiler to ``mingw32`` (using long option
+names)::
+
+ setup.py setopt --command=build --option=compiler --set-value=mingw32
+
+**Example 2**. Remove any setting for the distutils default package
+installation directory (short option names)::
+
+ setup.py setopt -c install -o install_lib -r
+
+
+Options for the ``setopt`` command:
+
+``--command=COMMAND, -c COMMAND``
+ Command to set the option for. This option is required.
+
+``--option=OPTION, -o OPTION``
+ The name of the option to set. This option is required.
+
+``--set-value=VALUE, -s VALUE``
+ The value to set the option to. Not needed if ``-r`` or ``--remove`` is
+ set.
+
+``--remove, -r``
+ Remove (unset) the option, instead of setting it.
+
+In addition to the above options, you may use any of the `configuration file
+options`_ (listed under the `saveopts`_ command, above) to determine which
+distutils configuration file the option will be added to (or removed from).
+
+
+.. _test:
+
+``test`` - Build package and run a unittest suite
+=================================================
+
+.. warning::
+ ``test`` is deprecated and will be removed in a future version. Users
+ looking for a generic test entry point independent of test runner are
+ encouraged to use `tox <https://tox.readthedocs.io>`_.
+
+When doing test-driven development, or running automated builds that need
+testing before they are deployed for downloading or use, it's often useful
+to be able to run a project's unit tests without actually deploying the project
+anywhere, even using the ``develop`` command. The ``test`` command runs a
+project's unit tests without actually deploying it, by temporarily putting the
+project's source on ``sys.path``, after first running ``build_ext -i`` and
+``egg_info`` to ensure that any C extensions and project metadata are
+up-to-date.
+
+To use this command, your project's tests must be wrapped in a ``unittest``
+test suite by either a function, a ``TestCase`` class or method, or a module
+or package containing ``TestCase`` classes. If the named suite is a module,
+and the module has an ``additional_tests()`` function, it is called and the
+result (which must be a ``unittest.TestSuite``) is added to the tests to be
+run. If the named suite is a package, any submodules and subpackages are
+recursively added to the overall test suite. (Note: if your project specifies
+a ``test_loader``, the rules for processing the chosen ``test_suite`` may
+differ; see the :ref:`test_loader <test_loader>` documentation for more details.)
+
+Note that many test systems including ``doctest`` support wrapping their
+non-``unittest`` tests in ``TestSuite`` objects. So, if you are using a test
+package that does not support this, we suggest you encourage its developers to
+implement test suite support, as this is a convenient and standard way to
+aggregate a collection of tests to be run under a common test harness.
+
+By default, tests will be run in the "verbose" mode of the ``unittest``
+package's text test runner, but you can get the "quiet" mode (just dots) if
+you supply the ``-q`` or ``--quiet`` option, either as a global option to
+the setup script (e.g. ``setup.py -q test``) or as an option for the ``test``
+command itself (e.g. ``setup.py test -q``). There is one other option
+available:
+
+``--test-suite=NAME, -s NAME``
+ Specify the test suite (or module, class, or method) to be run
+ (e.g. ``some_module.test_suite``). The default for this option can be
+ set by giving a ``test_suite`` argument to the ``setup()`` function, e.g.::
+
+ setup(
+ # ...
+ test_suite="my_package.tests.test_all"
+ )
+
+ If you did not set a ``test_suite`` in your ``setup()`` call, and do not
+ provide a ``--test-suite`` option, an error will occur.
+
+New in 41.5.0: Deprecated the test command.
+
+
+.. _upload:
+
+``upload`` - Upload source and/or egg distributions to PyPI
+===========================================================
+
+The ``upload`` command was deprecated in version 40.0 and removed in version
+42.0. Use `twine <https://pypi.org/p/twine>`_ instead.
+
+For more information on the current best practices in uploading your packages
+to PyPI, see the Python Packaging User Guide's "Packaging Python Projects"
+tutorial specifically the section on `uploading the distribution archives
+<https://packaging.python.org/tutorials/packaging-projects/#uploading-the-distribution-archives>`_.
Setuptools and the PyPA have a `stated goal <https://github.com/pypa/packaging-problems/issues/127>`_ to make Setuptools the reference API for distutils.
-Since the 60.0.0 release, Setuptools includes a local, vendored copy of distutils (from late copies of CPython) that is enabled by default. To disable the use of this copy of distutils when invoking setuptools, set the enviroment variable:
+Since the 60.0.0 release, Setuptools includes a local, vendored copy of distutils (from late copies of CPython) that is enabled by default. To disable the use of this copy of distutils when invoking setuptools, set the environment variable:
SETUPTOOLS_USE_DISTUTILS=stdlib
distutils/index
distutils-legacy
functionalities
- running_commands
+ commands
+++ /dev/null
-Running ``setuptools`` commands
-===============================
-
-Historically, ``setuptools`` allowed running commands via a ``setup.py`` script
-at the root of a Python project, as indicated in the examples below::
-
- python setup.py --help
- python setup.py --help-commands
- python setup.py --version
- python setup.py sdist
- python setup.py bdist_wheel
-
-You could also run commands in other circumstances:
-
-* ``setuptools`` projects without ``setup.py`` (e.g., ``setup.cfg``-only)::
-
- python -c "import setuptools; setup()" --help
-
-* ``distutils`` projects (with a ``setup.py`` importing ``distutils``)::
-
- python -c "import setuptools; with open('setup.py') as f: exec(compile(f.read(), 'setup.py', 'exec'))" develop
-
-That is, you can simply list the normal setup commands and options following the quoted part.
+++ /dev/null
------------------
-Command Reference
------------------
-
-.. _alias:
-
-``alias`` - Define shortcuts for commonly used commands
-=======================================================
-
-Sometimes, you need to use the same commands over and over, but you can't
-necessarily set them as defaults. For example, if you produce both development
-snapshot releases and "stable" releases of a project, you may want to put
-the distributions in different places, or use different ``egg_info`` tagging
-options, etc. In these cases, it doesn't make sense to set the options in
-a distutils configuration file, because the values of the options changed based
-on what you're trying to do.
-
-Setuptools therefore allows you to define "aliases" - shortcut names for
-an arbitrary string of commands and options, using ``setup.py alias aliasname
-expansion``, where aliasname is the name of the new alias, and the remainder of
-the command line supplies its expansion. For example, this command defines
-a sitewide alias called "daily", that sets various ``egg_info`` tagging
-options::
-
- setup.py alias --global-config daily egg_info --tag-build=development
-
-Once the alias is defined, it can then be used with other setup commands,
-e.g.::
-
- setup.py daily bdist_egg # generate a daily-build .egg file
- setup.py daily sdist # generate a daily-build source distro
- setup.py daily sdist bdist_egg # generate both
-
-The above commands are interpreted as if the word ``daily`` were replaced with
-``egg_info --tag-build=development``.
-
-Note that setuptools will expand each alias *at most once* in a given command
-line. This serves two purposes. First, if you accidentally create an alias
-loop, it will have no effect; you'll instead get an error message about an
-unknown command. Second, it allows you to define an alias for a command, that
-uses that command. For example, this (project-local) alias::
-
- setup.py alias bdist_egg bdist_egg rotate -k1 -m.egg
-
-redefines the ``bdist_egg`` command so that it always runs the ``rotate``
-command afterwards to delete all but the newest egg file. It doesn't loop
-indefinitely on ``bdist_egg`` because the alias is only expanded once when
-used.
-
-You can remove a defined alias with the ``--remove`` (or ``-r``) option, e.g.::
-
- setup.py alias --global-config --remove daily
-
-would delete the "daily" alias we defined above.
-
-Aliases can be defined on a project-specific, per-user, or sitewide basis. The
-default is to define or remove a project-specific alias, but you can use any of
-the `configuration file options`_ (listed under the `saveopts`_ command, below)
-to determine which distutils configuration file an aliases will be added to
-(or removed from).
-
-Note that if you omit the "expansion" argument to the ``alias`` command,
-you'll get output showing that alias' current definition (and what
-configuration file it's defined in). If you omit the alias name as well,
-you'll get a listing of all current aliases along with their configuration
-file locations.
-
-
-``bdist_egg`` - Create a Python Egg for the project
-===================================================
-
-.. warning::
- **eggs** are deprecated in favor of wheels, and not supported by pip.
-
-This command generates a Python Egg (``.egg`` file) for the project. Python
-Eggs are the preferred binary distribution format for EasyInstall, because they
-are cross-platform (for "pure" packages), directly importable, and contain
-project metadata including scripts and information about the project's
-dependencies. They can be simply downloaded and added to ``sys.path``
-directly, or they can be placed in a directory on ``sys.path`` and then
-automatically discovered by the egg runtime system.
-
-This command runs the `egg_info`_ command (if it hasn't already run) to update
-the project's metadata (``.egg-info``) directory. If you have added any extra
-metadata files to the ``.egg-info`` directory, those files will be included in
-the new egg file's metadata directory, for use by the egg runtime system or by
-any applications or frameworks that use that metadata.
-
-You won't usually need to specify any special options for this command; just
-use ``bdist_egg`` and you're done. But there are a few options that may
-be occasionally useful:
-
-``--dist-dir=DIR, -d DIR``
- Set the directory where the ``.egg`` file will be placed. If you don't
- supply this, then the ``--dist-dir`` setting of the ``bdist`` command
- will be used, which is usually a directory named ``dist`` in the project
- directory.
-
-``--plat-name=PLATFORM, -p PLATFORM``
- Set the platform name string that will be embedded in the egg's filename
- (assuming the egg contains C extensions). This can be used to override
- the distutils default platform name with something more meaningful. Keep
- in mind, however, that the egg runtime system expects to see eggs with
- distutils platform names, so it may ignore or reject eggs with non-standard
- platform names. Similarly, the EasyInstall program may ignore them when
- searching web pages for download links. However, if you are
- cross-compiling or doing some other unusual things, you might find a use
- for this option.
-
-``--exclude-source-files``
- Don't include any modules' ``.py`` files in the egg, just compiled Python,
- C, and data files. (Note that this doesn't affect any ``.py`` files in the
- EGG-INFO directory or its subdirectories, since for example there may be
- scripts with a ``.py`` extension which must still be retained.) We don't
- recommend that you use this option except for packages that are being
- bundled for proprietary end-user applications, or for "embedded" scenarios
- where space is at an absolute premium. On the other hand, if your package
- is going to be installed and used in compressed form, you might as well
- exclude the source because Python's ``traceback`` module doesn't currently
- understand how to display zipped source code anyway, or how to deal with
- files that are in a different place from where their code was compiled.
-
-There are also some options you will probably never need, but which are there
-because they were copied from similar ``bdist`` commands used as an example for
-creating this one. They may be useful for testing and debugging, however,
-which is why we kept them:
-
-``--keep-temp, -k``
- Keep the contents of the ``--bdist-dir`` tree around after creating the
- ``.egg`` file.
-
-``--bdist-dir=DIR, -b DIR``
- Set the temporary directory for creating the distribution. The entire
- contents of this directory are zipped to create the ``.egg`` file, after
- running various installation commands to copy the package's modules, data,
- and extensions here.
-
-``--skip-build``
- Skip doing any "build" commands; just go straight to the
- install-and-compress phases.
-
-
-.. _develop:
-
-``develop`` - Deploy the project source in "Development Mode"
-=============================================================
-
-This command allows you to deploy your project's source for use in one or more
-"staging areas" where it will be available for importing. This deployment is
-done in such a way that changes to the project source are immediately available
-in the staging area(s), without needing to run a build or install step after
-each change.
-
-The ``develop`` command works by creating an ``.egg-link`` file (named for the
-project) in the given staging area. If the staging area is Python's
-``site-packages`` directory, it also updates an ``easy-install.pth`` file so
-that the project is on ``sys.path`` by default for all programs run using that
-Python installation.
-
-The ``develop`` command also installs wrapper scripts in the staging area (or
-a separate directory, as specified) that will ensure the project's dependencies
-are available on ``sys.path`` before running the project's source scripts.
-And, it ensures that any missing project dependencies are available in the
-staging area, by downloading and installing them if necessary.
-
-Last, but not least, the ``develop`` command invokes the ``build_ext -i``
-command to ensure any C extensions in the project have been built and are
-up-to-date, and the ``egg_info`` command to ensure the project's metadata is
-updated (so that the runtime and wrappers know what the project's dependencies
-are). If you make any changes to the project's setup script or C extensions,
-you should rerun the ``develop`` command against all relevant staging areas to
-keep the project's scripts, metadata and extensions up-to-date. Most other
-kinds of changes to your project should not require any build operations or
-rerunning ``develop``, but keep in mind that even minor changes to the setup
-script (e.g. changing an entry point definition) require you to re-run the
-``develop`` or ``test`` commands to keep the distribution updated.
-
-Here are some of the options that the ``develop`` command accepts. Note that
-they affect the project's dependencies as well as the project itself, so if you
-have dependencies that need to be installed and you use ``--exclude-scripts``
-(for example), the dependencies' scripts will not be installed either! For
-this reason, you may want to use pip to install the project's dependencies
-before using the ``develop`` command, if you need finer control over the
-installation options for dependencies.
-
-``--uninstall, -u``
- Un-deploy the current project. You may use the ``--install-dir`` or ``-d``
- option to designate the staging area. The created ``.egg-link`` file will
- be removed, if present and it is still pointing to the project directory.
- The project directory will be removed from ``easy-install.pth`` if the
- staging area is Python's ``site-packages`` directory.
-
- Note that this option currently does *not* uninstall script wrappers! You
- must uninstall them yourself, or overwrite them by using pip to install a
- different version of the package. You can also avoid installing script
- wrappers in the first place, if you use the ``--exclude-scripts`` (aka
- ``-x``) option when you run ``develop`` to deploy the project.
-
-``--multi-version, -m``
- "Multi-version" mode. Specifying this option prevents ``develop`` from
- adding an ``easy-install.pth`` entry for the project(s) being deployed, and
- if an entry for any version of a project already exists, the entry will be
- removed upon successful deployment. In multi-version mode, no specific
- version of the package is available for importing, unless you use
- ``pkg_resources.require()`` to put it on ``sys.path``, or you are running
- a wrapper script generated by ``setuptools``. (In which case the wrapper
- script calls ``require()`` for you.)
-
- Note that if you install to a directory other than ``site-packages``,
- this option is automatically in effect, because ``.pth`` files can only be
- used in ``site-packages`` (at least in Python 2.3 and 2.4). So, if you use
- the ``--install-dir`` or ``-d`` option (or they are set via configuration
- file(s)) your project and its dependencies will be deployed in multi-
- version mode.
-
-``--install-dir=DIR, -d DIR``
- Set the installation directory (staging area). If this option is not
- directly specified on the command line or in a distutils configuration
- file, the distutils default installation location is used. Normally, this
- will be the ``site-packages`` directory, but if you are using distutils
- configuration files, setting things like ``prefix`` or ``install_lib``,
- then those settings are taken into account when computing the default
- staging area.
-
-``--script-dir=DIR, -s DIR``
- Set the script installation directory. If you don't supply this option
- (via the command line or a configuration file), but you *have* supplied
- an ``--install-dir`` (via command line or config file), then this option
- defaults to the same directory, so that the scripts will be able to find
- their associated package installation. Otherwise, this setting defaults
- to the location where the distutils would normally install scripts, taking
- any distutils configuration file settings into account.
-
-``--exclude-scripts, -x``
- Don't deploy script wrappers. This is useful if you don't want to disturb
- existing versions of the scripts in the staging area.
-
-``--always-copy, -a``
- Copy all needed distributions to the staging area, even if they
- are already present in another directory on ``sys.path``. By default, if
- a requirement can be met using a distribution that is already available in
- a directory on ``sys.path``, it will not be copied to the staging area.
-
-``--egg-path=DIR``
- Force the generated ``.egg-link`` file to use a specified relative path
- to the source directory. This can be useful in circumstances where your
- installation directory is being shared by code running under multiple
- platforms (e.g. Mac and Windows) which have different absolute locations
- for the code under development, but the same *relative* locations with
- respect to the installation directory. If you use this option when
- installing, you must supply the same relative path when uninstalling.
-
-In addition to the above options, the ``develop`` command also accepts all of
-the same options accepted by ``easy_install``. If you've configured any
-``easy_install`` settings in your ``setup.cfg`` (or other distutils config
-files), the ``develop`` command will use them as defaults, unless you override
-them in a ``[develop]`` section or on the command line.
-
-
-.. _egg_info:
-
-``egg_info`` - Create egg metadata and set build tags
-=====================================================
-
-This command performs two operations: it updates a project's ``.egg-info``
-metadata directory (used by the ``bdist_egg``, ``develop``, and ``test``
-commands), and it allows you to temporarily change a project's version string,
-to support "daily builds" or "snapshot" releases. It is run automatically by
-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
-is used when you are building source distributions.)
-
-In addition to writing the core egg metadata defined by ``setuptools`` and
-required by ``pkg_resources``, this command can be extended to write other
-metadata files as well, by defining entry points in the ``egg_info.writers``
-group. See the section on :ref:`Adding new EGG-INFO Files` below for more details.
-Note that using additional metadata writers may require you to include a
-``setup_requires`` argument to ``setup()`` in order to ensure that the desired
-writers are available on ``sys.path``.
-
-
-Release Tagging Options
------------------------
-
-The following options can be used to modify the project's version string for
-all remaining commands on the setup command line. The options are processed
-in the order shown, so if you use more than one, the requested tags will be
-added in the following order:
-
-``--tag-build=NAME, -b NAME``
- Append NAME to the project's version string. Due to the way setuptools
- processes "pre-release" version suffixes beginning with the letters "a"
- through "e" (like "alpha", "beta", and "candidate"), you will usually want
- to use a tag like ".build" or ".dev", as this will cause the version number
- to be considered *lower* than the project's default version. (If you
- want to make the version number *higher* than the default version, you can
- always leave off --tag-build and then use one or both of the following
- options.)
-
- If you have a default build tag set in your ``setup.cfg``, you can suppress
- it on the command line using ``-b ""`` or ``--tag-build=""`` as an argument
- to the ``egg_info`` command.
-
-``--tag-date, -d``
- Add a date stamp of the form "-YYYYMMDD" (e.g. "-20050528") to the
- project's version number.
-
-``--no-date, -D``
- Don't include a date stamp in the version number. This option is included
- so you can override a default setting in ``setup.cfg``.
-
-
-(Note: Because these options modify the version number used for source and
-binary distributions of your project, you should first make sure that you know
-how the resulting version numbers will be interpreted by automated tools
-like pip. See the section above on :ref:`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 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
-the project's source directory or metadata should get it from this setting:
-
-
-Other ``egg_info`` Options
---------------------------
-
-``--egg-base=SOURCEDIR, -e SOURCEDIR``
- Specify the directory that should contain the .egg-info directory. This
- should normally be the root of your project's source tree (which is not
- necessarily the same as your project directory; some projects use a ``src``
- or ``lib`` subdirectory as the source root). You should not normally need
- to specify this directory, as it is normally determined from the
- ``package_dir`` argument to the ``setup()`` function, if any. If there is
- no ``package_dir`` set, this option defaults to the current directory.
-
-
-``egg_info`` Examples
----------------------
-
-Creating a dated "nightly build" snapshot 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``::
-
- 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.)
-
-.. _rotate:
-
-``rotate`` - Delete outdated distribution files
-===============================================
-
-As you develop new versions of your project, your distribution (``dist``)
-directory will gradually fill up with older source and/or binary distribution
-files. The ``rotate`` command lets you automatically clean these up, keeping
-only the N most-recently modified files matching a given pattern.
-
-``--match=PATTERNLIST, -m PATTERNLIST``
- Comma-separated list of glob patterns to match. This option is *required*.
- The project name and ``-*`` is prepended to the supplied patterns, in order
- to match only distributions belonging to the current project (in case you
- have a shared distribution directory for multiple projects). Typically,
- you will use a glob pattern like ``.zip`` or ``.egg`` to match files of
- the specified type. Note that each supplied pattern is treated as a
- distinct group of files for purposes of selecting files to delete.
-
-``--keep=COUNT, -k COUNT``
- Number of matching distributions to keep. For each group of files
- identified by a pattern specified with the ``--match`` option, delete all
- but the COUNT most-recently-modified files in that group. This option is
- *required*.
-
-``--dist-dir=DIR, -d DIR``
- Directory where the distributions are. This defaults to the value of the
- ``bdist`` command's ``--dist-dir`` option, which will usually be the
- project's ``dist`` subdirectory.
-
-**Example 1**: Delete all .tar.gz files from the distribution directory, except
-for the 3 most recently modified ones::
-
- setup.py rotate --match=.tar.gz --keep=3
-
-**Example 2**: Delete all Python 2.3 or Python 2.4 eggs from the distribution
-directory, except the most recently modified one for each Python version::
-
- setup.py rotate --match=-py2.3*.egg,-py2.4*.egg --keep=1
-
-
-.. _saveopts:
-
-``saveopts`` - Save used options to a configuration file
-========================================================
-
-Finding and editing ``distutils`` configuration files can be a pain, especially
-since you also have to translate the configuration options from command-line
-form to the proper configuration file format. You can avoid these hassles by
-using the ``saveopts`` command. Just add it to the command line to save the
-options you used. For example, this command builds the project using
-the ``mingw32`` C compiler, then saves the --compiler setting as the default
-for future builds (even those run implicitly by the ``install`` command)::
-
- setup.py build --compiler=mingw32 saveopts
-
-The ``saveopts`` command saves all options for every command specified on the
-command line to the project's local ``setup.cfg`` file, unless you use one of
-the `configuration file options`_ to change where the options are saved. For
-example, this command does the same as above, but saves the compiler setting
-to the site-wide (global) distutils configuration::
-
- setup.py build --compiler=mingw32 saveopts -g
-
-Note that it doesn't matter where you place the ``saveopts`` command on the
-command line; it will still save all the options specified for all commands.
-For example, this is another valid way to spell the last example::
-
- setup.py saveopts -g build --compiler=mingw32
-
-Note, however, that all of the commands specified are always run, regardless of
-where ``saveopts`` is placed on the command line.
-
-
-Configuration File Options
---------------------------
-
-Normally, settings such as options and aliases are saved to the project's
-local ``setup.cfg`` file. But you can override this and save them to the
-global or per-user configuration files, or to a manually-specified filename.
-
-``--global-config, -g``
- Save settings to the global ``distutils.cfg`` file inside the ``distutils``
- package directory. You must have write access to that directory to use
- this option. You also can't combine this option with ``-u`` or ``-f``.
-
-``--user-config, -u``
- Save settings to the current user's ``~/.pydistutils.cfg`` (POSIX) or
- ``$HOME/pydistutils.cfg`` (Windows) file. You can't combine this option
- with ``-g`` or ``-f``.
-
-``--filename=FILENAME, -f FILENAME``
- Save settings to the specified configuration file to use. You can't
- combine this option with ``-g`` or ``-u``. Note that if you specify a
- non-standard filename, the ``distutils`` and ``setuptools`` will not
- use the file's contents. This option is mainly included for use in
- testing.
-
-These options are used by other ``setuptools`` commands that modify
-configuration files, such as the `alias`_ and `setopt`_ commands.
-
-
-.. _setopt:
-
-``setopt`` - Set a distutils or setuptools option in a config file
-==================================================================
-
-This command is mainly for use by scripts, but it can also be used as a quick
-and dirty way to change a distutils configuration option without having to
-remember what file the options are in and then open an editor.
-
-**Example 1**. Set the default C compiler to ``mingw32`` (using long option
-names)::
-
- setup.py setopt --command=build --option=compiler --set-value=mingw32
-
-**Example 2**. Remove any setting for the distutils default package
-installation directory (short option names)::
-
- setup.py setopt -c install -o install_lib -r
-
-
-Options for the ``setopt`` command:
-
-``--command=COMMAND, -c COMMAND``
- Command to set the option for. This option is required.
-
-``--option=OPTION, -o OPTION``
- The name of the option to set. This option is required.
-
-``--set-value=VALUE, -s VALUE``
- The value to set the option to. Not needed if ``-r`` or ``--remove`` is
- set.
-
-``--remove, -r``
- Remove (unset) the option, instead of setting it.
-
-In addition to the above options, you may use any of the `configuration file
-options`_ (listed under the `saveopts`_ command, above) to determine which
-distutils configuration file the option will be added to (or removed from).
-
-
-.. _test:
-
-``test`` - Build package and run a unittest suite
-=================================================
-
-.. warning::
- ``test`` is deprecated and will be removed in a future version. Users
- looking for a generic test entry point independent of test runner are
- encouraged to use `tox <https://tox.readthedocs.io>`_.
-
-When doing test-driven development, or running automated builds that need
-testing before they are deployed for downloading or use, it's often useful
-to be able to run a project's unit tests without actually deploying the project
-anywhere, even using the ``develop`` command. The ``test`` command runs a
-project's unit tests without actually deploying it, by temporarily putting the
-project's source on ``sys.path``, after first running ``build_ext -i`` and
-``egg_info`` to ensure that any C extensions and project metadata are
-up-to-date.
-
-To use this command, your project's tests must be wrapped in a ``unittest``
-test suite by either a function, a ``TestCase`` class or method, or a module
-or package containing ``TestCase`` classes. If the named suite is a module,
-and the module has an ``additional_tests()`` function, it is called and the
-result (which must be a ``unittest.TestSuite``) is added to the tests to be
-run. If the named suite is a package, any submodules and subpackages are
-recursively added to the overall test suite. (Note: if your project specifies
-a ``test_loader``, the rules for processing the chosen ``test_suite`` may
-differ; see the :ref:`test_loader <test_loader>` documentation for more details.)
-
-Note that many test systems including ``doctest`` support wrapping their
-non-``unittest`` tests in ``TestSuite`` objects. So, if you are using a test
-package that does not support this, we suggest you encourage its developers to
-implement test suite support, as this is a convenient and standard way to
-aggregate a collection of tests to be run under a common test harness.
-
-By default, tests will be run in the "verbose" mode of the ``unittest``
-package's text test runner, but you can get the "quiet" mode (just dots) if
-you supply the ``-q`` or ``--quiet`` option, either as a global option to
-the setup script (e.g. ``setup.py -q test``) or as an option for the ``test``
-command itself (e.g. ``setup.py test -q``). There is one other option
-available:
-
-``--test-suite=NAME, -s NAME``
- Specify the test suite (or module, class, or method) to be run
- (e.g. ``some_module.test_suite``). The default for this option can be
- set by giving a ``test_suite`` argument to the ``setup()`` function, e.g.::
-
- setup(
- # ...
- test_suite="my_package.tests.test_all"
- )
-
- If you did not set a ``test_suite`` in your ``setup()`` call, and do not
- provide a ``--test-suite`` option, an error will occur.
-
-New in 41.5.0: Deprecated the test command.
-
-
-.. _upload:
-
-``upload`` - Upload source and/or egg distributions to PyPI
-===========================================================
-
-The ``upload`` command was deprecated in version 40.0 and removed in version
-42.0. Use `twine <https://pypi.org/p/twine>`_ instead.
-
-For more information on the current best practices in uploading your packages
-to PyPI, see the Python Packaging User Guide's "Packaging Python Projects"
-tutorial specifically the section on `uploading the distribution archives
-<https://packaging.python.org/tutorials/packaging-projects/#uploading-the-distribution-archives>`_.
include_package_data=True
)
-.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
+.. tab:: pyproject.toml (**BETA**) [#beta]_
.. code-block:: toml
package_data={"mypkg": ["*.txt", "*.rst"]}
)
-.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
+.. tab:: pyproject.toml (**BETA**) [#beta]_
.. code-block:: toml
package_data={"": ["*.txt"], "mypkg1": ["data1.rst"]},
)
-.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
+.. tab:: pyproject.toml (**BETA**) [#beta]_
.. code-block:: toml
exclude_package_data={"mypkg": [".gitattributes"]},
)
-.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
+.. tab:: pyproject.toml (**BETA**) [#beta]_
.. code-block:: toml
}
)
-.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
+.. tab:: pyproject.toml (**BETA**) [#beta]_
.. code-block:: toml
include_package_data=True,
)
-.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
+.. tab:: pyproject.toml (**BETA**) [#beta]_
.. code-block:: toml
----
-.. [#experimental]
- Support for specifying package metadata and build configuration options via
- ``pyproject.toml`` is experimental and might change
- in the future. See :doc:`/userguide/pyproject_config`.
+.. [#beta]
+ Support for adding build configuration options via the ``[tool.setuptools]``
+ table in the ``pyproject.toml`` file. See :doc:`/userguide/pyproject_config`.
.. [#system-dirs] These locations can be discovered with the help of
third-party libraries such as :pypi:`platformdirs`.
:pep:`direct URLs <440#direct-references>`.
+.. _build-requires:
+
Build system requirement
========================
This needs to be specified in your ``pyproject.toml`` file
(if you have forgot what this is, go to :doc:`/userguide/quickstart` or :doc:`/build_meta`):
-.. code-block:: ini
+.. code-block:: toml
[build-system]
requires = ["setuptools"]
these dependencies when the package is installed. Although there is more
finesse to it, let's start with a simple example.
+.. tab:: pyproject.toml
+
+ .. code-block:: toml
+
+ [project]
+ # ...
+ dependencies = [
+ "docutils",
+ "BazSpam == 1.1",
+ ]
+ # ...
+
.. tab:: setup.cfg
.. code-block:: ini
],
)
-.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
-
- .. code-block:: toml
-
- [project]
- # ...
- dependencies = [
- "docutils",
- "BazSpam == 1.1",
- ]
- # ...
-
When your project is installed (e.g., using :pypi:`pip`), all of the dependencies not
already installed will be located (via `PyPI`_), downloaded, built (if necessary),
3.4, therefore, package that depends on it can elect to install it only when
the Python version is older than 3.4. To accomplish this
+.. tab:: pyproject.toml
+
+ .. code-block:: toml
+
+ [project]
+ # ...
+ dependencies = [
+ "enum34; python_version<'3.4'",
+ ]
+ # ...
+
.. tab:: setup.cfg
.. code-block:: ini
],
)
-.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
+Similarly, if you also wish to declare ``pywin32`` with a minimal version of 1.0
+and only install it if the user is using a Windows operating system:
+
+.. tab:: pyproject.toml
.. code-block:: toml
# ...
dependencies = [
"enum34; python_version<'3.4'",
+ "pywin32 >= 1.0; platform_system=='Windows'",
]
# ...
-Similarly, if you also wish to declare ``pywin32`` with a minimal version of 1.0
-and only install it if the user is using a Windows operating system:
-
.. tab:: setup.cfg
.. code-block:: ini
],
)
-.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
-
- .. code-block:: toml
-
- [project]
- # ...
- dependencies = [
- "enum34; python_version<'3.4'",
- "pywin32 >= 1.0; platform_system=='Windows'",
- ]
- # ...
-
The environmental markers that may be used for testing platform types are
detailed in :pep:`508`.
For example, let's consider a ``Package-A`` that offers
optional PDF support and requires two other dependencies for it to work:
+.. tab:: pyproject.toml
+
+ .. code-block:: toml
+
+ [project]
+ name = "Package-A"
+ # ...
+ [project.optional-dependencies]
+ PDF = ["ReportLab>=1.2", "RXP"]
+
.. tab:: setup.cfg
.. code-block:: ini
},
)
-.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
-
- .. code-block:: toml
-
- [project]
- name = "Package-A"
- # ...
- [project.optional-dependencies]
- PDF = ["ReportLab>=1.2", "RXP"]
-
.. sidebar::
.. tip::
own dependencies. For example, if ``Package-B`` needs ``Package-B`` with PDF support
installed, it might declare the dependency like this:
+.. tab:: pyproject.toml
+
+ .. code-block:: toml
+
+ [project]
+ name = "Package-B"
+ # ...
+ dependencies = [
+ "Package-A[PDF]"
+ ]
+
.. tab:: setup.cfg
.. code-block:: ini
...,
)
-.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
-
- .. code-block:: toml
-
- [project]
- name = "Package-B"
- # ...
- dependencies = [
- "Package-A[PDF]"
- ]
-
This will cause ``ReportLab`` to be installed along with ``Package-A``, if ``Package-B`` is
installed -- even if ``Package-A`` was already installed. In this way, a project
can encapsulate groups of optional "downstream dependencies" under a feature
In some cases, you might need to specify the minimum required python version.
This can be configured as shown in the example below.
+.. tab:: pyproject.toml
+
+ .. code-block:: toml
+
+ [project]
+ name = "Package-B"
+ requires-python = ">=3.6"
+ # ...
+
.. tab:: setup.cfg
.. code-block:: ini
)
-.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
-
- .. code-block:: toml
-
- [project]
- name = "Package-B"
- requires-python = ">=3.6"
- # ...
-
-----
-
-.. rubric:: Notes
-
-.. [#experimental]
- While the ``[build-system]`` table should always be specified in the
- ``pyproject.toml`` file, support for adding package metadata and build configuration
- options via the ``[project]`` and ``[tool.setuptools]`` tables is still
- experimental and might change in future releases.
- See :doc:`/userguide/pyproject_config`.
-
-
.. _PyPI: https://pypi.org
-Tagging and "Daily Build" or "Snapshot" Releases
-------------------------------------------------
-
-When a set of related projects are under development, it may be important to
-track finer-grained version increments than you would normally use for e.g.
-"stable" releases. While stable releases might be measured in dotted numbers
-with alpha/beta/etc. status codes, development versions of a project often
-need to be tracked by revision or build number or even build date. This is
-especially true when projects in development need to refer to one another, and
-therefore may literally need an up-to-the-minute version of something!
-
-To support these scenarios, ``setuptools`` allows you to "tag" your source and
-egg distributions by adding one or more of the following to the project's
-"official" version identifier:
-
-* A manually-specified pre-release tag, such as "build" or "dev", or a
- manually-specified post-release tag, such as a build or revision number
- (``--tag-build=STRING, -bSTRING``)
-
-* An 8-character representation of the build date (``--tag-date, -d``), as
- a postrelease tag
-
-You can add these tags by adding ``egg_info`` and the desired options to
-the command line ahead of the ``sdist`` or ``bdist`` commands that you want
-to generate a daily build or snapshot for. See the section below on the
-:ref:`egg_info <egg_info>` command for more details.
-
-(Also, before you release your project, be sure to see the section on
-:ref:`Specifying Your Project's Version` for more information about how pre- and
-post-release tags affect how version numbers are interpreted. This is
-important in order to make sure that dependency processing tools will know
-which versions of your project are newer than others.)
-
-Finally, if you are creating builds frequently, and either building them in a
-downloadable location or are copying them to a distribution server, you should
-probably also check out the :ref:`rotate <rotate>` command, which lets you automatically
-delete all but the N most-recently-modified distributions matching a glob
-pattern. So, you can use a command line like::
-
- 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
-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.
-
-If you have to manage automated builds for multiple packages, each with
-different tagging and rotation policies, you may also want to check out the
-:ref:`alias <alias>` command, which would let each package define an alias like ``daily``
-that would perform the necessary tag, build, and rotate commands. Then, a
-simpler script or cron job could just run ``setup.py daily`` in each project
-directory. (And, you could also define sitewide or per-user default versions
-of the ``daily`` alias, so that projects that didn't define their own would
-use the appropriate defaults.)
-
-Generating Source Distributions
--------------------------------
-
-``setuptools`` enhances the distutils' default algorithm for source file
-selection with pluggable endpoints for looking up files to include. If you are
-using a revision control system, and your source distributions only need to
-include files that you're tracking in revision control, use a corresponding
-plugin instead of writing a ``MANIFEST.in`` file. See the section below on
-:ref:`Adding Support for Revision Control Systems` for information on plugins.
-
-If you need to include automatically generated files, or files that are kept in
-an unsupported revision control system, you'll need to create a ``MANIFEST.in``
-file to specify any files that the default file location algorithm doesn't
-catch. See the distutils documentation for more information on the format of
-the ``MANIFEST.in`` file.
-
-But, be sure to ignore any part of the distutils documentation that deals with
-``MANIFEST`` or how it's generated from ``MANIFEST.in``; setuptools shields you
-from these issues and doesn't work the same way in any case. Unlike the
-distutils, setuptools regenerates the source distribution manifest file
-every time you build a source distribution, and it builds it inside the
-project's ``.egg-info`` directory, out of the way of your main project
-directory. You therefore need not worry about whether it is up-to-date or not.
-
-Indeed, because setuptools' approach to determining the contents of a source
-distribution is so much simpler, its ``sdist`` command omits nearly all of
-the options that the distutils' more complex ``sdist`` process requires. For
-all practical purposes, you'll probably use only the ``--formats`` option, if
-you use any option at all.
-
-
-Making "Official" (Non-Snapshot) Releases
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-When you make an official release, creating source or binary distributions,
-you will need to override the tag settings from ``setup.cfg``, so that you
-don't end up registering versions like ``foobar-0.7a1.dev-r34832``. This is
-easy to do if you are developing on the trunk and using tags or branches for
-your releases - just make the change to ``setup.cfg`` after branching or
-tagging the release, so the trunk will still produce development snapshots.
-
-Alternately, if you are not branching for releases, you can override the
-default version options on the command line, using something like::
-
- 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
-commands will use the plain version from your ``setup.py``, without adding the
-build designation string.
-
-Of course, if you will be doing this a lot, you may wish to create a personal
-alias for this operation, e.g.::
-
- setup.py alias -u release egg_info -Db ""
-
-You can then use it like this::
-
- 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 :ref:`egg_info <egg_info>` and
-:ref:`alias <alias>` commands for more ideas.
-
-Distributing Extensions compiled with Cython
---------------------------------------------
-
-``setuptools`` will detect at build time whether Cython is installed or not.
-If Cython is not found ``setuptools`` will ignore pyx files.
-
-To ensure Cython is available, include Cython in the build-requires section
-of your pyproject.toml::
-
- [build-system]
- 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
-setup-requires of setup.cfg::
-
- [options]
- setup_requires =
- ...
- cython
-
-As long as Cython is present in the build environment, ``setuptools`` includes
-transparent support for building Cython extensions, as
-long as extensions are defined using ``setuptools.Extension``.
-
-If you follow these rules, you can safely list ``.pyx`` files as the source
-of your ``Extension`` objects in the setup script. If it is, then ``setuptools``
-will use it.
-
-Of course, for this to work, your source distributions must include the C
-code generated by Cython, as well as your original ``.pyx`` files. This means
-that you will probably want to include current ``.c`` files in your revision
-control system, rebuilding them whenever you check changes in for the ``.pyx``
-source files. This will ensure that people tracking your project in a revision
-control system will be able to build it even if they don't have Cython
-installed, and that your source releases will be similarly usable with or
-without Cython.
-
-
.. _Specifying Your Project's Version:
Specifying Your Project's Version
----------------------------------
+=================================
Setuptools can work well with most versioning schemes. Over the years,
-setuptools has tried to closely follow the
-`PEP 440 <https://www.python.org/dev/peps/pep-0440/>`_ scheme, but it
+setuptools has tried to closely follow the :pep:`440` scheme, but it
also supports legacy versions. There are, however, a
few special things to watch out for, in order to ensure that setuptools and
other tools can always tell what version of your package is newer than another
Once you've decided on a version numbering scheme for your project, you can
have setuptools automatically tag your in-development releases with various
-pre- or post-release tags. See the following sections for more details:
+pre- or post-release tags. See the following section for more details.
+
+
+Tagging and "Daily Build" or "Snapshot" Releases
+------------------------------------------------
+
+.. warning::
+ Please note that running ``python setup.py ...`` directly is no longer
+ considered a good practice and that in the future the commands ``egg_info``
+ and ``rotate`` will be deprecated.
+
+ As a result, the instructions and information presented in this section
+ should be considered **transitional** while setuptools don't provide a
+ mechanism for tagging releases.
+
+ Meanwhile, if you can also consider using :pypi:`setuptools-scm` to achieve
+ similar objectives.
+
+
+When a set of related projects are under development, it may be important to
+track finer-grained version increments than you would normally use for e.g.
+"stable" releases. While stable releases might be measured in dotted numbers
+with alpha/beta/etc. status codes, development versions of a project often
+need to be tracked by revision or build number or even build date. This is
+especially true when projects in development need to refer to one another, and
+therefore may literally need an up-to-the-minute version of something!
+
+To support these scenarios, ``setuptools`` allows you to "tag" your source and
+egg distributions by adding one or more of the following to the project's
+"official" version identifier:
+
+* A manually-specified pre-release tag, such as "build" or "dev", or a
+ manually-specified post-release tag, such as a build or revision number
+ (``--tag-build=STRING, -bSTRING``)
+
+* An 8-character representation of the build date (``--tag-date, -d``), as
+ a postrelease tag
+
+You can add these tags by adding ``egg_info`` and the desired options to
+the command line ahead of the ``sdist`` or ``bdist`` commands that you want
+to generate a daily build or snapshot for. See the section below on the
+:ref:`egg_info <egg_info>` command for more details.
+
+(Also, before you release your project, be sure to see the section on
+:ref:`Specifying Your Project's Version` for more information about how pre- and
+post-release tags affect how version numbers are interpreted. This is
+important in order to make sure that dependency processing tools will know
+which versions of your project are newer than others).
+
+Finally, if you are creating builds frequently, and either building them in a
+downloadable location or are copying them to a distribution server, you should
+probably also check out the :ref:`rotate <rotate>` command, which lets you automatically
+delete all but the N most-recently-modified distributions matching a glob
+pattern. So, you can use a command line like::
-* `Tagging and "Daily Build" or "Snapshot" Releases`_
-* The :ref:`egg_info <egg_info>` command
+ 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
+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.
+
+If you have to manage automated builds for multiple packages, each with
+different tagging and rotation policies, you may also want to check out the
+:ref:`alias <alias>` command, which would let each package define an alias like ``daily``
+that would perform the necessary tag, build, and rotate commands. Then, a
+simpler script or cron job could just run ``setup.py daily`` in each project
+directory. (And, you could also define sitewide or per-user default versions
+of the ``daily`` alias, so that projects that didn't define their own would
+use the appropriate defaults.)
+
+Making "Official" (Non-Snapshot) Releases
+-----------------------------------------
+
+When you make an official release, creating source or binary distributions,
+you will need to override the tag settings from ``setup.cfg``, so that you
+don't end up registering versions like ``foobar-0.7a1.dev-r34832``. This is
+easy to do if you are developing on the trunk and using tags or branches for
+your releases - just make the change to ``setup.cfg`` after branching or
+tagging the release, so the trunk will still produce development snapshots.
+
+Alternately, if you are not branching for releases, you can override the
+default version options on the command line, using something like::
+
+ 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
+commands will use the plain version from your ``setup.py``, without adding the
+build designation string.
+
+Of course, if you will be doing this a lot, you may wish to create a personal
+alias for this operation, e.g.::
+
+ setup.py alias -u release egg_info -Db ""
+
+You can then use it like this::
+
+ 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 :ref:`egg_info <egg_info>` and
+:ref:`alias <alias>` commands for more ideas.
defined thus::
project_root_directory
- ├── setup.py # and/or setup.cfg, pyproject.toml
+ ├── pyproject.toml # and/or setup.cfg, setup.py
└── src
└── timmins
├── __init__.py
``timmins.hello_world``, add a console script entry point to your
configuration:
+.. tab:: pyproject.toml
+
+ .. code-block:: toml
+
+ [project.scripts]
+ hello-world = "timmins:hello_world"
+
.. tab:: setup.cfg
.. code-block:: ini
}
)
-.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
-
- .. code-block:: toml
-
- [project.scripts]
- hello-world = "timmins:hello_world"
-
After installing the package, a user may invoke that function by simply calling
``hello-world`` on the command line:
Then, we can add a GUI script entry point:
+.. tab:: pyproject.toml
+
+ .. code-block:: toml
+
+ [project.gui-scripts]
+ hello-world = "timmins:hello_world"
+
.. tab:: setup.cfg
.. code-block:: ini
.. tab:: setup.py
.. code-block:: python
-
+
from setuptools import setup
setup(
}
)
-.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
-
- .. code-block:: toml
-
- [project.gui-scripts]
- hello-world = "timmins:hello_world"
-
.. note::
To be able to import ``PySimpleGUI``, you need to add ``pysimplegui`` to your package dependencies.
See :doc:`/userguide/dependency_management` for more information.
directory structure::
timmins
- ├── setup.py # and/or setup.cfg, pyproject.toml
+ ├── pyproject.toml # and/or setup.cfg, setup.py
└── src
└── timmins
└── __init__.py
``timmins-plugin-fancy``, and set it up with the following directory structure::
timmins-plugin-fancy
- ├── setup.py # and/or setup.cfg, pyproject.toml
+ ├── pyproject.toml # and/or setup.cfg, setup.py
└── src
└── timmins_plugin_fancy
└── __init__.py
``timmins`` package. We can do that by adding the following in the configuration
of ``timmins-plugin-fancy``:
+.. tab:: pyproject.toml
+
+ .. code-block:: toml
+
+ # Note the quotes around timmins.display in order to escape the dot .
+ [project.entry-points."timmins.display"]
+ excl = "timmins_plugin_fancy:excl_display"
+
.. tab:: setup.cfg
.. code-block:: ini
}
)
-.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
-
- .. code-block:: toml
-
- # Note the quotes around timmins.display in order to escape the dot .
- [project.entry-points."timmins.display"]
- excl = "timmins_plugin_fancy:excl_display"
-
Basically, this configuration states that we are a supplying an entry point
under the group ``timmins.display``. The entry point is named ``excl`` and it
refers to the function ``excl_display`` defined by the package ``timmins-plugin-fancy``.
The configuration of ``timmins-plugin-fancy`` would then change to:
+.. tab:: pyproject.toml
+
+ .. code-block:: toml
+
+ [project.entry-points."timmins.display"]
+ excl = "timmins_plugin_fancy:excl_display"
+ lined = "timmins_plugin_fancy:lined_display"
+
.. tab:: setup.cfg
.. code-block:: ini
}
)
-.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
-
- .. code-block:: toml
-
- [project.entry-points."timmins.display"]
- excl = "timmins_plugin_fancy:excl_display"
- lined = "timmins_plugin_fancy:lined_display"
-
On the ``timmins`` side, we can also use a different strategy of loading entry
points. For example, we can search for a specific display style:
----
-.. [#experimental]
- Support for specifying package metadata and build configuration options via
- ``pyproject.toml`` is experimental and might change
- in the future. See :doc:`/userguide/pyproject_config`.
-
.. [#use_for_scripts]
Reference: https://packaging.python.org/en/latest/specifications/entry-points/#use-for-scripts
--- /dev/null
+==========================
+Building Extension Modules
+==========================
+
+Setuptools can build C/C++ extension modules. The keyword argument
+``ext_modules`` of ``setup()`` should be a list of instances of the
+:class:`setuptools.Extension` class.
+
+
+For example, let's consider a simple project with only one extension module::
+
+ <project_folder>
+ ├── pyproject.toml
+ └── foo.c
+
+and all project metadata configuration in the ``pyproject.toml`` file:
+
+.. code-block:: toml
+
+ # pyproject.toml
+ [build-system]
+ requires = ["setuptools"]
+ build-backend = "setuptools.build_meta"
+
+ [project]
+ name = "mylib-foo" # as it would appear on PyPI
+ version = "0.42"
+
+To instruct setuptools to compile the ``foo.c`` file into the extension module
+``mylib.foo``, we need to add a ``setup.py`` file similar to the following:
+
+.. code-block:: python
+
+ from setuptools import Extension, setup
+
+ setup(
+ ext_modules=[
+ Extension(
+ name="mylib.foo", # as it would be imported
+ # may include packages/namespaces separated by `.`
+
+ sources=["foo.c"], # all sources are compiled into a single binary file
+ ),
+ ]
+ )
+
+.. seealso::
+ You can find more information on the `Python docs about C/C++ extensions`_.
+ Alternatively, you might also be interested in learn about `Cython`_.
+
+ If you plan to distribute a package that uses extensions across multiple
+ platforms, :pypi:`cibuildwheel` can also be helpful.
+
+.. important::
+ All files used to compile your extension need to be available on the system
+ when building the package, so please make sure to include some documentation
+ on how developers interested in building your package from source
+ can obtain operating system level dependencies
+ (e.g. compilers and external binary libraries/artifacts).
+
+ You will also need to make sure that all auxiliary files that are contained
+ inside your :term:`project` (e.g. C headers authored by you or your team)
+ are configured to be included in your :term:`sdist <Source Distribution (or "sdist")>`.
+ Please have a look on our section on :ref:`Controlling files in the distribution`.
+
+
+Compiler and linker options
+===========================
+
+The command ``build_ext`` builds C/C++ extension modules. It creates
+a command line for running the compiler and linker by combining
+compiler and linker options from various sources:
+
+.. Reference: `test_customize_compiler` in distutils/tests/test_sysconfig.py
+
+* the ``sysconfig`` variables ``CC``, ``CXX``, ``CCSHARED``,
+ ``LDSHARED``, and ``CFLAGS``,
+* the environment variables ``CC``, ``CPP``,
+ ``CXX``, ``LDSHARED`` and ``LDFLAGS``,
+ ``CFLAGS``, ``CPPFLAGS``, ``LDFLAGS``,
+* the ``Extension`` attributes ``include_dirs``,
+ ``library_dirs``, ``extra_compile_args``, ``extra_link_args``,
+ ``runtime_library_dirs``.
+
+.. Ignoring AR, ARFLAGS, RANLIB here because they are used by the (obsolete?) build_clib, not build_ext.
+
+The resulting command line is then processed by the compiler and linker.
+According to the GCC manual sections on `directory options`_ and
+`environment variables`_, the C/C++ compiler searches for files named in
+``#include <file>`` directives in the following order:
+
+* first, in directories given by ``-I`` options (in left-to-right order),
+* then, in directories given by the environment variable ``CPATH`` (in left-to-right order),
+* then, in directories given by ``-isystem`` options (in left-to-right order),
+* then, in directories given by the environment variable ``C_INCLUDE_PATH`` (for C) and ``CPLUS_INCLUDE_PATH`` (for C++),
+* then, in standard system directories,
+* finally, in directories given by ``-idirafter`` options (in left-to-right order).
+
+The linker searches for libraries in the following order:
+
+* first, in directories given by ``-L`` options (in left-to-right order),
+* then, in directories given by the environment variable ``LIBRARY_PATH`` (in left-to-right order).
+
+
+Distributing Extensions compiled with Cython
+============================================
+
+When your :pypi:`Cython` extension modules *are declared using the*
+:class:`setuptools.Extension` *class*, ``setuptools`` will detect at build time
+whether Cython is installed or not.
+
+If Cython is present, then ``setuptools`` will use it to build the ``.pyx`` files.
+Otherwise, ``setuptools`` will try to find and compile the equivalent ``.c`` files
+(instead of ``.pyx``). These files can be generated using the
+`cython command line tool`_.
+
+You can ensure that Cython is always automatically installed into the build
+environment by including it as a :ref:`build dependency <build-requires>` in
+your ``pyproject.toml``:
+
+.. code-block:: toml
+
+ [build-system]
+ requires = [..., "cython"]
+
+Alternatively, you can include the ``.c`` code that is pre-compiled by Cython
+into your source distribution, alongside the original ``.pyx`` files (this
+might save a few seconds when building from an ``sdist``).
+To improve version compatibility, you probably also want to include current
+``.c`` files in your :wiki:`revision control system`, and rebuild them whenever
+you check changes in for the ``.pyx`` source files.
+This will ensure that people tracking your project will be able to build it
+without installing Cython, and that there will be no variation due to small
+differences in the generate C files.
+Please checkout our docs on :ref:`controlling files in the distribution` for
+more information.
+
+----
+
+Extension API Reference
+=======================
+
+.. autoclass:: setuptools.Extension
+
+
+.. _Python docs about C/C++ extensions: https://docs.python.org/3/extending/extending.html
+.. _Cython: https://cython.readthedocs.io/en/stable/index.html
+.. _directory options: https://gcc.gnu.org/onlinedocs/gcc/Directory-Options.html
+.. _environment variables: https://gcc.gnu.org/onlinedocs/gcc/Environment-Variables.html>
+.. _cython command line tool: https://cython.readthedocs.io/en/stable/src/userguide/source_files_and_compilation.html
package_discovery
entry_point
dependency_management
+ ext_modules
datafiles
development_mode
distribution
extension
declarative_config
pyproject_config
- commands
miscellaneous
---
For the most common use cases, ``setuptools`` will automatically find out which
files are necessary for distributing the package.
-Th
is includes all :term:`pure Python modules <Pure Module>` in the
+Th
ese include all :term:`pure Python modules <Pure Module>` in the
``py_modules`` or ``packages`` configuration, and the C sources (but not C
-headers) listed as part of extensions when creating a :term:`Source
-Distribution (or "sdist")`.
+headers) listed as part of extensions when creating a :term:`source
+distribution (or "sdist")`.
However, when building more complex packages (e.g. packages that include
non-Python files, or that need to use custom C headers), you might find that
not all files present in your project folder are included in package
:term:`distribution archive <Distribution Package>`.
-In these situations you can use a ``setuptools``
-:ref:`plugin <Adding Support for Revision Control Systems>`,
-such as :pypi:`setuptools-scm` or :pypi:`setuptools-svn` to automatically
-include all files tracked by your Revision Control System into the ``sdist``.
+If you are using a :wiki:`Revision Control System`, such as git_ or mercurial_,
+and your source distributions only need to include files that you're
+tracking in revision control, you can use a ``setuptools`` :ref:`plugin <Adding
+Support for Revision Control Systems>`, such as :pypi:`setuptools-scm` or
+:pypi:`setuptools-svn` to automatically include all tracked files into the ``sdist``.
.. _Using MANIFEST.in:
-Alternatively, if you need finer control, you can add a ``MANIFEST.in`` file at
-the root of your project.
+Alternatively, if you need finer control over the files (e.g. you don't want to
+distribute :wiki:`CI/CD`-related files) or you need automatically generated files,
+you can add a ``MANIFEST.in`` file at the root of your project,
+to specify any files that the default file location algorithm doesn't catch.
+
This file contains instructions that tell ``setuptools`` which files exactly
should be part of the ``sdist`` (or not).
A comprehensive guide to ``MANIFEST.in`` syntax is available at the
:doc:`PyPA's Packaging User Guide <PyPUG:guides/using-manifest-in>`.
+.. attention::
+ Please note that ``setuptools`` supports the ``MANIFEST.in``,
+ and not ``MANIFEST`` (no extension). Any documentation, tutorial or example
+ that recommends using ``MANIFEST`` (no extension) is likely outdated.
+
+.. tip::
+ The ``MANIFEST.in`` file contains commands that allow you to discover and
+ manipulate lists of files. There are many commands that can be used with
+ different objectives, but you should try to not make your ``MANIFEST.in``
+ file too fine grained.
+
+ A good idea is to start with a ``graft`` command (to add all
+ files inside a set of directories) and then fine tune the file selection
+ by removing the excess or adding isolated files.
+
+An example of ``MANIFEST.in`` for a simple project that organized according to a
+:ref:`src-layout` is:
+
+.. code-block:: bash
+
+ # MANIFEST.in -- just for illustration
+ graft src
+ graft tests
+ graft docs
+ # `-> adds all files inside a directory
+
+ include tox.ini
+ # `-> matches file paths relative to the root of the project
+
+ global-exclude *~ *.py[cod] *.so
+ # `-> matches file names (regardless of directory)
+
Once the correct files are present in the ``sdist``, they can then be used by
binary extensions during the build process, or included in the final
:term:`wheel <Wheel>` [#build-process]_ if you configure ``setuptools`` with
and is ready to be unpacked into a running installation of Python or
:term:`Virtual Environment`.
Therefore it only contains items that are required during runtime.
+
+.. _git: https://git-scm.com
+.. _mercurial: https://www.mercurial-scm.org
packages=['mypkg', 'mypkg.subpkg1', 'mypkg.subpkg2']
)
-.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
+.. tab:: pyproject.toml (**BETA**) [#beta]_
.. code-block:: toml
# ...
)
-.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
+.. tab:: pyproject.toml (**BETA**) [#beta]_
.. code-block:: toml
Automatic discovery
===================
-.. warning:: Automatic discovery is an **experimental** feature and might change
+.. warning:: Automatic discovery is an **beta** feature and might change
(or be completely removed) in the future.
See :ref:`custom-discovery` for a stable way of configuring ``setuptools``.
# or
from setuptools import find_namespace_packages
-.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
+.. tab:: pyproject.toml (**BETA**) [#beta]_
.. code-block:: toml
``pkg.namespace`` is ignored by ``find_packages()``
(see ``find_namespace_packages()`` below).
-.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
+.. tab:: pyproject.toml (**BETA**) [#beta]_
.. code-block:: toml
On the other hand, ``find_namespace_packages()`` will scan all
directories.
-.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
+.. tab:: pyproject.toml (**BETA**) [#beta]_
.. code-block:: toml
----
-.. [#experimental]
- Support for specifying package metadata and build configuration options via
- ``pyproject.toml`` is experimental and might change
- in the future. See :doc:`/userguide/pyproject_config`.
+.. [#beta]
+ Support for adding build configuration options via the ``[tool.setuptools]``
+ table in the ``pyproject.toml`` file is still in **beta** stage.
+ See :doc:`/userguide/pyproject_config`.
.. [#layout1] https://blog.ionelmc.ro/2014/05/25/python-packaging/#the-structure
.. [#layout2] https://blog.ionelmc.ro/2017/09/25/rehashing-the-src-layout/
Configuring setuptools using ``pyproject.toml`` files
-----------------------------------------------------
-.. note:: New in 61.0.0 (**experimental**)
-
-.. warning::
- Support for declaring :doc:`project metadata
- <PyPUG:specifications/declaring-project-metadata>` or configuring
- ``setuptools`` via ``pyproject.toml`` files is still experimental and might
- change in future releases.
+.. note:: New in 61.0.0
.. important::
For the time being, ``pip`` still might require a ``setup.py`` file
Setuptools-specific configuration
=================================
+.. warning::
+ Support for declaring configurations not standardized by :pep:`621`
+ (i.e. the ``[tool.setuptools]`` table),
+ is still in **beta** stage and might change in future releases.
+
While the standard ``project`` table in the ``pyproject.toml`` file covers most
of the metadata used during the packaging process, there are still some
``setuptools``-specific configurations that can be set by users that require
``exclude-package-data`` table/inline-table
``license-files`` array of glob patterns **Provisional** - likely to change with :pep:`639`
(by default: ``['LICEN[CS]E*', 'COPYING*', 'NOTICE*', 'AUTHORS*']``)
-``data-files`` table/inline-table **Deprecated** - check :doc:`/userguide/datafiles`
+``data-files`` table/inline-table **Discouraged** - check :doc:`/userguide/datafiles`
``script-files`` array **Deprecated** - equivalent to the ``script`` keyword in ``setup.py``
(should be avoided in favour of ``project.scripts``)
``provides`` array **Ignored by pip**
Installation
============
-To install the latest version of setuptools, use::
+You can install the latest version of ``setuptools`` using :pypi:`pip`::
pip install --upgrade setuptools
+Most of the times, however, you don't have to...
-Python packaging at a glance
-============================
-The landscape of Python packaging is shifting and ``Setuptools`` has evolved to
-only provide backend support, no longer being the de-facto packaging tool in
-the market. Every python package must provide a ``pyproject.toml`` and specify
+Instead, when creating new Python packages, it is recommended to use
+a command line tool called :pypi:`build`. This tool will automatically download
+``setuptools`` and any other build-time dependencies that your project might
+have. You just need to specify them in a ``pyproject.toml`` file at the root of
+your package, as indicated in the :ref:`following section <basic-use>`.
+
+.. _install-build:
+
+You can also :doc:`install build <build:installation>` using :pypi:`pip`::
+
+ pip install --upgrade build
+
+This will allow you to run the command: ``python -m build``.
+
+.. important::
+ Please note that some operating systems might be equipped with
+ the ``python3`` and ``pip3`` commands instead of ``python`` and ``pip``
+ (but they should be equivalent).
+ If you don't have ``pip`` or ``pip3`` available in your system, please
+ check out :doc:`pip installation docs <pip:installation>`.
+
+
+Every python package must provide a ``pyproject.toml`` and specify
the backend (build system) it wants to use. The distribution can then
be generated with whatever tool that provides a ``build sdist``-like
-functionality. While this may appear cumbersome, given the added pieces,
-it in fact tremendously enhances the portability of your package. The
-change is driven under :pep:`PEP 517 <517#build-requirements>`. To learn more about Python packaging in general,
-navigate to the :ref:`bottom <packaging-resources>` of this page.
+functionality.
+
+.. _basic-use:
Basic Use
=========
-For basic use of setuptools, you will need a ``pyproject.toml`` with the
-exact following info, which declares you want to use ``setuptools`` to
-package your project:
+
+When creating a Python package, you must provide a ``pyproject.toml`` file
+containing a ``build-system`` section similar to the example below:
.. code-block:: toml
requires = ["setuptools"]
build-backend = "setuptools.build_meta"
-Then, you will need to specify your package information such as metadata,
-contents, dependencies, etc.
+This section declares what are your build system dependencies, and which
+library will be used to actually do the packaging.
+
+In addition to specifying a build system, you also will need to add
+some package information such as metadata, contents, dependencies, etc.
+This can be done in the same ``pyproject.toml`` [#beta]_ file,
+or in a separated one: ``setup.cfg`` or ``setup.py`` (please note however
+that configuring new projects via ``setup.py`` is discouraged [#setup.py]_).
-Setuptools currently supports configurations from either ``setup.cfg``,
-``setup.py`` or ``pyproject.toml`` [#experimental]_ files, however, configuring new
-projects via ``setup.py`` is discouraged [#setup.py]_.
+The following example demonstrates a minimum configuration
+(which assumes the project depends on :pypi:`requests` and
+:pypi:`importlib-metadata` to be able to run):
-The following example demonstrates a minimum configuration:
+.. tab:: pyproject.toml
+
+ .. code-block:: toml
+
+ [project]
+ name = "mypackage"
+ version = "0.0.1"
+ dependencies = [
+ "requests",
+ 'importlib-metadata; python_version<"3.8"',
+ ]
+
+ See :doc:`/userguide/pyproject_config` for more information.
.. tab:: setup.cfg
version = 0.0.1
[options]
- packages = mypackage
install_requires =
requests
importlib-metadata; python_version < "3.8"
setup(
name='mypackage',
version='0.0.1',
- packages=['mypackage'],
install_requires=[
'requests',
'importlib-metadata; python_version == "3.8"',
See :doc:`/references/keywords` for more information.
-.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
-
- .. code-block:: toml
-
- [project]
- name = "mypackage"
- version = "0.0.1"
- dependencies = [
- "requests",
- 'importlib-metadata; python_version<"3.8"',
- ]
-
- See :doc:`/userguide/pyproject_config` for more information.
-
-This is what your project would look like::
+Finally, you will need to organize your Python code to make it ready for
+distributing into something that looks like the following
+(optional files marked with ``#``)::
- ~/mypackage/
- pyproject.toml
- setup.cfg # or setup.py
- mypackage/__init__.py
+ mypackage
+ ├── pyproject.toml
+ | # setup.cfg or setup.py (depending on the confuguration method)
+ | # README.rst or README.md (a nice description of your package)
+ | # LICENCE (properly chosen license information, e.g. MIT, BSD-3, GPL-3, MPL-2, etc...)
+ └── mypackage
+ ├── __init__.py
+ └── ... (other Python files)
-Then, you need a builder, such as :std:doc:`PyPA build <pypa-build:index>`
-which you can obtain via ``pip install build``. After downloading it, invoke
-the builder::
+With :ref:`build installed in you system <install-build>`, you can then run::
python -m build
-You now have your distribution ready (e.g. a ``tar.gz`` file and a ``.whl``
-file in the ``dist`` directory), which you can upload to PyPI!
+You now have your distribution ready (e.g. a ``tar.gz`` file and a ``.whl`` file
+in the ``dist`` directory), which you can :doc:`upload <twine:index>` to PyPI_!
-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
-project. And maybe your project will have grown by then to include a few
+Of course, before you release your project to PyPI_, you'll want to add a bit
+more information to help people find or learn about your project.
+And maybe your project will have grown by then to include a few
dependencies, and perhaps some data files and scripts. In the next few sections,
we will walk through the additional but essential information you need
to specify to properly package your project.
-Automatic package discovery
-===========================
-For simple projects, it's usually easy enough to manually add packages to
-the ``packages`` keyword in ``setup.cfg``. However, for very large projects,
-it can be a big burden to keep the package list updated.
-Therefore, ``setuptools`` provides a convenient way to automatically list all
-the packages in your project directory:
+..
+ TODO: A previous generation of this document included a section called
+ "Python packaging at a glance". This is a nice title, but the content
+ removed because it assumed the reader had familiarity with the history of
+ setuptools and PEP 517. We should take advantage of this nice title and add
+ this section back, but use it to explain important concepts of the
+ ecosystem, such as "sdist", "wheel", "index". It would also be nice if we
+ could have a diagram for that (explaining for example that "wheels" are
+ built from "sdists" not the source tree).
+
+
+Overview
+========
+
+Package discovery
+-----------------
+For projects that follow a simple directory structure, ``setuptools`` should be
+able to automatically detect all :term:`packages <package>` and
+:term:`namespaces <namespace>`. However, complex projects might include
+additional folders and supporting files that not necessarily should be
+distributed (or that can confuse ``setuptools`` auto discovery algorithm).
+
+Therefore, ``setuptools`` provides a convenient way to customize
+which packages should be distributed and in which directory they should be
+found, as shown in the example below:
+
+.. tab:: pyproject.toml (**BETA**) [#beta]_
+
+ .. code-block:: toml
+
+ # ...
+ [tool.setuptools.packages]
+ find = {} # Scan the project directory with the default parameters
+
+ # OR
+ [tool.setuptools.packages.find]
+ where = ["src"] # ["."] by default
+ include = ["mypackage*"] # ["*"] by default
+ exclude = ["mypackage.tests*"] # empty by default
+ namespaces = false # true by default
.. tab:: setup.cfg
# ...
)
-.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
-
- .. code-block:: toml
-
- # ...
- [tool.setuptools.packages]
- find = {} # Scan the project directory with the default parameters
-
- # OR
- [tool.setuptools.packages.find]
- where = ["src"] # ["."] by default
- include = ["mypackage*"] # ["*"] by default
- exclude = ["mypackage.tests*"] # empty by default
- namespaces = false # true by default
-
When you pass the above information, alongside other necessary information,
``setuptools`` walks through the directory specified in ``where`` (omitted
here as the package resides in the current directory) and filters the packages
-it can find following the ``include`` (defaults to none), then removes
-those that match the ``exclude`` and returns a list of Python packages. The above
-setup also allows you to adopt a ``src/`` layout. For more details and advanced
-use, go to :ref:`package_discovery`.
+it can find following the ``include`` patterns (defaults to ``*``), then it removes
+those that match the ``exclude`` patterns and returns a list of Python packages.
+
+For more details and advanced use, go to :ref:`package_discovery`.
.. tip::
Starting with version 61.0.0, setuptools' automatic discovery capabilities
:ref:`flat-layout` and :ref:`src-layout`) without requiring any
special configuration. Check out our :ref:`reference docs <package_discovery>`
for more information, but please keep in mind that this functionality is
- still considered **experimental** and might change (or even be removed) in
- future releases.
+ still considered **beta** and might change in future releases.
Entry points and automatic script creation
-===========================================
-Setuptools supports automatic creation of scripts upon installation, that runs
+-------------------------------------------
+Setuptools supports automatic creation of scripts upon installation, that run
code within your package if you specify them as :doc:`entry points
<PyPUG:specifications/entry-points>`.
-This is what allows you to run commands like ``pip install`` instead of having
+An example of how this feature can be used in ``pip``:
+it allows you to run commands like ``pip install`` instead of having
to type ``python -m pip install``.
+
The following configuration examples show how to accomplish this:
+
+.. tab:: pyproject.toml
+
+ .. code-block:: toml
+
+ [project.scripts]
+ cli-name = "mypkg.mymodule:some_func"
+
.. tab:: setup.cfg
.. code-block:: ini
}
)
-.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
-
- .. code-block:: toml
-
- [project.scripts]
- cli-name = "mypkg.mymodule:some_func"
-
When this project is installed, a ``cli-name`` executable will be created.
``cli-name`` will invoke the function ``some_func`` in the
``mypkg/mymodule.py`` file when called by the user.
Dependency management
-=====================
+---------------------
Packages built with ``setuptools`` can specify dependencies to be automatically
installed when the package itself is installed.
The example below show how to configure this kind of dependencies:
+.. tab:: pyproject.toml
+
+ .. code-block:: toml
+
+ [project]
+ # ...
+ dependencies = [
+ "docutils",
+ "requires <= 0.4",
+ ]
+ # ...
+
.. tab:: setup.cfg
.. code-block:: ini
# ...
)
-.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
-
- .. code-block:: toml
-
- [project]
- # ...
- dependencies = [
- "docutils",
- "requires <= 0.4",
- ]
- # ...
-
Each dependency is represented by a string that can optionally contain version requirements
(e.g. one of the operators <, >, <=, >=, == or !=, followed by a version identifier),
and/or conditional environment markers, e.g. ``sys_platform == "win32"``
.. _Including Data Files:
Including Data Files
-====================
+--------------------
Setuptools offers three ways to specify data files to be included in your packages.
For the simplest use, you can simply use the ``include_package_data`` keyword:
+.. tab:: pyproject.toml (**BETA**) [#beta]_
+
+ .. code-block:: toml
+
+ [tool.setuptools]
+ include-package-data = true
+ # This is already the default behaviour if your are using
+ # pyproject.toml to configure your build.
+ # You can deactivate that with `include-package-data = false`
+
.. tab:: setup.cfg
.. code-block:: ini
# ...
)
-.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
-
- .. code-block:: toml
-
- [tool.setuptools]
- include-package-data = true
- # This is already the default behaviour if your are using
- # pyproject.toml to configure your build.
- # You can deactivate that with `include-package-data = false`
-
This tells setuptools to install any data files it finds in your packages.
The data files must be specified via the |MANIFEST.in|_ file
or automatically added by a :ref:`Revision Control System plugin
Development mode
-================
+----------------
``setuptools`` allows you to install a package without copying any files
to your interpreter directory (e.g. the ``site-packages`` directory).
Uploading your package to PyPI
-==============================
+------------------------------
After generating the distribution files, the next step would be to upload your
distribution so others can use it. This functionality is provided by
:pypi:`twine` and is documented in the :doc:`Python packaging tutorial
Transitioning from ``setup.py`` to ``setup.cfg``
-================================================
+------------------------------------------------
To avoid executing arbitrary scripts and boilerplate code, we are transitioning
into a full-fledged ``setup.cfg`` to declare your package information instead
of running ``setup()``. This inevitably brings challenges due to a different
<pyproject_config>` and use ``setup.py`` only for the parts not
supported in those files (e.g. C extensions).
-.. [#experimental]
- While the ``[build-system]`` table should always be specified in the
- ``pyproject.toml`` file, support for adding package metadata and build configuration
- options via the ``[project]`` and ``[tool.setuptools]`` tables is still
- experimental and might change in future releases.
+.. [#beta]
+ Support for adding build configuration options via the ``[tool.setuptools]``
+ table in the ``pyproject.toml`` file is still in **beta** stage.
See :doc:`/userguide/pyproject_config`.
+
+.. _PyPI: https://pypi.org
ignore:Distutils was imported before setuptools
ignore:Setuptools is replacing distutils
- ignore:Support for project metadata in .pyproject.toml. is still experimental
+ ignore:Support for .* in .pyproject.toml. is still .beta.
[metadata]
name = setuptools
-version = 62.4.0
+version = 62.5.0
author = Python Packaging Authority
author_email = distutils-sig@python.org
description = Easily download, build, install, upgrade, and uninstall Python packages
The distribution and metadata objects are modeled after (an old version of)
core metadata, therefore configs in the format specified for ``pyproject.toml``
need to be processed before being applied.
+
+**PRIVATE MODULE**: API reserved for setuptools internal usage only.
"""
import logging
import os
`{field} = {value!r}`
- According to the spec (see the link bellow), however, setuptools CANNOT
+ According to the spec (see the link below), however, setuptools CANNOT
consider this value unless {field!r} is listed as `dynamic`.
https://packaging.python.org/en/latest/specifications/declaring-project-metadata/
This module focus on the second step, and therefore allow sharing the expansion
functions among several configuration file formats.
+
+**PRIVATE MODULE**: API reserved for setuptools internal usage only.
"""
import ast
import importlib
-"""Load setuptools configuration from ``pyproject.toml`` files"""
+"""
+Load setuptools configuration from ``pyproject.toml`` files.
+
+**PRIVATE MODULE**: API reserved for setuptools internal usage only.
+"""
import logging
import os
import warnings
if not asdict or not (project_table or setuptools_table):
return {} # User is not using pyproject to configure setuptools
- # TODO: Remove the following once the feature stabilizes:
- msg = (
- "Support for project metadata in `pyproject.toml` is still experimental "
- "and may be removed (or change) in future releases."
- )
- warnings.warn(msg, _ExperimentalProjectMetadata)
+ if setuptools_table:
+ # TODO: Remove the following once the feature stabilizes:
+ msg = "Support for `[tool.setuptools]` in `pyproject.toml` is still *beta*."
+ warnings.warn(msg, _BetaConfiguration)
# There is an overall sense in the community that making include_package_data=True
# the default would be an improvement.
return super().__exit__(exc_type, exc_value, traceback)
-class _ExperimentalProjectMetadata(UserWarning):
- """Explicitly inform users that `pyproject.toml` configuration is experimental"""
+class _BetaConfiguration(UserWarning):
+ """Explicitly inform users that some `pyproject.toml` configuration is *beta*"""
class _InvalidFile(UserWarning):
-"""Load setuptools configuration from ``setup.cfg`` files"""
+"""
+Load setuptools configuration from ``setup.cfg`` files.
+
+**API will be made private in the future**
+"""
import os
import warnings
class Extension(_Extension):
- """Extension that uses '.c' files in place of '.pyx' files"""
+ """
+ Describes a single extension module.
+
+ This means that all source files will be compiled into a single binary file
+ ``<module path>.<suffix>`` (with ``<module path>`` derived from ``name`` and
+ ``<suffix>`` defined by one of the values in
+ ``importlib.machinery.EXTENSION_SUFFIXES``).
+
+ In the case ``.pyx`` files are passed as ``sources and`` ``Cython`` is **not**
+ installed in the build environment, ``setuptools`` may also try to look for the
+ equivalent ``.cpp`` or ``.c`` files.
+
+ :arg str name:
+ the full name of the extension, including any packages -- ie.
+ *not* a filename or pathname, but Python dotted name
+
+ :arg list[str] sources:
+ list of source filenames, relative to the distribution root
+ (where the setup script lives), in Unix form (slash-separated)
+ for portability. Source files may be C, C++, SWIG (.i),
+ platform-specific resource files, or whatever else is recognized
+ by the "build_ext" command as source for a Python extension.
+
+ :keyword list[str] include_dirs:
+ list of directories to search for C/C++ header files (in Unix
+ form for portability)
+
+ :keyword list[tuple[str, str|None]] define_macros:
+ list of macros to define; each macro is defined using a 2-tuple:
+ the first item corresponding to the name of the macro and the second
+ item either a string with its value or None to
+ define it without a particular value (equivalent of "#define
+ FOO" in source or -DFOO on Unix C compiler command line)
+
+ :keyword list[str] undef_macros:
+ list of macros to undefine explicitly
+
+ :keyword list[str] library_dirs:
+ list of directories to search for C/C++ libraries at link time
+
+ :keyword list[str] libraries:
+ list of library names (not filenames or paths) to link against
+
+ :keyword list[str] runtime_library_dirs:
+ list of directories to search for C/C++ libraries at run time
+ (for shared extensions, this is when the extension is loaded)
+
+ :keyword list[str] extra_objects:
+ list of extra files to link with (eg. object files not implied
+ by 'sources', static library that must be explicitly specified,
+ binary resource files, etc.)
+
+ :keyword list[str] extra_compile_args:
+ any extra platform- and compiler-specific information to use
+ when compiling the source files in 'sources'. For platforms and
+ compilers where "command line" makes sense, this is typically a
+ list of command-line arguments, but for other platforms it could
+ be anything.
+
+ :keyword list[str] extra_link_args:
+ any extra platform- and compiler-specific information to use
+ when linking object files together to create the extension (or
+ to create a new static Python interpreter). Similar
+ interpretation as for 'extra_compile_args'.
+
+ :keyword list[str] export_symbols:
+ list of symbols to be exported from a shared extension. Not
+ used on all platforms, and not generally necessary for Python
+ extensions, which typically export exactly one symbol: "init" +
+ extension_name.
+
+ :keyword list[str] swig_opts:
+ any extra options to pass to SWIG if a source file has the .i
+ extension.
+
+ :keyword list[str] depends:
+ list of files that the extension depends on
+
+ :keyword str language:
+ extension language (i.e. "c", "c++", "objc"). Will be detected
+ from the source extensions if not provided.
+
+ :keyword bool optional:
+ specifies that a build failure in the extension should not abort the
+ build process, but simply not install the failing extension.
+ """
def __init__(self, name, sources, *args, **kw):
# The *args is needed for compatibility as calls may use positional
"""
Configure logging to emit warning and above to stderr
and everything else to stdout. This behavior is provided
- for compatibilty with distutils.log but may change in
+ for compatibility with distutils.log but may change in
the future.
"""
err_handler = logging.StreamHandler()
# == Arrange ==
# Pretend that build isolation was enabled
- # e.g pip sets the environment varible PYTHONNOUSERSITE=1
+ # e.g pip sets the environment variable PYTHONNOUSERSITE=1
monkeypatch.setattr('site.ENABLE_USER_SITE', False)
# Patching $HOME for 2 reasons:
projects / platform / upstream / python-setuptools.git / commitdiff