diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/_templates/indexsidebar.html | 14 | ||||
| -rw-r--r-- | docs/build_meta.txt | 89 | ||||
| -rw-r--r-- | docs/conf.py | 49 | ||||
| -rw-r--r-- | docs/developer-guide.txt | 10 | ||||
| -rw-r--r-- | docs/development.txt | 2 | ||||
| -rw-r--r-- | docs/easy_install.txt | 6 | ||||
| -rw-r--r-- | docs/ez_setup.txt | 195 | ||||
| -rw-r--r-- | docs/formats.txt | 7 | ||||
| -rw-r--r-- | docs/history.txt | 2 | ||||
| -rw-r--r-- | docs/keywords.txt | 336 | ||||
| -rw-r--r-- | docs/pkg_resources.txt | 20 | ||||
| -rw-r--r-- | docs/releases.txt | 40 | ||||
| -rw-r--r-- | docs/requirements.txt | 6 | ||||
| -rw-r--r-- | docs/setuptools.txt | 622 |
14 files changed, 700 insertions, 698 deletions
diff --git a/docs/_templates/indexsidebar.html b/docs/_templates/indexsidebar.html index 504de6b0..d803b8a3 100644 --- a/docs/_templates/indexsidebar.html +++ b/docs/_templates/indexsidebar.html @@ -1,3 +1,10 @@ +<h3 class="donation">For Enterprise</h3> + +<p> +Professionally-supported {{ project }} is available with the +<a href="https://tidelift.com/subscription/pkg/pypi-{{ project }}?utm_source=pypi-{{ project }}&utm_medium=referral">Tidelift Subscription</a>. +</p> + <h3>Download</h3> <p>Current version: <b>{{ version }}</b></p> @@ -6,10 +13,3 @@ <h3>Questions? Suggestions? Contributions?</h3> <p>Visit the <a href="{{ package_url }}">Project page</a> </p> - -<h3 class="donation">Professional support</h3> - -<p> -Professionally-supported {{ project }} is available with the -<a href="https://tidelift.com/subscription/pkg/pypi-{{ project }}?utm_source=pypi-{{ project }}&utm_medium=readme">Tidelift Subscription</a>. -</p> diff --git a/docs/build_meta.txt b/docs/build_meta.txt new file mode 100644 index 00000000..ef9fb2ac --- /dev/null +++ b/docs/build_meta.txt @@ -0,0 +1,89 @@ +======================================= +Build System Support +======================================= + +What is it? +------------- + +Python packaging has come `a long way <https://www.bernat.tech/pep-517-518/>`_. + +The traditional ``setuptools`` way of packgaging Python modules +uses a ``setup()`` function within the ``setup.py`` script. Commands such as +``python setup.py bdist`` or ``python setup.py bdist_wheel`` generate a +distribution bundle and ``python setup.py install`` installs the distribution. +This interface makes it difficult to choose other packaging tools without an +overhaul. Because ``setup.py`` scripts allowed for arbitrary execution, it +proved difficult to provide a reliable user experience across environments +and history. + +`PEP 517 <https://www.python.org/dev/peps/pep-0517/>`_ therefore came to +rescue and specified a new standard to +package and distribute Python modules. Under PEP 517: + + a ``pyproject.toml`` file is used to specify what program to use + for generating distribution. + + Then, two functions provided by the program, ``build_wheel(directory: str)`` + and ``build_sdist(directory: str)`` create the distribution bundle at the + specified ``directory``. The program is free to use its own configuration + script or extend the ``.toml`` file. + + Lastly, ``pip install *.whl`` or ``pip install *.tar.gz`` does the actual + installation. If ``*.whl`` is available, ``pip`` will go ahead and copy + the files into ``site-packages`` directory. If not, ``pip`` will look at + ``pyproject.toml`` and decide what program to use to 'build from source' + (the default is ``setuptools``) + +With this standard, switching between packaging tools becomes a lot easier. ``build_meta`` +implements ``setuptools``' build system support. + +How to use it? +-------------- + +Starting with a package that you want to distribute. You will need your source +scripts, a ``pyproject.toml`` file and a ``setup.cfg`` file:: + + ~/meowpkg/ + pyproject.toml + setup.cfg + meowpkg/__init__.py + +The pyproject.toml file is required to specify the build system (i.e. what is +being used to package your scripts and install from source). To use it with +setuptools, the content would be:: + + [build-system] + requires = ["setuptools", "wheel"] + build-backend = "setuptools.build_meta" + +Use ``setuptools``' `declarative config`_ to specify the package information:: + + [metadata] + name = meowpkg + version = 0.0.1 + description = a package that meows + + [options] + packages = find: + +Now generate the distribution. Although the PyPA is still working to +`provide a recommended tool <https://github.com/pypa/packaging-problems/issues/219>`_ +to build packages, the `pep517 package <https://pypi.org/project/pep517`_ +provides this functionality. To build the package:: + + $ pip install -q pep517 + $ mkdir dist + $ python -m pep517.build . + +And now it's done! The ``.whl`` file and ``.tar.gz`` can then be distributed +and installed:: + + dist/ + meowpkg-0.0.1.whl + meowpkg-0.0.1.tar.gz + + $ pip install dist/meowpkg-0.0.1.whl + +or:: + + $ pip install dist/meowpkg-0.0.1.tar.gz diff --git a/docs/conf.py b/docs/conf.py index c7eb6d3f..b92b50cc 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,23 +1,3 @@ -# -*- coding: utf-8 -*- -# -# Setuptools documentation build configuration file, created by -# sphinx-quickstart on Fri Jul 17 14:22:37 2009. -# -# This file is execfile()d with the current directory set to its containing dir. -# -# The contents of this file are pickled, so don't put values in the namespace -# that aren't pickleable (module imports are okay, they're removed automatically). -# -# Note that not all possible configuration values are present in this -# autogenerated file. -# -# All configuration values have a default; values that are commented out -# serve to show the default - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. - import subprocess import sys import os @@ -26,14 +6,12 @@ import os # hack to run the bootstrap script so that jaraco.packaging.sphinx # can invoke setup.py 'READTHEDOCS' in os.environ and subprocess.check_call( - [sys.executable, 'bootstrap.py'], + [sys.executable, '-m', 'bootstrap'], cwd=os.path.join(os.path.dirname(__file__), os.path.pardir), ) -# -- General configuration ----------------------------------------------------- +# -- General configuration -- -# Add any Sphinx extension module names here, as strings. They can be extensions -# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. extensions = ['jaraco.packaging.sphinx', 'rst.linker'] # Add any paths that contain templates here, relative to this directory. @@ -45,7 +23,8 @@ source_suffix = '.txt' # The master toctree document. master_doc = 'index' -# A list of glob-style patterns that should be excluded when looking for source files. +# A list of glob-style patterns that should be excluded +# when looking for source files. exclude_patterns = ['requirements.txt'] # List of directories, relative to source directory, that shouldn't be searched @@ -55,7 +34,7 @@ exclude_trees = [] # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' -# -- Options for HTML output --------------------------------------------------- +# -- Options for HTML output -- # The theme to use for HTML and HTML Help pages. Major themes that come with # Sphinx are currently 'default' and 'sphinxdoc'. @@ -69,7 +48,10 @@ html_theme_path = ['_theme'] html_use_smartypants = True # Custom sidebar templates, maps document names to template names. -html_sidebars = {'index': 'indexsidebar.html'} +html_sidebars = { + 'index': [ + 'relations.html', 'sourcelink.html', 'indexsidebar.html', + 'searchbox.html']} # If false, no module index is generated. html_use_modindex = False @@ -77,14 +59,15 @@ html_use_modindex = False # If false, no index is generated. html_use_index = False -# -- Options for LaTeX output -------------------------------------------------- +# -- Options for LaTeX output -- # Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, author, documentclass [howto/manual]). -latex_documents = [ - ('index', 'Setuptools.tex', 'Setuptools Documentation', - 'The fellowship of the packaging', 'manual'), -] +# (source start file, target name, title, author, +# documentclass [howto/manual]). +latex_documents = [( + 'index', 'Setuptools.tex', 'Setuptools Documentation', + 'The fellowship of the packaging', 'manual', +)] link_files = { '../CHANGES.rst': dict( diff --git a/docs/developer-guide.txt b/docs/developer-guide.txt index d145fba1..e6171e4e 100644 --- a/docs/developer-guide.txt +++ b/docs/developer-guide.txt @@ -104,12 +104,8 @@ from the command line after pushing a new branch. Testing ------- -The primary tests are run using tox. To run the tests, first create the metadata -needed to run the tests:: - - $ python bootstrap.py - -Then make sure you have tox installed, and invoke it:: +The primary tests are run using tox. Make sure you have tox installed, +and invoke it:: $ tox @@ -143,7 +139,7 @@ Vendored Dependencies --------------------- Setuptools has some dependencies, but due to `bootstrapping issues -<https://github.com/pypa/setuptools/issues/980>`, those dependencies +<https://github.com/pypa/setuptools/issues/980>`_, those dependencies cannot be declared as they won't be resolved soon enough to build setuptools from source. Eventually, this limitation may be lifted as PEP 517/518 reach ubiquitous adoption, but for now, Setuptools diff --git a/docs/development.txt b/docs/development.txt index 455f038a..28e653fe 100644 --- a/docs/development.txt +++ b/docs/development.txt @@ -7,7 +7,7 @@ Authority (PyPA) and led by Jason R. Coombs. This document describes the process by which Setuptools is developed. This document assumes the reader has some passing familiarity with -*using* setuptools, the ``pkg_resources`` module, and EasyInstall. It +*using* setuptools, the ``pkg_resources`` module, and pip. It does not attempt to explain basic concepts like inter-project dependencies, nor does it contain detailed lexical syntax for most file formats. Neither does it explain concepts like "namespace diff --git a/docs/easy_install.txt b/docs/easy_install.txt index aa11f890..fac7b8fc 100644 --- a/docs/easy_install.txt +++ b/docs/easy_install.txt @@ -41,7 +41,7 @@ Please see the `setuptools PyPI page <https://pypi.org/project/setuptools/>`_ for download links and basic installation instructions for each of the supported platforms. -You will need at least Python 3.4 or 2.7. An ``easy_install`` script will be +You will need at least Python 3.5 or 2.7. An ``easy_install`` script will be installed in the normal location for Python scripts on your platform. Note that the instructions on the setuptools PyPI page assume that you are @@ -317,8 +317,8 @@ Note that instead of changing your ``PATH`` to include the Python scripts directory, you can also retarget the installation location for scripts so they go on a directory that's already on the ``PATH``. For more information see `Command-Line Options`_ and `Configuration Files`_. During installation, -pass command line options (such as ``--script-dir``) to -``ez_setup.py`` to control where ``easy_install.exe`` will be installed. +pass command line options (such as ``--script-dir``) to control where +scripts will be installed. Windows Executable Launcher diff --git a/docs/ez_setup.txt b/docs/ez_setup.txt deleted file mode 100644 index 0126fee3..00000000 --- a/docs/ez_setup.txt +++ /dev/null @@ -1,195 +0,0 @@ -:orphan: - -``ez_setup`` distribution guide -=============================== - -Using ``setuptools``... Without bundling it! ---------------------------------------------- - -.. warning:: **ez_setup** is deprecated in favor of PIP with **PEP-518** support. - -.. _ez_setup.py: https://bootstrap.pypa.io/ez_setup.py - -.. _EasyInstall Installation Instructions: easy_install.html - -.. _Custom Installation Locations: easy_install.html - -Your users might not have ``setuptools`` installed on their machines, or even -if they do, it might not be the right version. Fixing this is easy; just -download `ez_setup.py`_, and put it in the same directory as your ``setup.py`` -script. (Be sure to add it to your revision control system, too.) Then add -these two lines to the very top of your setup script, before the script imports -anything from setuptools: - -.. code-block:: python - - import ez_setup - ez_setup.use_setuptools() - -That's it. The ``ez_setup`` module will automatically download a matching -version of ``setuptools`` from PyPI, if it isn't present on the target system. -Whenever you install an updated version of setuptools, you should also update -your projects' ``ez_setup.py`` files, so that a matching version gets installed -on the target machine(s). - -(By the way, if you need to distribute a specific version of ``setuptools``, -you can specify the exact version and base download URL as parameters to the -``use_setuptools()`` function. See the function's docstring for details.) - - -What Your Users Should Know ---------------------------- - -In general, a setuptools-based project looks just like any distutils-based -project -- as long as your users have an internet connection and are installing -to ``site-packages``, that is. But for some users, these conditions don't -apply, and they may become frustrated if this is their first encounter with -a setuptools-based project. To keep these users happy, you should review the -following topics in your project's installation instructions, if they are -relevant to your project and your target audience isn't already familiar with -setuptools and ``easy_install``. - -Network Access - If your project is using ``ez_setup``, you should inform users of the - need to either have network access, or to preinstall the correct version of - setuptools using the `EasyInstall installation instructions`_. Those - instructions also have tips for dealing with firewalls as well as how to - manually download and install setuptools. - -Custom Installation Locations - You should inform your users that if they are installing your project to - somewhere other than the main ``site-packages`` directory, they should - first install setuptools using the instructions for `Custom Installation - Locations`_, before installing your project. - -Your Project's Dependencies - If your project depends on other projects that may need to be downloaded - from PyPI or elsewhere, you should list them in your installation - instructions, or tell users how to find out what they are. While most - users will not need this information, any users who don't have unrestricted - internet access may have to find, download, and install the other projects - manually. (Note, however, that they must still install those projects - using ``easy_install``, or your project will not know they are installed, - and your setup script will try to download them again.) - - If you want to be especially friendly to users with limited network access, - you may wish to build eggs for your project and its dependencies, making - them all available for download from your site, or at least create a page - with links to all of the needed eggs. In this way, users with limited - network access can manually download all the eggs to a single directory, - then use the ``-f`` option of ``easy_install`` to specify the directory - to find eggs in. Users who have full network access can just use ``-f`` - with the URL of your download page, and ``easy_install`` will find all the - needed eggs using your links directly. This is also useful when your - target audience isn't able to compile packages (e.g. most Windows users) - and your package or some of its dependencies include C code. - -Revision Control System Users and Co-Developers - Users and co-developers who are tracking your in-development code using - a revision control system should probably read this manual's sections - regarding such development. Alternately, you may wish to create a - quick-reference guide containing the tips from this manual that apply to - your particular situation. For example, if you recommend that people use - ``setup.py develop`` when tracking your in-development code, you should let - them know that this needs to be run after every update or commit. - - Similarly, if you remove modules or data files from your project, you - should remind them to run ``setup.py clean --all`` and delete any obsolete - ``.pyc`` or ``.pyo``. (This tip applies to the distutils in general, not - just setuptools, but not everybody knows about them; be kind to your users - by spelling out your project's best practices rather than leaving them - guessing.) - -Creating System Packages - Some users want to manage all Python packages using a single package - manager, and sometimes that package manager isn't ``easy_install``! - Setuptools currently supports ``bdist_rpm``, ``bdist_wininst``, and - ``bdist_dumb`` formats for system packaging. If a user has a locally- - installed "bdist" packaging tool that internally uses the distutils - ``install`` command, it should be able to work with ``setuptools``. Some - examples of "bdist" formats that this should work with include the - ``bdist_nsi`` and ``bdist_msi`` formats for Windows. - - However, packaging tools that build binary distributions by running - ``setup.py install`` on the command line or as a subprocess will require - modification to work with setuptools. They should use the - ``--single-version-externally-managed`` option to the ``install`` command, - combined with the standard ``--root`` or ``--record`` options. - See the `install command`_ documentation below for more details. The - ``bdist_deb`` command is an example of a command that currently requires - this kind of patching to work with setuptools. - - Please note that building system packages may require you to install - some system software, for example ``bdist_rpm`` requires the ``rpmbuild`` - command to be installed. - - If you or your users have a problem building a usable system package for - your project, please report the problem via the mailing list so that - either the "bdist" tool in question or setuptools can be modified to - resolve the issue. - -Your users might not have ``setuptools`` installed on their machines, or even -if they do, it might not be the right version. Fixing this is easy; just -download `ez_setup.py`_, and put it in the same directory as your ``setup.py`` -script. (Be sure to add it to your revision control system, too.) Then add -these two lines to the very top of your setup script, before the script imports -anything from setuptools: - -.. code-block:: python - - import ez_setup - ez_setup.use_setuptools() - -That's it. The ``ez_setup`` module will automatically download a matching -version of ``setuptools`` from PyPI, if it isn't present on the target system. -Whenever you install an updated version of setuptools, you should also update -your projects' ``ez_setup.py`` files, so that a matching version gets installed -on the target machine(s). - -(By the way, if you need to distribute a specific version of ``setuptools``, -you can specify the exact version and base download URL as parameters to the -``use_setuptools()`` function. See the function's docstring for details.) - -.. _install command: - -``install`` - Run ``easy_install`` or old-style installation -============================================================ - -The setuptools ``install`` command is basically a shortcut to run the -``easy_install`` command on the current project. However, for convenience -in creating "system packages" of setuptools-based projects, you can also -use this option: - -``--single-version-externally-managed`` - This boolean option tells the ``install`` command to perform an "old style" - installation, with the addition of an ``.egg-info`` directory so that the - installed project will still have its metadata available and operate - normally. If you use this option, you *must* also specify the ``--root`` - or ``--record`` options (or both), because otherwise you will have no way - to identify and remove the installed files. - -This option is automatically in effect when ``install`` is invoked by another -distutils command, so that commands like ``bdist_wininst`` and ``bdist_rpm`` -will create system packages of eggs. It is also automatically in effect if -you specify the ``--root`` option. - - -``install_egg_info`` - Install an ``.egg-info`` directory in ``site-packages`` -============================================================================== - -Setuptools runs this command as part of ``install`` operations that use the -``--single-version-externally-managed`` options. You should not invoke it -directly; it is documented here for completeness and so that distutils -extensions such as system package builders can make use of it. This command -has only one option: - -``--install-dir=DIR, -d DIR`` - The parent directory where the ``.egg-info`` directory will be placed. - Defaults to the same as the ``--install-dir`` option specified for the - ``install_lib`` command, which is usually the system ``site-packages`` - directory. - -This command assumes that the ``egg_info`` command has been given valid options -via the command line or ``setup.cfg``, as it will invoke the ``egg_info`` -command and use its options to locate the project's source ``.egg-info`` -directory. diff --git a/docs/formats.txt b/docs/formats.txt index a182eb99..6c0456de 100644 --- a/docs/formats.txt +++ b/docs/formats.txt @@ -299,11 +299,8 @@ specified by the ``setup_requires`` parameter to the Distribution. A list of dependency URLs, one per line, as specified using the ``dependency_links`` keyword to ``setup()``. These may be direct download URLs, or the URLs of web pages containing direct download -links, and will be used by EasyInstall to find dependencies, as though -the user had manually provided them via the ``--find-links`` command -line option. Please see the setuptools manual and EasyInstall manual -for more information on specifying this option, and for information on -how EasyInstall processes ``--find-links`` URLs. +links. Please see the setuptools manual for more information on +specifying this option. ``depends.txt`` -- Obsolete, do not create! diff --git a/docs/history.txt b/docs/history.txt index 385cfa7e..faf7adfe 100644 --- a/docs/history.txt +++ b/docs/history.txt @@ -12,7 +12,7 @@ Credits * The original design for the ``.egg`` format and the ``pkg_resources`` API was co-created by Phillip Eby and Bob Ippolito. Bob also implemented the first - version of ``pkg_resources``, and supplied the OS X operating system version + version of ``pkg_resources``, and supplied the macOS operating system version compatibility algorithm. * Ian Bicking implemented many early "creature comfort" features of diff --git a/docs/keywords.txt b/docs/keywords.txt new file mode 100644 index 00000000..56356190 --- /dev/null +++ b/docs/keywords.txt @@ -0,0 +1,336 @@ +``name`` + A string specifying the name of the package. + +``version`` + A string specifying the version number of the package. + +``description`` + A string describing the package in a single line. + +``long_description`` + A string providing a longer description of the package. + +``long_description_content_type`` + A string specifying the content type is used for the ``long_description`` + (e.g. ``text/markdown``) + +``author`` + A string specifying the author of the package. + +``author_email`` + A string specifying the email address of the package author. + +``maintainer`` + A string specifying the name of the current maintainer, if different from + the author. Note that if the maintainer is provided, setuptools will use it + as the author in ``PKG-INFO``. + +``maintainer_email`` + A string specifying the email address of the current maintainer, if + different from the author. + +``url`` + A string specifying the URL for the package homepage. + +``download_url`` + A string specifying the URL to download the package. + +``packages`` + A list of strings specifying the packages that setuptools will manipulate. + +``py_modules`` + A list of strings specifying the modules that setuptools will manipulate. + +``scripts`` + A list of strings specifying the standalone script files to be built and + installed. + +``ext_package`` + A string specifying the base package name for the extensions provided by + this package. + +``ext_modules`` + A list of instances of ``setuptools.Extension`` providing the list of + Python extensions to be built. + +``classifiers`` + A list of strings describing the categories for the package. + +``distclass`` + A subclass of ``Distribution`` to use. + +``script_name`` + A string specifying the name of the setup.py script -- defaults to + ``sys.argv[0]`` + +``script_args`` + A list of strings defining the arguments to supply to the setup script. + +``options`` + A dictionary providing the default options for the setup script. + +``license`` + A string specifying the license of the package. + +``keywords`` + A list of strings or a comma-separated string providing descriptive + meta-data. See: `PEP 0314`_. + +.. _PEP 0314: https://www.python.org/dev/peps/pep-0314/ + +``platforms`` + A list of strings or comma-separated string. + +``cmdclass`` + A dictionary providing a mapping of command names to ``Command`` + subclasses. + +``data_files`` + + .. warning:: + ``data_files`` is deprecated. It does not work with wheels, so it + should be avoided. + + A list of strings specifying the data files to install. + +``package_dir`` + A dictionary providing a mapping of package to directory names. + +``requires`` + + .. warning:: + ``requires`` is superseded by ``install_requires`` and should not be used + anymore. + +``obsoletes`` + + .. warning:: + ``obsoletes`` is currently ignored by ``pip``. + + List of strings describing packages which this package renders obsolete, + meaning that the two projects should not be installed at the same time. + + Version declarations can be supplied. Version numbers must be in the format + specified in Version specifiers (e.g. ``foo (<3.0)``). + + This field may be followed by an environment marker after a semicolon (e.g. + ``foo; os_name == "posix"``) + + The most common use of this field will be in case a project name changes, + e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install + Torqued Python, the Gorgon distribution should be removed. + +``provides`` + + .. warning:: + ``provides`` is currently ignored by ``pip``. + + List of strings describing package- and virtual package names contained + within this package. + + A package may provide additional names, e.g. to indicate that multiple + projects have been bundled together. For instance, source distributions of + the ZODB project have historically included the transaction project, which + is now available as a separate distribution. Installing such a source + distribution satisfies requirements for both ZODB and transaction. + + A package may also provide a “virtual” project name, which does not + correspond to any separately-distributed project: such a name might be used + to indicate an abstract capability which could be supplied by one of + multiple projects. E.g., multiple projects might supply RDBMS bindings for + use by a given ORM: each project might declare that it provides + ORM-bindings, allowing other projects to depend only on having at most one + of them installed. + + A version declaration may be supplied and must follow the rules described in + Version specifiers. The distribution’s version number will be implied if + none is specified (e.g. ``foo (<3.0)``). + + Each package may be followed by an environment marker after a semicolon + (e.g. ``foo; os_name == "posix"``). + +.. Below are setuptools keywords, above are distutils + +``include_package_data`` + If set to ``True``, this tells ``setuptools`` to automatically include any + data files it finds inside your package directories that are specified by + your ``MANIFEST.in`` file. For more information, see the section on + :ref:`Including Data Files`. + +``exclude_package_data`` + A dictionary mapping package names to lists of glob patterns that should + be *excluded* from your package directories. You can use this to trim back + any excess files included by ``include_package_data``. For a complete + description and examples, see the section on :ref:`Including Data Files`. + +``package_data`` + A dictionary mapping package names to lists of glob patterns. For a + complete description and examples, see the section on :ref:`Including Data + Files`. You do not need to use this option if you are using + ``include_package_data``, unless you need to add e.g. files that are + generated by your setup script and build process. (And are therefore not + in source control or are files that you don't want to include in your + source distribution.) + +``zip_safe`` + A boolean (True or False) flag specifying whether the project can be + safely installed and run from a zip file. If this argument is not + supplied, the ``bdist_egg`` command will have to analyze all of your + project's contents for possible problems each time it builds an egg. + +``install_requires`` + A string or list of strings specifying what other distributions need to + be installed when this one is. See the section on :ref:`Declaring + Dependencies` for details and examples of the format of this argument. + +``entry_points`` + A dictionary mapping entry point group names to strings or lists of strings + defining the entry points. Entry points are used to support dynamic + discovery of services or plugins provided by a project. See :ref:`Dynamic + Discovery of Services and Plugins` for details and examples of the format + of this argument. In addition, this keyword is used to support + :ref:`Automatic Script Creation`. + +``extras_require`` + A dictionary mapping names of "extras" (optional features of your project) + to strings or lists of strings specifying what other distributions must be + installed to support those features. See the section on :ref:`Declaring + Dependencies` for details and examples of the format of this argument. + +``python_requires`` + A string corresponding to a version specifier (as defined in PEP 440) for + the Python version, used to specify the Requires-Python defined in PEP 345. + +``setup_requires`` + + .. warning:: + Using ``setup_requires`` is discouraged in favor of `PEP-518`_ + + A string or list of strings specifying what other distributions need to + be present in order for the *setup script* to run. ``setuptools`` will + attempt to obtain these (even going so far as to download them using + ``EasyInstall``) before processing the rest of the setup script or commands. + This argument is needed if you are using distutils extensions as part of + your build process; for example, extensions that process setup() arguments + and turn them into EGG-INFO metadata files. + + (Note: projects listed in ``setup_requires`` will NOT be automatically + installed on the system where the setup script is being run. They are + simply downloaded to the ./.eggs directory if they're not locally available + already. If you want them to be installed, as well as being available + when the setup script is run, you should add them to ``install_requires`` + **and** ``setup_requires``.) + +.. _PEP-518: http://www.python.org/dev/peps/pep-0518/ + +``dependency_links`` + + .. warning:: + ``dependency_links`` is deprecated. It is not supported anymore by pip. + + A list of strings naming URLs to be searched when satisfying dependencies. + These links will be used if needed to install packages specified by + ``setup_requires`` or ``tests_require``. They will also be written into + the egg's metadata for use by tools like EasyInstall to use when installing + an ``.egg`` file. + +``namespace_packages`` + A list of strings naming the project's "namespace packages". A namespace + package is a package that may be split across multiple project + distributions. For example, Zope 3's ``zope`` package is a namespace + package, because subpackages like ``zope.interface`` and ``zope.publisher`` + may be distributed separately. The egg runtime system can automatically + merge such subpackages into a single parent package at runtime, as long + as you declare them in each project that contains any subpackages of the + namespace package, and as long as the namespace package's ``__init__.py`` + does not contain any code other than a namespace declaration. See the + section on :ref:`Namespace Packages` for more information. + +``test_suite`` + A string naming a ``unittest.TestCase`` subclass (or a package or module + containing one or more of them, or a method of such a subclass), or naming + a function that can be called with no arguments and returns a + ``unittest.TestSuite``. If the named suite is a module, and the module + has an ``additional_tests()`` function, it is called and the results are + 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. + + Specifying this argument enables use of the :ref:`test` command to run the + specified test suite, e.g. via ``setup.py test``. See the section on the + :ref:`test` command below for more details. + + New in 41.5.0: Deprecated the test command. + +``tests_require`` + If your project's tests need one or more additional packages besides those + needed to install it, you can use this option to specify them. It should + be a string or list of strings specifying what other distributions need to + be present for the package's tests to run. When you run the ``test`` + command, ``setuptools`` will attempt to obtain these (even going + so far as to download them using ``EasyInstall``). Note that these + required projects will *not* be installed on the system where the tests + are run, but only downloaded to the project's setup directory if they're + not already installed locally. + + New in 41.5.0: Deprecated the test command. + +.. _test_loader: + +``test_loader`` + If you would like to use a different way of finding tests to run than what + setuptools normally uses, you can specify a module name and class name in + this argument. The named class must be instantiable with no arguments, and + its instances must support the ``loadTestsFromNames()`` method as defined + in the Python ``unittest`` module's ``TestLoader`` class. Setuptools will + pass only one test "name" in the `names` argument: the value supplied for + the ``test_suite`` argument. The loader you specify may interpret this + string in any way it likes, as there are no restrictions on what may be + contained in a ``test_suite`` string. + + The module name and class name must be separated by a ``:``. The default + value of this argument is ``"setuptools.command.test:ScanningLoader"``. If + you want to use the default ``unittest`` behavior, you can specify + ``"unittest:TestLoader"`` as your ``test_loader`` argument instead. This + will prevent automatic scanning of submodules and subpackages. + + The module and class you specify here may be contained in another package, + as long as you use the ``tests_require`` option to ensure that the package + containing the loader class is available when the ``test`` command is run. + + New in 41.5.0: Deprecated the test command. + +``eager_resources`` + A list of strings naming resources that should be extracted together, if + any of them is needed, or if any C extensions included in the project are + imported. This argument is only useful if the project will be installed as + a zipfile, and there is a need to have all of the listed resources be + extracted to the filesystem *as a unit*. Resources listed here + should be '/'-separated paths, relative to the source root, so to list a + resource ``foo.png`` in package ``bar.baz``, you would include the string + ``bar/baz/foo.png`` in this argument. + + If you only need to obtain resources one at a time, or you don't have any C + extensions that access other files in the project (such as data files or + shared libraries), you probably do NOT need this argument and shouldn't + mess with it. For more details on how this argument works, see the section + below on :ref:`Automatic Resource Extraction`. + +``use_2to3`` + Convert the source code from Python 2 to Python 3 with 2to3 during the + build process. See :doc:`python3` for more details. + +``convert_2to3_doctests`` + List of doctest source files that need to be converted with 2to3. + See :doc:`python3` for more details. + +``use_2to3_fixers`` + A list of modules to search for additional fixers to be used during + the 2to3 conversion. See :doc:`python3` for more details. + +``use_2to3_exclude_fixers`` + List of fixer names to be skipped. + +``project_urls`` + An arbitrary map of URL names to hyperlinks, allowing more extensible + documentation of where various resources can be found than the simple + ``url`` and ``download_url`` options provide. diff --git a/docs/pkg_resources.txt b/docs/pkg_resources.txt index 806f1b14..71568c1a 100644 --- a/docs/pkg_resources.txt +++ b/docs/pkg_resources.txt @@ -245,8 +245,8 @@ abbreviation for ``pkg_resources.working_set.require()``: interactive interpreter hacking than for production use. If you're creating an actual library or application, it's strongly recommended that you create a "setup.py" script using ``setuptools``, and declare all your requirements - there. That way, tools like EasyInstall can automatically detect what - requirements your package has, and deal with them accordingly. + there. That way, tools like pip can automatically detect what requirements + your package has, and deal with them accordingly. Note that calling ``require('SomePackage')`` will not install ``SomePackage`` if it isn't already present. If you need to do this, you @@ -611,9 +611,9 @@ Requirements Parsing or activation of both Report-O-Rama and any libraries it needs in order to provide PDF support. For example, you could use:: - easy_install.py Report-O-Rama[PDF] + pip install Report-O-Rama[PDF] - To install the necessary packages using the EasyInstall program, or call + To install the necessary packages using pip, or call ``pkg_resources.require('Report-O-Rama[PDF]')`` to add the necessary distributions to sys.path at runtime. @@ -1621,7 +1621,7 @@ Platform Utilities ``get_build_platform()`` Return this platform's identifier string. For Windows, the return value - is ``"win32"``, and for Mac OS X it is a string of the form + is ``"win32"``, and for macOS it is a string of the form ``"macosx-10.4-ppc"``. All other platforms return the same uname-based string that the ``distutils.util.get_platform()`` function returns. This string is the minimum platform version required by distributions built @@ -1641,7 +1641,7 @@ Platform Utilities considered a wildcard, and the platforms are therefore compatible. Likewise, if the platform strings are equal, they're also considered compatible, and ``True`` is returned. Currently, the only non-equal - platform strings that are considered compatible are Mac OS X platform + platform strings that are considered compatible are macOS platform strings with the same hardware type (e.g. ``ppc``) and major version (e.g. ``10``) with the `provided` platform's minor version being less than or equal to the `required` platform's minor version. @@ -1674,7 +1674,7 @@ File/Path Utilities the same filesystem location if they have equal ``normalized_path()`` values. Specifically, this is a shortcut for calling ``os.path.realpath`` and ``os.path.normcase`` on `path`. Unfortunately, on certain platforms - (notably Cygwin and Mac OS X) the ``normcase`` function does not accurately + (notably Cygwin and macOS) the ``normcase`` function does not accurately reflect the platform's case-sensitivity, so there is always the possibility of two apparently-different paths being equal on such platforms. @@ -1843,9 +1843,9 @@ History because it isn't necessarily a filesystem path (and hasn't been for some time now). The ``location`` of ``Distribution`` objects in the filesystem should always be normalized using ``pkg_resources.normalize_path()``; all - of the setuptools and EasyInstall code that generates distributions from - the filesystem (including ``Distribution.from_filename()``) ensure this - invariant, but if you use a more generic API like ``Distribution()`` or + of the setuptools' code that generates distributions from the filesystem + (including ``Distribution.from_filename()``) ensure this invariant, but if + you use a more generic API like ``Distribution()`` or ``Distribution.from_location()`` you should take care that you don't create a distribution with an un-normalized filesystem path. diff --git a/docs/releases.txt b/docs/releases.txt index 98ba39e8..35b415c2 100644 --- a/docs/releases.txt +++ b/docs/releases.txt @@ -3,39 +3,13 @@ Release Process =============== In order to allow for rapid, predictable releases, Setuptools uses a -mechanical technique for releases, enacted by Travis following a -successful build of a tagged release per -`PyPI deployment <https://docs.travis-ci.com/user/deployment/pypi>`_. - -Prior to cutting a release, please use `towncrier`_ to update -``CHANGES.rst`` to summarize the changes since the last release. -To update the changelog: - -1. Install towncrier via ``pip install towncrier`` if not already installed. -2. Preview the new ``CHANGES.rst`` entry by running - ``towncrier --draft --version {new.version.number}`` (enter the desired - version number for the next release). If any changes are needed, make - them and generate a new preview until the output is acceptable. Run - ``git add`` for any modified files. -3. Run ``towncrier --version {new.version.number}`` to stage the changelog - updates in git. -4. Verify that there are no remaining ``changelog.d/*.rst`` files. If a - file was named incorrectly, it may be ignored by towncrier. -5. Review the updated ``CHANGES.rst`` file. If any changes are needed, - make the edits and stage them via ``git add CHANGES.rst``. - -Once the changelog edits are staged and ready to commit, cut a release by -installing and running ``bump2version --allow-dirty {part}`` where ``part`` -is major, minor, or patch based on the scope of the changes in the -release. Then, push the commits to the master branch:: - - $ git push origin master - $ git push --tags - -If tests pass, the release will be uploaded to PyPI (from the Python 3.6 -tests). - -.. _towncrier: https://pypi.org/project/towncrier/ +mechanical technique for releases, enacted on tagged commits by +continuous integration. + +To finalize a release, run ``tox -e finalize``, review, then push +the changes. + +If tests pass, the release will be uploaded to PyPI. Release Frequency ----------------- diff --git a/docs/requirements.txt b/docs/requirements.txt index bc27165b..104d68fa 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,5 +1,7 @@ -sphinx!=1.8.0 -rst.linker>=1.9 +# keep these in sync with setup.cfg +sphinx jaraco.packaging>=6.1 +rst.linker>=1.9 +pygments-github-lexers==0.0.5 setuptools>=34 diff --git a/docs/setuptools.txt b/docs/setuptools.txt index 2e7fe3bd..7e0914b7 100644 --- a/docs/setuptools.txt +++ b/docs/setuptools.txt @@ -8,23 +8,10 @@ distribute Python packages, especially ones that have dependencies on other packages. Packages built and distributed using ``setuptools`` look to the user like -ordinary Python packages based on the ``distutils``. Your users don't need to -install or even know about setuptools in order to use them, and you don't -have to include the entire setuptools package in your distributions. By -including just a single `bootstrap module`_ (a 12K .py file), your package will -automatically download and install ``setuptools`` if the user is building your -package from source and doesn't have a suitable version already installed. - -.. _bootstrap module: https://bootstrap.pypa.io/ez_setup.py +ordinary Python packages based on the ``distutils``. Feature Highlights: -* Automatically find/download/install/upgrade dependencies at build time using - the `EasyInstall tool <easy_install.html>`_, - which supports downloading via HTTP, FTP, Subversion, and SourceForge, and - automatically scans web pages linked from PyPI to find download links. (It's - the closest thing to CPAN currently available for Python.) - * Create `Python Eggs <http://peak.telecommunity.com/DevCenter/PythonEggs>`_ - a single-file importable distribution format @@ -62,8 +49,6 @@ Feature Highlights: .. contents:: **Table of Contents** -.. _ez_setup.py: `bootstrap module`_ - ----------------- Developer's Guide @@ -73,15 +58,11 @@ Developer's Guide Installing ``setuptools`` ========================= -.. _EasyInstall Installation Instructions: easy_install.html - -.. _Custom Installation Locations: easy_install.html - .. _Installing Packages: https://packaging.python.org/tutorials/installing-packages/ To install the latest version of setuptools, use:: - pip install -U setuptools + pip install --upgrade setuptools Refer to `Installing Packages`_ guide for more information. @@ -107,7 +88,7 @@ packages in the directory where the setup.py lives. See the `Command Reference`_ section below to see what commands you can give to this setup script. For example, to produce a source distribution, simply invoke:: - python setup.py sdist + setup.py sdist Of course, before you release your project to PyPI, you'll want to add a bit more information to your setup script to help people find or learn about your @@ -119,17 +100,17 @@ dependencies, and perhaps some data files and scripts:: name="HelloWorld", version="0.1", packages=find_packages(), - scripts=['say_hello.py'], + scripts=["say_hello.py"], # Project uses reStructuredText, so ensure that the docutils get # installed or upgraded on the target machine - install_requires=['docutils>=0.3'], + install_requires=["docutils>=0.3"], package_data={ # If any package contains *.txt or *.rst files, include them: - '': ['*.txt', '*.rst'], - # And include any *.msg files found in the 'hello' package, too: - 'hello': ['*.msg'], + "": ["*.txt", "*.rst"], + # And include any *.msg files found in the "hello" package, too: + "hello": ["*.msg"], }, # metadata to display on PyPI @@ -144,7 +125,7 @@ dependencies, and perhaps some data files and scripts:: "Source Code": "https://code.example.com/HelloWorld/", }, classifiers=[ - 'License :: OSI Approved :: Python Software Foundation License' + "License :: OSI Approved :: Python Software Foundation License" ] # could also include long_description, download_url, etc. @@ -160,7 +141,7 @@ Specifying Your Project's Version Setuptools can work well with most versioning schemes; there are, however, a few special things to watch out for, in order to ensure that setuptools and -EasyInstall can always tell what version of your package is newer than another +other tools can always tell what version of your package is newer than another version. Knowing these things will also help you correctly specify what versions of other projects your project depends on. @@ -226,11 +207,11 @@ but here are a few tips that will keep you out of trouble in the corner cases: to compare different version numbers:: >>> from pkg_resources import parse_version - >>> parse_version('1.9.a.dev') == parse_version('1.9a0dev') + >>> parse_version("1.9.a.dev") == parse_version("1.9a0dev") True - >>> parse_version('2.1-rc2') < parse_version('2.1') + >>> parse_version("2.1-rc2") < parse_version("2.1") True - >>> parse_version('0.6a9dev-r41475') < parse_version('0.6a9') + >>> parse_version("0.6a9dev-r41475") < parse_version("0.6a9") True Once you've decided on a version numbering scheme for your project, you can @@ -248,170 +229,7 @@ The following keyword arguments to ``setup()`` are added or changed by ``setuptools``. All of them are optional; you do not have to supply them unless you need the associated ``setuptools`` feature. -``include_package_data`` - If set to ``True``, this tells ``setuptools`` to automatically include any - data files it finds inside your package directories that are specified by - your ``MANIFEST.in`` file. For more information, see the section below on - `Including Data Files`_. - -``exclude_package_data`` - A dictionary mapping package names to lists of glob patterns that should - be *excluded* from your package directories. You can use this to trim back - any excess files included by ``include_package_data``. For a complete - description and examples, see the section below on `Including Data Files`_. - -``package_data`` - A dictionary mapping package names to lists of glob patterns. For a - complete description and examples, see the section below on `Including - Data Files`_. You do not need to use this option if you are using - ``include_package_data``, unless you need to add e.g. files that are - generated by your setup script and build process. (And are therefore not - in source control or are files that you don't want to include in your - source distribution.) - -``zip_safe`` - A boolean (True or False) flag specifying whether the project can be - safely installed and run from a zip file. If this argument is not - supplied, the ``bdist_egg`` command will have to analyze all of your - project's contents for possible problems each time it builds an egg. - -``install_requires`` - A string or list of strings specifying what other distributions need to - be installed when this one is. See the section below on `Declaring - Dependencies`_ for details and examples of the format of this argument. - -``entry_points`` - A dictionary mapping entry point group names to strings or lists of strings - defining the entry points. Entry points are used to support dynamic - discovery of services or plugins provided by a project. See `Dynamic - Discovery of Services and Plugins`_ for details and examples of the format - of this argument. In addition, this keyword is used to support `Automatic - Script Creation`_. - -``extras_require`` - A dictionary mapping names of "extras" (optional features of your project) - to strings or lists of strings specifying what other distributions must be - installed to support those features. See the section below on `Declaring - Dependencies`_ for details and examples of the format of this argument. - -``python_requires`` - A string corresponding to a version specifier (as defined in PEP 440) for - the Python version, used to specify the Requires-Python defined in PEP 345. - -``setup_requires`` - A string or list of strings specifying what other distributions need to - be present in order for the *setup script* to run. ``setuptools`` will - attempt to obtain these (even going so far as to download them using - ``EasyInstall``) before processing the rest of the setup script or commands. - This argument is needed if you are using distutils extensions as part of - your build process; for example, extensions that process setup() arguments - and turn them into EGG-INFO metadata files. - - (Note: projects listed in ``setup_requires`` will NOT be automatically - installed on the system where the setup script is being run. They are - simply downloaded to the ./.eggs directory if they're not locally available - already. If you want them to be installed, as well as being available - when the setup script is run, you should add them to ``install_requires`` - **and** ``setup_requires``.) - -``dependency_links`` - A list of strings naming URLs to be searched when satisfying dependencies. - These links will be used if needed to install packages specified by - ``setup_requires`` or ``tests_require``. They will also be written into - the egg's metadata for use by tools like EasyInstall to use when installing - an ``.egg`` file. - -``namespace_packages`` - A list of strings naming the project's "namespace packages". A namespace - package is a package that may be split across multiple project - distributions. For example, Zope 3's ``zope`` package is a namespace - package, because subpackages like ``zope.interface`` and ``zope.publisher`` - may be distributed separately. The egg runtime system can automatically - merge such subpackages into a single parent package at runtime, as long - as you declare them in each project that contains any subpackages of the - namespace package, and as long as the namespace package's ``__init__.py`` - does not contain any code other than a namespace declaration. See the - section below on `Namespace Packages`_ for more information. - -``test_suite`` - A string naming a ``unittest.TestCase`` subclass (or a package or module - containing one or more of them, or a method of such a subclass), or naming - a function that can be called with no arguments and returns a - ``unittest.TestSuite``. If the named suite is a module, and the module - has an ``additional_tests()`` function, it is called and the results are - 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. - - Specifying this argument enables use of the `test`_ command to run the - specified test suite, e.g. via ``setup.py test``. See the section on the - `test`_ command below for more details. - -``tests_require`` - If your project's tests need one or more additional packages besides those - needed to install it, you can use this option to specify them. It should - be a string or list of strings specifying what other distributions need to - be present for the package's tests to run. When you run the ``test`` - command, ``setuptools`` will attempt to obtain these (even going - so far as to download them using ``EasyInstall``). Note that these - required projects will *not* be installed on the system where the tests - are run, but only downloaded to the project's setup directory if they're - not already installed locally. - -.. _test_loader: - -``test_loader`` - If you would like to use a different way of finding tests to run than what - setuptools normally uses, you can specify a module name and class name in - this argument. The named class must be instantiable with no arguments, and - its instances must support the ``loadTestsFromNames()`` method as defined - in the Python ``unittest`` module's ``TestLoader`` class. Setuptools will - pass only one test "name" in the `names` argument: the value supplied for - the ``test_suite`` argument. The loader you specify may interpret this - string in any way it likes, as there are no restrictions on what may be - contained in a ``test_suite`` string. - - The module name and class name must be separated by a ``:``. The default - value of this argument is ``"setuptools.command.test:ScanningLoader"``. If - you want to use the default ``unittest`` behavior, you can specify - ``"unittest:TestLoader"`` as your ``test_loader`` argument instead. This - will prevent automatic scanning of submodules and subpackages. - - The module and class you specify here may be contained in another package, - as long as you use the ``tests_require`` option to ensure that the package - containing the loader class is available when the ``test`` command is run. - -``eager_resources`` - A list of strings naming resources that should be extracted together, if - any of them is needed, or if any C extensions included in the project are - imported. This argument is only useful if the project will be installed as - a zipfile, and there is a need to have all of the listed resources be - extracted to the filesystem *as a unit*. Resources listed here - should be '/'-separated paths, relative to the source root, so to list a - resource ``foo.png`` in package ``bar.baz``, you would include the string - ``bar/baz/foo.png`` in this argument. - - If you only need to obtain resources one at a time, or you don't have any C - extensions that access other files in the project (such as data files or - shared libraries), you probably do NOT need this argument and shouldn't - mess with it. For more details on how this argument works, see the section - below on `Automatic Resource Extraction`_. - -``use_2to3`` - Convert the source code from Python 2 to Python 3 with 2to3 during the - build process. See :doc:`python3` for more details. - -``convert_2to3_doctests`` - List of doctest source files that need to be converted with 2to3. - See :doc:`python3` for more details. - -``use_2to3_fixers`` - A list of modules to search for additional fixers to be used during - the 2to3 conversion. See :doc:`python3` for more details. - -``project_urls`` - An arbitrary map of URL names to hyperlinks, allowing more extensible - documentation of where various resources can be found than the simple - ``url`` and ``download_url`` options provide. +.. include:: keywords.txt Using ``find_packages()`` @@ -428,7 +246,7 @@ the same directory as the setup script. Some projects use a ``src`` or ``lib`` directory as the root of their source tree, and those projects would of course use ``"src"`` or ``"lib"`` as the first argument to ``find_packages()``. (And -such projects also need something like ``package_dir={'':'src'}`` in their +such projects also need something like ``package_dir={"": "src"}`` in their ``setup()`` arguments, but that's just a normal distutils thing.) Anyway, ``find_packages()`` walks the target directory, filtering by inclusion @@ -495,7 +313,7 @@ top-level package called ``tests``! One way to avoid this problem is to use the setup( name="namespace.mypackage", version="0.1", - packages=find_namespace_packages(include=['namespace.*']) + packages=find_namespace_packages(include=["namespace.*"]) ) Another option is to use the "src" layout, where all package code is placed in @@ -515,11 +333,13 @@ With this layout, the package directory is specified as ``src``, as such:: setup(name="namespace.mypackage", version="0.1", - package_dir={'': 'src'}, - packages=find_namespace_packages(where='src')) + package_dir={"": "src"}, + packages=find_namespace_packages(where="src")) .. _PEP 420: https://www.python.org/dev/peps/pep-0420/ +.. _Automatic Script Creation: + Automatic Script Creation ========================= @@ -541,22 +361,23 @@ script called ``baz``, you might do something like this:: setup( # other arguments here... entry_points={ - 'console_scripts': [ - 'foo = my_package.some_module:main_func', - 'bar = other_module:some_func', + "console_scripts": [ + "foo = my_package.some_module:main_func", + "bar = other_module:some_func", ], - 'gui_scripts': [ - 'baz = my_package_gui:start_func', + "gui_scripts": [ + "baz = my_package_gui:start_func", ] } ) When this project is installed on non-Windows platforms (using "setup.py -install", "setup.py develop", or by using EasyInstall), a set of ``foo``, -``bar``, and ``baz`` scripts will be installed that import ``main_func`` and -``some_func`` from the specified modules. The functions you specify are called -with no arguments, and their return value is passed to ``sys.exit()``, so you -can return an errorlevel or message to print to stderr. +install", "setup.py develop", or with pip), a set of ``foo``, ``bar``, +and ``baz`` scripts will be installed that import ``main_func`` and +``some_func`` from the specified modules. The functions you specify are +called with no arguments, and their return value is passed to +``sys.exit()``, so you can return an errorlevel or message to print to +stderr. On Windows, a set of ``foo.exe``, ``bar.exe``, and ``baz.exe`` launchers are created, alongside a set of ``foo.py``, ``bar.py``, and ``baz.pyw`` files. The @@ -574,6 +395,8 @@ Services and Plugins`_. "Eggsecutable" Scripts ---------------------- +.. deprecated:: 45.3.0 + Occasionally, there are situations where it's desirable to make an ``.egg`` file directly executable. You can do this by including an entry point such as the following:: @@ -581,8 +404,8 @@ as the following:: setup( # other arguments here... entry_points={ - 'setuptools.installation': [ - 'eggsecutable = my_package.some_module:main_func', + "setuptools.installation": [ + "eggsecutable = my_package.some_module:main_func", ] } ) @@ -596,10 +419,6 @@ Python must be available via the ``PATH`` environment variable, under its "long" name. That is, if the egg is built for Python 2.3, there must be a ``python2.3`` executable present in a directory on ``PATH``. -This feature is primarily intended to support ez_setup the installation of -setuptools itself on non-Windows platforms, but may also be useful for other -projects as well. - IMPORTANT NOTE: Eggs with an "eggsecutable" header cannot be renamed, or invoked via symlinks. They *must* be invoked using their original filename, in order to ensure that, once running, ``pkg_resources`` will know what project @@ -607,13 +426,14 @@ and version is in use. The header script will check this and exit with an error if the ``.egg`` file has been renamed or is invoked via a symlink that changes its base name. +.. _Declaring Dependencies: Declaring Dependencies ====================== ``setuptools`` supports automatically installing dependencies when a package is installed, and including information about dependencies in Python Eggs (so that -package management tools like EasyInstall can use the information). +package management tools like pip can use the information). ``setuptools`` and ``pkg_resources`` use a common syntax for specifying a project's required dependencies. This syntax consists of a project's PyPI @@ -652,10 +472,9 @@ requirement in a string, each requirement must begin on a new line. This has three effects: -1. When your project is installed, either by using EasyInstall, ``setup.py - install``, or ``setup.py develop``, all of the dependencies not already - installed will be located (via PyPI), downloaded, built (if necessary), - and installed. +1. When your project is installed, either by using pip, ``setup.py install``, + or ``setup.py develop``, all of the dependencies not already installed will + be located (via PyPI), downloaded, built (if necessary), and installed. 2. Any scripts in your project will be installed with wrappers that verify the availability of the specified dependencies at runtime, and ensure that @@ -675,6 +494,10 @@ using ``setup.py develop``.) Dependencies that aren't in PyPI -------------------------------- +.. warning:: + Dependency links support has been dropped by pip starting with version + 19.0 (released 2019-01-22). + If your project depends on packages that don't exist on PyPI, you may still be able to depend on them, as long as they are available for download as: @@ -725,9 +548,8 @@ This will do a checkout (or a clone, in Git and Mercurial parlance) to a temporary folder and run ``setup.py bdist_egg``. The ``dependency_links`` option takes the form of a list of URL strings. For -example, the below will cause EasyInstall to search the specified page for -eggs or source distributions, if the package's dependencies aren't already -installed:: +example, this will cause a search of the specified page for eggs or source +distributions, if the package's dependencies aren't already installed:: setup( ... @@ -757,8 +579,8 @@ For example, let's say that Project A offers optional PDF and reST support:: name="Project-A", ... extras_require={ - 'PDF': ["ReportLab>=1.2", "RXP"], - 'reST': ["docutils>=0.3"], + "PDF": ["ReportLab>=1.2", "RXP"], + "reST": ["docutils>=0.3"], } ) @@ -767,7 +589,7 @@ names of "extra" features, to strings or lists of strings describing those features' requirements. These requirements will *not* be automatically installed unless another package depends on them (directly or indirectly) by including the desired "extras" in square brackets after the associated project -name. (Or if the extras were listed in a requirement spec on the EasyInstall +name. (Or if the extras were listed in a requirement spec on the "pip install" command line.) Extras can be used by a project's `entry points`_ to specify dynamic @@ -779,9 +601,9 @@ declare it like this, so that the "PDF" requirements are only resolved if the name="Project-A", ... entry_points={ - 'console_scripts': [ - 'rst2pdf = project_a.tools.pdfgen [PDF]', - 'rst2html = project_a.tools.htmlgen', + "console_scripts": [ + "rst2pdf = project_a.tools.pdfgen [PDF]", + "rst2html = project_a.tools.htmlgen", # more script entry points ... ], } @@ -817,8 +639,8 @@ setup to this:: name="Project-A", ... extras_require={ - 'PDF': [], - 'reST': ["docutils>=0.3"], + "PDF": [], + "reST": ["docutils>=0.3"], } ) @@ -845,8 +667,8 @@ For example, here is a project that uses the ``enum`` module and ``pywin32``:: name="Project", ... install_requires=[ - 'enum34;python_version<"3.4"', - 'pywin32 >= 1.0;platform_system=="Windows"' + "enum34;python_version<'3.4'", + "pywin32 >= 1.0;platform_system=='Windows'" ] ) @@ -860,6 +682,8 @@ detailed in `PEP 508`_. .. _PEP 508: https://www.python.org/dev/peps/pep-0508/ +.. _Including Data Files: + Including Data Files ==================== @@ -894,9 +718,9 @@ e.g.:: ... package_data={ # If any package contains *.txt or *.rst files, include them: - '': ['*.txt', '*.rst'], - # And include any *.msg files found in the 'hello' package, too: - 'hello': ['*.msg'], + "": ["*.txt", "*.rst"], + # And include any *.msg files found in the "hello" package, too: + "hello": ["*.msg"], } ) @@ -919,15 +743,15 @@ The setuptools setup file might look like this:: from setuptools import setup, find_packages setup( ... - packages=find_packages('src'), # include all packages under src - package_dir={'':'src'}, # tell distutils packages are under src + packages=find_packages("src"), # include all packages under src + package_dir={"": "src"}, # tell distutils packages are under src package_data={ # If any package contains *.txt files, include them: - '': ['*.txt'], - # And include any *.dat files found in the 'data' subdirectory - # of the 'mypkg' package, also: - 'mypkg': ['data/*.dat'], + "": ["*.txt"], + # And include any *.dat files found in the "data" subdirectory + # of the "mypkg" package, also: + "mypkg": ["data/*.dat"], } ) @@ -942,7 +766,7 @@ converts slashes to appropriate platform-specific separators at build time. If datafiles are contained in a subdirectory of a package that isn't a package itself (no ``__init__.py``), then the subdirectory names (or ``*``) are required -in the ``package_data`` argument (as shown above with ``'data/*.dat'``). +in the ``package_data`` argument (as shown above with ``"data/*.dat"``). When building an ``sdist``, the datafiles are also drawn from the ``package_name.egg-info/SOURCES.txt`` file, so make sure that this is removed if @@ -955,7 +779,7 @@ python.org website. If using the setuptools-specific ``include_package_data`` argument, files specified by ``package_data`` will *not* be automatically added to the manifest unless they are listed in the MANIFEST.in file.) -__ http://docs.python.org/dist/node11.html +__ https://docs.python.org/3/distutils/setupscript.html#installing-package-data Sometimes, the ``include_package_data`` or ``package_data`` options alone aren't sufficient to precisely define what files you want included. For @@ -967,18 +791,18 @@ to do things like this:: from setuptools import setup, find_packages setup( ... - packages=find_packages('src'), # include all packages under src - package_dir={'':'src'}, # tell distutils packages are under src + packages=find_packages("src"), # include all packages under src + package_dir={"": "src"}, # tell distutils packages are under src include_package_data=True, # include everything in source control # ...but exclude README.txt from all packages - exclude_package_data={'': ['README.txt']}, + exclude_package_data={"": ["README.txt"]}, ) The ``exclude_package_data`` option is a dictionary mapping package names to lists of wildcard patterns, just like the ``package_data`` option. And, just -as with that option, a key of ``''`` will apply the given pattern(s) to all +as with that option, a key of ``""`` will apply the given pattern(s) to all packages. However, any files that match these patterns will be *excluded* from installation, even if they were listed in ``package_data`` or were included as a result of using ``include_package_data``. @@ -1016,11 +840,11 @@ and Python Eggs. It is strongly recommended that, if you are using data files, you should use the :ref:`ResourceManager API` of ``pkg_resources`` to access them. The ``pkg_resources`` module is distributed as part of setuptools, so if you're using setuptools to distribute your package, there is no reason not to -use its resource management API. See also `Accessing Package Resources`_ for +use its resource management API. See also `Importlib Resources`_ for a quick example of converting code that uses ``__file__`` to use ``pkg_resources`` instead. -.. _Accessing Package Resources: http://peak.telecommunity.com/DevCenter/PythonEggs#accessing-package-resources +.. _Importlib Resources: https://docs.python.org/3/library/importlib.html#module-importlib.resources Non-Package Data Files @@ -1035,6 +859,7 @@ no supported facility to reliably retrieve these resources. Instead, the PyPA recommends that any data files you wish to be accessible at run time be included in the package. +.. _Automatic Resource Extraction: Automatic Resource Extraction ----------------------------- @@ -1080,6 +905,8 @@ Extensible Applications and Frameworks .. _Entry Points: +.. _Dynamic Discovery of Services and Plugins: + Dynamic Discovery of Services and Plugins ----------------------------------------- @@ -1112,12 +939,12 @@ for our hypothetical blogging tool:: setup( # ... - entry_points={'blogtool.parsers': '.rst = some_module:SomeClass'} + entry_points={"blogtool.parsers": ".rst = some_module:SomeClass"} ) setup( # ... - entry_points={'blogtool.parsers': ['.rst = some_module:a_func']} + entry_points={"blogtool.parsers": [".rst = some_module:a_func"]} ) setup( @@ -1182,13 +1009,12 @@ preferred way of working (as opposed to using a common independent staging area or the site-packages directory). To do this, use the ``setup.py develop`` command. It works very similarly to -``setup.py install`` or the EasyInstall tool, except that it doesn't actually -install anything. Instead, it creates a special ``.egg-link`` file in the -deployment directory, that links to your project's source code. And, if your -deployment directory is Python's ``site-packages`` directory, it will also -update the ``easy-install.pth`` file to include your project's source code, -thereby making it available on ``sys.path`` for all programs using that Python -installation. +``setup.py install``, except that it doesn't actually install anything. +Instead, it creates a special ``.egg-link`` file in the deployment directory, +that links to your project's source code. And, if your deployment directory is +Python's ``site-packages`` directory, it will also update the +``easy-install.pth`` file to include your project's source code, thereby making +it available on ``sys.path`` for all programs using that Python installation. If you have enabled the ``use_2to3`` flag, then of course the ``.egg-link`` will not link directly to your source code when run under Python 3, since @@ -1216,7 +1042,7 @@ command; see the section on the `develop`_ command below for more details. Note that you can also apply setuptools commands to non-setuptools projects, using commands like this:: - python -c "import setuptools; execfile('setup.py')" develop + 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. @@ -1225,28 +1051,28 @@ the quoted part. Distributing a ``setuptools``-based project =========================================== -Detailed instructions to distribute a setuptools project can be found at +Detailed instructions to distribute a setuptools project can be found at `Packaging project tutorials`_. .. _Packaging project tutorials: https://packaging.python.org/tutorials/packaging-projects/#generating-distribution-archives Before you begin, make sure you have the latest versions of setuptools and wheel:: - python3 -m pip install --user --upgrade setuptools wheel + pip install --upgrade setuptools wheel To build a setuptools project, run this command from the same directory where setup.py is located:: - python3 setup.py sdist bdist_wheel + setup.py sdist bdist_wheel This will generate distribution archives in the `dist` directory. -Before you upload the generated archives make sure you're registered on +Before you upload the generated archives make sure you're registered on https://test.pypi.org/account/register/. You will also need to verify your email to be able to upload any packages. You should install twine to be able to upload packages:: - python3 -m pip install --user --upgrade setuptools wheel + pip install --upgrade twine Now, to upload these archives, run:: @@ -1254,25 +1080,11 @@ Now, to upload these archives, run:: To install your newly uploaded package ``example_pkg``, you can use pip:: - python3 -m pip install --index-url https://test.pypi.org/simple/ example_pkg + pip install --index-url https://test.pypi.org/simple/ example_pkg If you have issues at any point, please refer to `Packaging project tutorials`_ for clarification. -Distributing legacy ``setuptools`` projects using ez_setup.py -------------------------------------------------------------- - -.. warning:: **ez_setup** is deprecated in favor of PIP with **PEP-518** support. - -Distributing packages using the legacy ``ez_setup.py`` and ``easy_install`` is -deprecated in favor of PIP. Please consider migrating to using pip and twine based -distribution. - -However, if you still have any ``ez_setup`` based packages, documentation for -ez_setup based distributions can be found at `ez_setup distribution guide`_. - -.. _ez_setup distribution guide: ez_setup.html - Setting the ``zip_safe`` flag ----------------------------- @@ -1308,20 +1120,14 @@ you've checked over all the warnings it issued, and you are either satisfied it doesn't work, you can always change it to ``False``, which will force ``setuptools`` to install your project as a directory rather than as a zipfile. -Of course, the end-user can still override either decision, if they are using -EasyInstall to install your package. And, if you want to override for testing -purposes, you can just run ``setup.py easy_install --zip-ok .`` or ``setup.py -easy_install --always-unzip .`` in your project directory. to install the -package as a zipfile or directory, respectively. - In the future, as we gain more experience with different packages and become more satisfied with the robustness of the ``pkg_resources`` runtime, the "zip safety" analysis may become less conservative. However, we strongly recommend that you determine for yourself whether your project functions correctly when installed as a zipfile, correct any problems if you can, and then make an explicit declaration of ``True`` or ``False`` for the ``zip_safe`` -flag, so that it will not be necessary for ``bdist_egg`` or ``EasyInstall`` to -try to guess whether your project can work as a zipfile. +flag, so that it will not be necessary for ``bdist_egg`` to try to guess +whether your project can work as a zipfile. .. _Namespace Packages: @@ -1346,7 +1152,7 @@ participates in. For example, the ZopeInterface project might do this:: setup( # ... - namespace_packages=['zope'] + namespace_packages=["zope"] ) because it contains a ``zope.interface`` package that lives in the ``zope`` @@ -1364,7 +1170,7 @@ packages' ``__init__.py`` files (and the ``__init__.py`` of any parent packages), in a normal Python package layout. These ``__init__.py`` files *must* contain the line:: - __import__('pkg_resources').declare_namespace(__name__) + __import__("pkg_resources").declare_namespace(__name__) This code ensures that the namespace package machinery is operating and that the current package is registered as a namespace package. @@ -1435,9 +1241,9 @@ to generate a daily build or snapshot for. See the section below on the (Also, before you release your project, be sure to see the section above on `Specifying Your Project's Version`_ for more information about how pre- and -post-release tags affect how setuptools and EasyInstall interpret version -numbers. This is important in order to make sure that dependency processing -tools will know which versions of your project are newer than others.) +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 @@ -1447,7 +1253,7 @@ 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 +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. @@ -1493,58 +1299,6 @@ all practical purposes, you'll probably use only the ``--formats`` option, if you use any option at all. -Making your package available for EasyInstall ---------------------------------------------- - -There may be reasons why you don't want to upload distributions to -PyPI, and just want your existing distributions (or perhaps a Subversion -checkout) to be used instead. - -There are three ``setup()`` arguments that affect EasyInstall: - -``url`` and ``download_url`` - These become links on your project's PyPI page. EasyInstall will examine - them to see if they link to a package ("primary links"), or whether they are - HTML pages. If they're HTML pages, EasyInstall scans all HREF's on the - page for primary links - -``long_description`` - EasyInstall will check any URLs contained in this argument to see if they - are primary links. - -A URL is considered a "primary link" if it is a link to a .tar.gz, .tgz, .zip, -.egg, .egg.zip, .tar.bz2, or .exe file, or if it has an ``#egg=project`` or -``#egg=project-version`` fragment identifier attached to it. EasyInstall -attempts to determine a project name and optional version number from the text -of a primary link *without* downloading it. When it has found all the primary -links, EasyInstall will select the best match based on requested version, -platform compatibility, and other criteria. - -So, if your ``url`` or ``download_url`` point either directly to a downloadable -source distribution, or to HTML page(s) that have direct links to such, then -EasyInstall will be able to locate downloads automatically. If you want to -make Subversion checkouts available, then you should create links with either -``#egg=project`` or ``#egg=project-version`` added to the URL. You should -replace ``project`` and ``version`` with the values they would have in an egg -filename. (Be sure to actually generate an egg and then use the initial part -of the filename, rather than trying to guess what the escaped form of the -project name and version number will be.) - -Note that Subversion checkout links are of lower precedence than other kinds -of distributions, so EasyInstall will not select a Subversion checkout for -downloading unless it has a version included in the ``#egg=`` suffix, and -it's a higher version than EasyInstall has seen in any other links for your -project. - -As a result, it's a common practice to use mark checkout URLs with a version of -"dev" (i.e., ``#egg=projectname-dev``), so that users can do something like -this:: - - easy_install --editable projectname==dev - -in order to check out the in-development version of ``projectname``. - - Making "Official" (Non-Snapshot) Releases ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1558,7 +1312,7 @@ 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:: - python setup.py egg_info -Db "" sdist bdist_egg + setup.py egg_info -Db "" sdist bdist_egg The first part of this command (``egg_info -Db ""``) will override the configured tag information, before creating source and binary eggs. Thus, these @@ -1568,11 +1322,11 @@ 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.:: - python setup.py alias -u release egg_info -Db "" + setup.py alias -u release egg_info -Db "" You can then use it like this:: - python setup.py release sdist bdist_egg + setup.py release sdist bdist_egg Or of course you can create more elaborate aliases that do all of the above. See the sections below on the `egg_info`_ and `alias`_ commands for more ideas. @@ -1589,7 +1343,7 @@ To ensure Cython is available, include Cython in the build-requires section of your pyproject.toml:: [build-system] - requires=[..., 'cython'] + requires=[..., "cython"] Built with pip 10 or later, that declaration is sufficient to include Cython in the build. For broader compatibility, declare the dependency in your @@ -1689,6 +1443,9 @@ 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 @@ -1796,9 +1553,9 @@ 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 EasyInstall to install the project's -dependencies before using the ``develop`` command, if you need finer control -over the installation options for dependencies. +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`` @@ -1808,10 +1565,10 @@ over the installation options for dependencies. 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 EasyInstall to - activate 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. + 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 @@ -1820,8 +1577,8 @@ over the installation options for dependencies. 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`` or EasyInstall. (In which - case the wrapper script calls ``require()`` for you.) + 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 @@ -1874,25 +1631,6 @@ files), the ``develop`` command will use them as defaults, unless you override them in a ``[develop]`` section or on the command line. -``easy_install`` - Find and install packages -============================================ - -This command runs the `EasyInstall tool -<easy_install.html>`_ for you. It is exactly -equivalent to running the ``easy_install`` command. All command line arguments -following this command are consumed and not processed further by the distutils, -so this must be the last command listed on the command line. Please see -the EasyInstall documentation for the options reference and usage examples. -Normally, there is no reason to use this command via the command line, as you -can just use ``easy_install`` directly. It's only listed here so that you know -it's a distutils command, which means that you can: - -* create command aliases that use it, -* create distutils extensions that invoke it as a subcommand, and -* configure options for it in your ``setup.cfg`` or other distutils config - files. - - .. _egg_info: ``egg_info`` - Create egg metadata and set build tags @@ -1905,7 +1643,7 @@ 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 +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 @@ -1951,9 +1689,9 @@ added in the following order: (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 EasyInstall. See the section above on `Specifying Your Project's -Version`_ for an explanation of pre- and post-release tags, as well as tips on -how to choose and verify a versioning scheme for your your project.) +like pip. See the section above on `Specifying Your Project's Version`_ for an +explanation of pre- and post-release tags, as well as tips on how to choose and +verify a versioning scheme for your 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 @@ -1978,12 +1716,12 @@ Other ``egg_info`` Options Creating a dated "nightly build" snapshot egg:: - python setup.py egg_info --tag-date --tag-build=DEV bdist_egg + setup.py egg_info --tag-date --tag-build=DEV bdist_egg Creating a release with no version tags, even if some default tags are specified in ``setup.cfg``:: - python setup.py egg_info -RDb "" sdist bdist_egg + setup.py egg_info -RDb "" sdist bdist_egg (Notice that ``egg_info`` must always appear on the command line *before* any commands that you want the version changes to apply to.) @@ -2135,6 +1873,11 @@ distutils configuration file the option will be added to (or removed from). ``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 @@ -2152,7 +1895,7 @@ 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 `test_loader`_ documentation for more details.) +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 @@ -2180,22 +1923,21 @@ available: 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 =========================================================== -.. warning:: - **upload** is deprecated in favor of using `twine - <https://pypi.org/p/twine>`_ - -The ``upload`` command is implemented and `documented -<https://docs.python.org/3.1/distutils/uploading.html>`_ -in distutils. +The ``upload`` command was deprecated in version 40.0 and removed in version +42.0. Use `twine <https://pypi.org/p/twine>`_ instead. -New in 20.1: Added keyring support. -New in 40.0: Deprecated the upload command. +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>`_. ----------------------------------------- @@ -2205,8 +1947,9 @@ Configuring setup() using setup.cfg files .. note:: New in 30.3.0 (8 Dec 2016). .. important:: - A ``setup.py`` file containing a ``setup()`` function call is still - required even if your configuration resides in ``setup.cfg``. + If compatibility with legacy builds (i.e. those not using the :pep:`517` + build API) is desired, a ``setup.py`` file containing a ``setup()`` function + call is still required even if your configuration resides in ``setup.cfg``. ``Setuptools`` allows using configuration files (usually :file:`setup.cfg`) to define a package’s metadata and other options that are normally supplied @@ -2291,11 +2034,54 @@ Metadata and options are set in the config sections of the same name. * In some cases, complex values can be provided in dedicated subsections for clarity. -* Some keys allow ``file:``, ``attr:``, and ``find:`` and ``find_namespace:`` directives in +* Some keys allow ``file:``, ``attr:``, ``find:``, and ``find_namespace:`` directives in order to cover common usecases. * Unknown keys are ignored. +setup.cfg-only projects +======================= + +.. versionadded:: 40.9.0 + +If ``setup.py`` is missing from the project directory when a :pep:`517` +build is invoked, ``setuptools`` emulates a dummy ``setup.py`` file containing +only a ``setuptools.setup()`` call. + +.. note:: + + :pep:`517` doesn't support editable installs so this is currently + incompatible with ``pip install -e .``, as :pep:`517` does not support editable installs. + +This means that you can have a Python project with all build configuration +specified in ``setup.cfg``, without a ``setup.py`` file, if you **can rely +on** your project always being built by a :pep:`517`/:pep:`518` compatible +frontend. + +To use this feature: + +* Specify build requirements and :pep:`517` build backend in + ``pyproject.toml``. + For example: + + .. code-block:: toml + + [build-system] + requires = [ + "setuptools >= 40.9.0", + "wheel", + ] + build-backend = "setuptools.build_meta" + +* Use a :pep:`517` compatible build frontend, such as ``pip >= 19`` or ``pep517``. + + .. warning:: + + As :pep:`517` is new, support is not universal, and frontends that + do support it may still have bugs. For compatibility, you may want to + put a ``setup.py`` file containing only a ``setuptools.setup()`` + invocation. + Using a ``src/`` layout ======================= @@ -2345,6 +2131,12 @@ Special directives: * ``attr:`` - Value is read from a module attribute. ``attr:`` supports callables and iterables; unsupported types are cast using ``str()``. + + In order to support the common case of a literal value assigned to a variable + in a module containing (directly or indirectly) third-party imports, + ``attr:`` first tries to read the value from the module by examining the + module's AST. If that fails, ``attr:`` falls back to importing the module. + * ``file:`` - Value is read from a list of files and then concatenated @@ -2375,6 +2167,7 @@ maintainer_email maintainer-email str classifiers classifier file:, list-comma license str license_file str +license_files list-comma description summary file:, str long_description long-description file:, str long_description_content_type str 38.6.0 @@ -2416,7 +2209,7 @@ tests_require list-semi include_package_data bool packages find:, find_namespace:, list-comma package_dir dict -package_data section +package_data section (1) exclude_package_data section namespace_packages list-comma py_modules list-comma @@ -2433,6 +2226,10 @@ data_files dict 40.6.0 **find_namespace directive** - The ``find_namespace:`` directive is supported since Python >=3.3. +Notes: +1. In the `package_data` section, a key named with a single asterisk (`*`) +refers to all packages, in lieu of the empty string used in `setup.py`. + Configuration API ================= @@ -2447,7 +2244,7 @@ parsing ``metadata`` and ``options`` sections into a dictionary. from setuptools.config import read_configuration - conf_dict = read_configuration('/home/user/dev/package/setup.cfg') + conf_dict = read_configuration("/home/user/dev/package/setup.cfg") By default, ``read_configuration()`` will read only the file provided @@ -2515,6 +2312,10 @@ script defines entry points for them! Adding ``setup()`` Arguments ---------------------------- +.. warning:: Adding arguments to setup is discouraged as such arguments + are only supported through imperative execution and not supported through + declarative config. + Sometimes, your commands may need additional arguments to the ``setup()`` call. You can enable this by defining entry points in the ``distutils.setup_keywords`` group. For example, if you wanted a ``setup()`` @@ -2566,6 +2367,25 @@ script using your extension lists your project in its ``setup_requires`` argument. +Customizing Distribution Options +-------------------------------- + +Plugins may wish to extend or alter the options on a Distribution object to +suit the purposes of that project. For example, a tool that infers the +``Distribution.version`` from SCM-metadata may need to hook into the +option finalization. To enable this feature, Setuptools offers an entry +point "setuptools.finalize_distribution_options". That entry point must +be a callable taking one argument (the Distribution instance). + +If the callable has an ``.order`` property, that value will be used to +determine the order in which the hook is called. Lower numbers are called +first and the default is zero (0). + +Plugins may read, alter, and set properties on the distribution, but each +plugin is encouraged to load the configuration/settings for their behavior +independently. + + Adding new EGG-INFO Files ------------------------- @@ -2604,7 +2424,7 @@ a file. Here's what the writer utility looks like:: argname = os.path.splitext(basename)[0] value = getattr(cmd.distribution, argname, None) if value is not None: - value = '\n'.join(value) + '\n' + value = "\n".join(value) + "\n" cmd.write_or_delete_file(argname, filename, value) As you can see, ``egg_info.writers`` entry points must be a function taking |