diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/build_meta.txt | 89 | ||||
| -rw-r--r-- | docs/developer-guide.txt | 2 | ||||
| -rw-r--r-- | docs/history.txt | 2 | ||||
| -rw-r--r-- | docs/pkg_resources.txt | 6 | ||||
| -rw-r--r-- | docs/releases.txt | 40 | ||||
| -rw-r--r-- | docs/requirements.txt | 7 | ||||
| -rw-r--r-- | docs/setuptools.txt | 60 |
7 files changed, 164 insertions, 42 deletions
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/developer-guide.txt b/docs/developer-guide.txt index 0b4ae4d4..e6171e4e 100644 --- a/docs/developer-guide.txt +++ b/docs/developer-guide.txt @@ -139,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/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/pkg_resources.txt b/docs/pkg_resources.txt index b887a923..71568c1a 100644 --- a/docs/pkg_resources.txt +++ b/docs/pkg_resources.txt @@ -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/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 36b78dea..7e0914b7 100644 --- a/docs/setuptools.txt +++ b/docs/setuptools.txt @@ -395,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:: @@ -777,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 @@ -1945,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 @@ -2031,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 ======================= @@ -2085,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 |