diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/build_meta.txt | 89 | ||||
| -rw-r--r-- | docs/conf.py | 6 | ||||
| -rw-r--r-- | docs/developer-guide.txt | 14 | ||||
| -rw-r--r-- | docs/distutils-legacy.txt | 25 | ||||
| -rw-r--r-- | docs/history.txt | 2 | ||||
| -rw-r--r-- | docs/index.txt | 14 | ||||
| -rw-r--r-- | docs/keywords.txt | 336 | ||||
| -rw-r--r-- | docs/pkg_resources.txt | 20 | ||||
| -rw-r--r-- | docs/python 2 sunset.txt | 69 | ||||
| -rw-r--r-- | docs/releases.txt | 40 | ||||
| -rw-r--r-- | docs/requirements.txt | 7 | ||||
| -rw-r--r-- | docs/setuptools.txt | 249 |
12 files changed, 630 insertions, 241 deletions
diff --git a/docs/build_meta.txt b/docs/build_meta.txt new file mode 100644 index 00000000..fcc2b7fe --- /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 965ee264..64d0c61e 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -89,7 +89,7 @@ link_files = { url='http://bugs.jython.org/issue{jython}', ), dict( - pattern=r'Python #(?P<python>\d+)', + pattern=r'(Python #|bpo-)(?P<python>\d+)', url='http://bugs.python.org/issue{python}', ), dict( @@ -117,6 +117,10 @@ link_files = { url='{GH}/jaraco/setuptools_svn/issues/{setuptools_svn}', ), dict( + pattern=r'pypa/distutils#(?P<distutils>\d+)', + url='{GH}/pypa/distutils/issues/{distutils}', + ), + dict( pattern=r'^(?m)((?P<scm_version>v?\d+(\.\d+){1,2}))\n[-=]+\n', with_scm='{text}\n{rev[timestamp]:%d %b %Y}\n', ), diff --git a/docs/developer-guide.txt b/docs/developer-guide.txt index 0b4ae4d4..e84cd640 100644 --- a/docs/developer-guide.txt +++ b/docs/developer-guide.txt @@ -23,16 +23,16 @@ contribution. Project Management ------------------ -Setuptools is maintained primarily in Github at `this home +Setuptools is maintained primarily in GitHub at `this home <https://github.com/pypa/setuptools>`_. Setuptools is maintained under the Python Packaging Authority (PyPA) with several core contributors. All bugs -for Setuptools are filed and the canonical source is maintained in Github. +for Setuptools are filed and the canonical source is maintained in GitHub. User support and discussions are done through the issue tracker (for specific) -issues, through the distutils-sig mailing list, or on IRC (Freenode) at +issues, through the `distutils-sig mailing list <https://mail.python.org/mailman3/lists/distutils-sig.python.org/>`_, or on IRC (Freenode) at #pypa. -Discussions about development happen on the pypa-dev mailing list or on +Discussions about development happen on the distutils-sig mailing list or on `Gitter <https://gitter.im/pypa/setuptools>`_. ----------------- @@ -44,7 +44,7 @@ describing the motivation behind making changes. First search to see if a ticket already exists for your issue. If not, create one. Try to think from the perspective of the reader. Explain what behavior you expected, what you got instead, and what factors might have contributed to the unexpected -behavior. In Github, surround a block of code or traceback with the triple +behavior. In GitHub, surround a block of code or traceback with the triple backtick "\`\`\`" so that it is formatted nicely. Filing a ticket provides a forum for justification, discussion, and @@ -139,11 +139,11 @@ 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 cannot declare dependencies other than through ``setuptools/_vendor/vendored.txt`` and -``pkg_reosurces/_vendor/vendored.txt`` and refreshed by way of +``pkg_resources/_vendor/vendored.txt`` and refreshed by way of ``paver update_vendored`` (pavement.py). diff --git a/docs/distutils-legacy.txt b/docs/distutils-legacy.txt new file mode 100644 index 00000000..a5d96260 --- /dev/null +++ b/docs/distutils-legacy.txt @@ -0,0 +1,25 @@ +Porting from Distutils +====================== + +Setuptools and the PyPA have a `stated goal <https://github.com/pypa/packaging-problems/issues/127>`_ to make Setuptools the reference API for distutils. + +Since the 49.1.2 release, Setuptools includes a local, vendored copy of distutils (from late copies of CPython) that is disabled by default. To enable the use of this copy of distutils when invoking setuptools, set the enviroment variable: + + SETUPTOOLS_USE_DISTUTILS=local + +This behavior is planned to become the default. + +Prefer Setuptools +----------------- + +As Distutils is deprecated, any usage of functions or objects from distutils is similarly discouraged, and Setuptools aims to replace or deprecate all such uses. This section describes the recommended replacements. + +``distutils.core.setup`` → ``setuptools.setup`` + +``distutils.cmd.Command`` → ``setuptools.Command`` + +``distutils.log`` → (no replacement yet) + +``distutils.version.*`` → ``packaging.version.*`` + +If a project relies on uses of ``distutils`` that do not have a suitable replacement above, please search the `Setuptools issue tracker <https://github.com/pypa/setuptools/issues/>`_ and file a request, describing the use-case so that Setuptools' maintainers can investigate. Please provide enough detail to help the maintainers understand how distutils is used, what value it provides, and why that behavior should be supported. 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/index.txt b/docs/index.txt index 13a46e74..5ee17eac 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -1,15 +1,8 @@ -Welcome to Setuptools' documentation! -===================================== +Documentation +============= Setuptools is a fully-featured, actively-maintained, and stable library -designed to facilitate packaging Python projects, where packaging includes: - - - Python package and module definitions - - Distribution package metadata - - Test hooks - - Project installation - - Platform-specific details - - Python 3 support +designed to facilitate packaging Python projects. Documentation content: @@ -22,4 +15,5 @@ Documentation content: development roadmap Deprecated: Easy Install <easy_install> + distutils-legacy history 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 b887a923..7d0d8da9 100644 --- a/docs/pkg_resources.txt +++ b/docs/pkg_resources.txt @@ -594,7 +594,7 @@ Requirements Parsing FooProject >= 1.2 Fizzy [foo, bar] - PickyThing<1.6,>1.9,!=1.9.6,<2.0a0,==2.4c1 + PickyThing>1.6,<=1.9,!=1.8.6 SomethingWhoseVersionIDontCareAbout SomethingWithMarker[foo]>1.0;python_version<"2.7" @@ -1596,12 +1596,12 @@ Parsing Utilities See ``to_filename()``. ``safe_version(version)`` - This will return the normalized form of any PEP 440 version, if the version - string is not PEP 440 compatible than it is similar to ``safe_name()`` - except that spaces in the input become dots, and dots are allowed to exist - in the output. As with ``safe_name()``, if you are generating a filename - from this you should replace any "-" characters in the output with - underscores. + This will return the normalized form of any PEP 440 version. If the version + string is not PEP 440 compatible, this function behaves similar to + ``safe_name()`` except that spaces in the input become dots, and dots are + allowed to exist in the output. As with ``safe_name()``, if you are + generating a filename from this you should replace any "-" characters in + the output with underscores. ``safe_extra(extra)`` Return a "safe" form of an extra's name, suitable for use in a requirement @@ -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. diff --git a/docs/python 2 sunset.txt b/docs/python 2 sunset.txt new file mode 100644 index 00000000..f7b7ee25 --- /dev/null +++ b/docs/python 2 sunset.txt @@ -0,0 +1,69 @@ +:orphan: + +Python 2 Sunset +=============== + +Since January 2020 and the release of Setuptools 45, Python 2 is no longer +supported by the most current release (`discussion +<https://github.com/pypa/setuptools/issues/1458>`_). Setuptools as a project +continues to support Python 2 with bugfixes and important features on +Setuptools 44.x. + +By design, most users will be unaffected by this change. That's because +Setuptools 45 declares its supported Python versions to exclude Python 2.7, +and installers such as pip 9 or later will honor this declaration and prevent +installation of Setuptools 45 or later in Python 2 environments. + +Users that do import any portion of Setuptools 45 or later on Python 2 are +directed to this documentation to provide guidance on how to work around the +issues. + +Workarounds +----------- + +The best recommendation is to avoid Python 2 and move to Python 3 where +possible. This project acknowledges that not all environments can drop Python +2 support, so provides other options. + +In less common scenarios, later versions of Setuptools can be installed on +unsupported Python versions. In these environments, the installer is advised +to first install ``setuptools<45`` to "pin Setuptools" to a compatible +version. + +- When using older versions of pip (before 9.0), the ``Requires-Python`` + directive is not honored and invalid versions can be installed. Users are + advised first to upgrade pip and retry or to pin Setuptools. Use ``pip + --version`` to determine the version of pip. +- When using ``easy_install``, ``Requires-Python`` is not honored and later + versions can be installed. In this case, users are advised to pin + Setuptools. This applies to ``setup.py install`` invocations as well, as + they use Setuptools under the hood. + +It's still not working +---------------------- + +If after trying the above steps, the Python environment still has incompatible +versions of Setuptools installed, here are some things to try. + +1. Uninstall and reinstall Setuptools. Run ``pip uninstall -y setuptools`` for + the relevant environment. Repeat until there is no Setuptools installed. + Then ``pip install setuptools``. +2. If possible, attempt to replicate the problem in a second environment + (virtual machine, friend's computer, etc). If the issue is isolated to just + one unique enviornment, first determine what is different about those + environments (or reinstall/reset the failing one to defaults). +3. End users who are not themselves the maintainers for the package they are + trying to install should contact the support channels for the relevant + application. Please be considerate of those projects by searching for + existing issues and following the latest guidance before reaching out for + support. When filing an issue, be sure to give as much detail as possible + to help the maintainers understand what factors led to the issue after + following their recommended guidance. +4. Reach out to your local support groups. There's a good chance someone + nearby has the expertise and willingness to help. +5. If all else fails, `file this template + <https://github.com/pypa/setuptools/issues/new?assignees=&labels=Python+2&template=setuptools-warns-about-python-2-incompatibility.md&title=Incompatible+install+in+(summarize+your+environment)>`_ + with Setuptools. Please complete the whole template, providing as much + detail about what factors led to the issue. Setuptools maintainers will + summarily close tickets filed without any meaningful detail or engagement + with the issue. 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 new file mode 100644 index 00000000..104d68fa --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,7 @@ +# 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 efcd0a86..d60c87a0 100644 --- a/docs/setuptools.txt +++ b/docs/setuptools.txt @@ -229,174 +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 (using pip if available) 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 during install by tools that support them. - -``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. - - 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 (using pip if - available). 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 `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()`` @@ -505,6 +338,8 @@ With this layout, the package directory is specified as ``src``, as such:: .. _PEP 420: https://www.python.org/dev/peps/pep-0420/ +.. _Automatic Script Creation: + Automatic Script Creation ========================= @@ -591,6 +426,7 @@ 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 ====================== @@ -846,6 +682,8 @@ detailed in `PEP 508`_. .. _PEP 508: https://www.python.org/dev/peps/pep-0508/ +.. _Including Data Files: + Including Data Files ==================== @@ -941,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 @@ -1021,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 ----------------------------- @@ -1066,6 +905,8 @@ Extensible Applications and Frameworks .. _Entry Points: +.. _Dynamic Discovery of Services and Plugins: + Dynamic Discovery of Services and Plugins ----------------------------------------- @@ -2054,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 @@ -2106,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 @@ -2146,11 +1988,11 @@ boilerplate code in some cases. include_package_data = True packages = find: scripts = - bin/first.py - bin/second.py + bin/first.py + bin/second.py install_requires = - requests - importlib; python_version == "2.6" + requests + importlib; python_version == "2.6" [options.package_data] * = *.txt, *.rst @@ -2186,17 +2028,60 @@ Metadata and options are set in the config sections of the same name. [metadata] keywords = - one - two + one + two * 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 ======================= @@ -2246,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 |