summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authorcdfarrow <cdfarrow@users.noreply.github.com>2022-06-17 18:32:44 +1200
committerGitHub <noreply@github.com>2022-06-17 18:32:44 +1200
commitbf11294e54828c8bd3c319fb84a5c16513559a62 (patch)
treec7e92b34634fc8d43b26b241edf0529dcaebc860 /docs
parentd9e23903c9b97492db21f42beccf76bd287c1e05 (diff)
downloadpython-setuptools-git-bf11294e54828c8bd3c319fb84a5c16513559a62.tar.gz
Update build_meta.rst
Mainly grammar/style tweaks... which turned into a few more thoughts: About this statement: "decide which program to use to 'build from source' (the default is ``setuptools``)." I think 'default' conveys the wrong impression here when it is explaining the new way of doing things. PEP517 says, "(build) tools should revert to the legacy behaviour of running setup.py" Maybe a footnote would be better saying it is a fallback, for backward compatibility. (But, all the same, this is interesting information that now explains to me why 'py -m build' worked before I had tried using a pyproject.toml file.) Line 37: ``build_meta`` implements ``setuptools``'s build system support. This seems out of place, and doesn't make sense. build_meta hasn't been mentioned yet in this article. Maybe this sentence could go before line 61. Line 26-28: This seems like low-level detail that is out of place in this article. If you want to keep it, maybe add a note that the default directory is dist\. **The "bullet items" under the PEP517 section aren't formatting correctly in the Preview. Please check that I haven't messed anything up there in the final render.
Diffstat (limited to 'docs')
-rw-r--r--docs/build_meta.rst65
1 files changed, 33 insertions, 32 deletions
diff --git a/docs/build_meta.rst b/docs/build_meta.rst
index fab42b02..d3a56385 100644
--- a/docs/build_meta.rst
+++ b/docs/build_meta.rst
@@ -16,22 +16,23 @@ overhaul. Because ``setup.py`` scripts allow for arbitrary execution, it
is difficult to provide a reliable user experience across environments
and history.
-`PEP 517 <https://www.python.org/dev/peps/pep-0517/>`_ therefore came to
-the rescue and specified a new standard to package and distribute Python
+`PEP 517 <https://www.python.org/dev/peps/pep-0517/>`_ came to
+the rescue and specified a new standard for packaging and distributing Python
modules. Under PEP 517:
- A ``pyproject.toml`` file is used to specify what program to use
- for generating the distribution.
+ A ``pyproject.toml`` file is used to specify which program to use
+ to generate the 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.
+ Two functions provided by the program, ``build_wheel(directory: str)``
+ and ``build_sdist(directory: str)``, create the distribution bundle in the
+ specified ``directory``.
- 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 program is free to use its own configuration file or extend the ``.toml`` file.
+
+ The actual installation is done with ``pip install *.whl`` or
+ ``pip install *.tar.gz``. If ``*.whl`` is available, ``pip`` will go ahead and copy
+ its files into the ``site-packages`` directory. If not, ``pip`` will look at
+ ``pyproject.toml`` and decide which program to use to 'build from source'
(the default is ``setuptools``).
With this standard, switching between packaging tools is a lot easier. ``build_meta``
@@ -50,9 +51,9 @@ files, a ``pyproject.toml`` file and a ``setup.cfg`` file::
__init__.py
module.py
-The pyproject.toml file is required to specify the build system (i.e. what is
+The pyproject.toml file specifies 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::
+setuptools the content would be::
[build-system]
requires = ["setuptools"]
@@ -102,24 +103,24 @@ Dynamic build dependencies and other ``build_meta`` tweaks
----------------------------------------------------------
With the changes introduced by :pep:`517` and :pep:`518`, the
-``setup_requires`` configuration field was made deprecated in ``setup.cfg`` and
+``setup_requires`` configuration field was deprecated in ``setup.cfg`` and
``setup.py``, in favour of directly listing build dependencies in the
``requires`` field of the ``build-system`` table of ``pyproject.toml``.
This approach has a series of advantages and gives package managers and
-installers the ability to inspect in advance the build requirements and
+installers the ability to inspect the build requirements in advance and
perform a series of optimisations.
-However some package authors might still need to dynamically inspect the final
-users machine before deciding these requirements. One way of doing that, as
-specified by :pep:`517`, is to "tweak" ``setuptools.build_meta`` by using a
+However, some package authors might still need to dynamically inspect the final
+user's machine before deciding these requirements. One way of doing that, as
+specified by :pep:`517`, is to "tweak" ``setuptools.build_meta`` by using an
:pep:`in-tree backend <517#in-tree-build-backends>`.
-.. tip:: Before implementing a *in-tree* backend, have a look on
- :pep:`PEP 508 <508#environment-markers>`. Most of the times, dependencies
+.. tip:: Before implementing an *in-tree* backend, have a look at
+ :pep:`PEP 508 <508#environment-markers>`. Most of the time, dependencies
with **environment markers** are enough to differentiate operating systems
and platforms.
-If you add the following configuration to your ``pyproject.toml``:
+If you put the following configuration in your ``pyproject.toml``:
.. code-block:: toml
@@ -129,7 +130,7 @@ If you add the following configuration to your ``pyproject.toml``:
backend-path = ["_custom_build"]
-then you should be able to implement a thin wrapper around ``build_meta`` in
+then you can implement a thin wrapper around ``build_meta`` in
the ``_custom_build/backend.py`` file, as shown in the following example:
.. code-block:: python
@@ -159,17 +160,17 @@ requirements.
and :pypi:`setuptools-svn`), or by correctly setting up :ref:`MANIFEST.in
<manifest>`.
- If this is the first time you are using a customised backend, please have a
- look on the generated ``.tar.gz`` and ``.whl``.
- On POSIX systems that can be done with ``tar -tf dist/*.tar.gz``
+ The generated ``.tar.gz`` and ``.whl`` files are compressed archives that
+ can be inspected as follows:
+ On POSIX systems, this can be done with ``tar -tf dist/*.tar.gz``
and ``unzip -l dist/*.whl``.
- On Windows systems you can rename the ``.whl`` to ``.zip`` to be able to
- inspect it on the file explorer, and use the same ``tar`` command in a
- command prompt (alternativelly there are GUI programs like `7-zip`_ that
- handle ``.tar.gz``).
+ On Windows systems, you can rename the ``.whl`` to ``.zip`` to be able to
+ inspect it from File Explorer, or you can use the aoove ``tar`` command in a
+ command prompt. Alternatively, there are GUI programs like `7-zip`_ that
+ handle ``.tar.gz`` and ``.whl`` files.
- In general the backend script should be present in the ``.tar.gz`` (so the
- project can be build from the source) but not in the ``.whl`` (otherwise the
+ In general, the backend script should be present in the ``.tar.gz`` (so the
+ project can be built from the source) but not in the ``.whl`` (otherwise the
backend script would end up being distributed alongside your package).
See ":doc:`/userguide/package_discovery`" for more details about package
files.