From 3ab0328dbd8208c4dae3aad9a5182ef6052a0b3a Mon Sep 17 00:00:00 2001 From: konstin Date: Mon, 12 Dec 2022 00:13:22 +0100 Subject: [PATCH 001/121] Dependency Specifiers: Don't require whitespace after URL otherwise would `numpy @ https://example.org/numpy` is not a valid specifier (missing whitespace after the URL). This already what pip and packaging do and also what the parsley grammar says --- source/specifications/dependency-specifiers.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/specifications/dependency-specifiers.rst b/source/specifications/dependency-specifiers.rst index a5bc52bc7..5453e367c 100644 --- a/source/specifications/dependency-specifiers.rst +++ b/source/specifications/dependency-specifiers.rst @@ -113,7 +113,7 @@ Giving us a rule for name based requirements:: And a rule for direct reference specifications:: - url_req = name wsp* extras? wsp* urlspec wsp+ quoted_marker? + url_req = name wsp* extras? wsp* urlspec (wsp+ quoted_marker?)? Leading to the unified rule that can specify a dependency.:: From 4193e048f5bac6b5e996000e329cddc069a0a40a Mon Sep 17 00:00:00 2001 From: konstin Date: Mon, 12 Dec 2022 00:17:35 +0100 Subject: [PATCH 002/121] Dependency Specifiers: Require whitespace before `in` and `not in` Otherwise `numpy; os_namein 'posix'` would be a valid specifier which it isn't --- source/specifications/dependency-specifiers.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/specifications/dependency-specifiers.rst b/source/specifications/dependency-specifiers.rst index 5453e367c..9b29669d9 100644 --- a/source/specifications/dependency-specifiers.rst +++ b/source/specifications/dependency-specifiers.rst @@ -70,7 +70,7 @@ URI is defined in :rfc:`std-66 <3986>`):: Environment markers allow making a specification only take effect in some environments:: - marker_op = version_cmp | (wsp* 'in') | (wsp* 'not' wsp+ 'in') + marker_op = version_cmp | (wsp+ 'in') | (wsp+ 'not' wsp+ 'in') python_str_c = (wsp | letter | digit | '(' | ')' | '.' | '{' | '}' | '-' | '_' | '*' | '#' | ':' | ';' | ',' | '/' | '?' | '[' | ']' | '!' | '~' | '`' | '@' | '$' | '%' | '^' | From f91e32f29244fb8a9d313a9701b81036de25842e Mon Sep 17 00:00:00 2001 From: konstin Date: Mon, 12 Dec 2022 00:19:24 +0100 Subject: [PATCH 003/121] Dependency Specifiers: Require whitespace after `in` and `not in` Otherwise `numpy; os_name in'posix'` and `numpy; os_name inos_name` would be valid. pypa/packaging 22.0 actually allows currently `numpy; os_name in'posix'` --- source/specifications/dependency-specifiers.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/specifications/dependency-specifiers.rst b/source/specifications/dependency-specifiers.rst index 9b29669d9..8fc445013 100644 --- a/source/specifications/dependency-specifiers.rst +++ b/source/specifications/dependency-specifiers.rst @@ -70,7 +70,7 @@ URI is defined in :rfc:`std-66 <3986>`):: Environment markers allow making a specification only take effect in some environments:: - marker_op = version_cmp | (wsp+ 'in') | (wsp+ 'not' wsp+ 'in') + marker_op = version_cmp | (wsp+ 'in' wsp+) | (wsp+ 'not' wsp+ 'in' wsp+) python_str_c = (wsp | letter | digit | '(' | ')' | '.' | '{' | '}' | '-' | '_' | '*' | '#' | ':' | ';' | ',' | '/' | '?' | '[' | ']' | '!' | '~' | '`' | '@' | '$' | '%' | '^' | From b3ce0245bc3f0fe8f36bffa4c48dcdaf00159f9c Mon Sep 17 00:00:00 2001 From: Jean Abou Samra Date: Wed, 15 Nov 2023 23:34:09 +0100 Subject: [PATCH 004/121] Add discussion of package formats, expanding "Wheel vs Egg" discussion --- source/discussions/index.rst | 2 +- source/discussions/package-formats.rst | 193 ++++++++++++++++++ source/discussions/wheel-vs-egg.rst | 55 ----- .../binary-distribution-format.rst | 2 + 4 files changed, 196 insertions(+), 56 deletions(-) create mode 100644 source/discussions/package-formats.rst delete mode 100644 source/discussions/wheel-vs-egg.rst diff --git a/source/discussions/index.rst b/source/discussions/index.rst index b378ed810..5033bf703 100644 --- a/source/discussions/index.rst +++ b/source/discussions/index.rst @@ -11,7 +11,7 @@ specific topic. If you're just trying to get stuff done, see deploying-python-applications pip-vs-easy-install install-requires-vs-requirements - wheel-vs-egg distribution-package-vs-import-package + package-formats src-layout-vs-flat-layout setup-py-deprecated diff --git a/source/discussions/package-formats.rst b/source/discussions/package-formats.rst new file mode 100644 index 000000000..6d4dee35c --- /dev/null +++ b/source/discussions/package-formats.rst @@ -0,0 +1,193 @@ +.. _package-formats: + +=============== +Package Formats +=============== + +This page discusses the file formats that are used to distribute Python packages +and the differences between them. + +You will find files in two formats on package indices such as PyPI_: **source +distributions**, or **sdists** for short, and **binary distributions**, commonly +called **wheels**. For example, the `PyPI page for pip 23.3.1 `_ +lets you download two files, ``pip-23.3.1.tar.gz`` and +``pip-23.3.1-py3-none-any.whl``. The former is an sdist, the latter is a +wheel. As explained below, these serve different purposes. When publishing a +package on PyPI (or elsewhere), you should always upload both an sdist and one +or more wheel. + + +What is a source distribution? +============================== + +Conceptually, a source distribution is an archive of the source code in raw +form. Concretely, an sdist is a ``.tar.gz`` archive containing the source code +plus an additional special file called ``PKG-INFO``, which holds the project +metadata. The presence of this file helps packaging tools to be more efficient +by not needing to compute the metadata themselves. The ``PKG-INFO`` file follows +the format specified in :ref:`core-metadata` and is not intended to be written +by hand [#core-metadata-format]_. + +You can thus inspect the contents of an sdist by unpacking it using standard +tools to work with tar archives, such as ``tar -xvf`` on UNIX platforms (like +Linux and macOS), or :ref:`the command line interface of Python's tarfile module +` on any platform. + +Sdists serve several purposes in the packaging ecosystem. When :ref:`pip`, the +standard Python package installer, cannot find a wheel to install, it will fall +back on downloading a source distribution, compiling a wheel from it, and +installing the wheel. Furthermore, sdists are often used as the package source +by downstream packagers (such as Linux distributions, Conda, Homebrew and +MacPorts on macOS, ...), who, for various reasons, may prefer them over, e.g., +pulling from a Git repository. + +A source distribution is recognized by its file name, which has the form +:samp:`{package_name}-{version}.tar.gz`, e.g., ``pip-23.3.1.tar.gz``. + +.. TODO: provide clear guidance on whether sdists should contain docs and tests. + Discussion: https://discuss.python.org/t/should-sdists-include-docs-and-tests/14578 + +If you want technical details on the sdist format, read the :ref:`sdist +specification `. + + +What is a wheel? +================ + +Conceptually, a wheel contains exactly the files that need to be copied when +installing the package. + +There is a big difference between sdists and wheels for packages with +:term:`extension modules `, written in compiled languages like +C, C++ and Rust, which need to be compiled into platform-dependent machine code. +With these packages, wheels do not contain source code (like C source files) but +compiled, executable code (like ``.so`` files on Linux or DLLs on Windows). + +Furthermore, while there is only one sdist per version of a project, there may +be many wheels. Again, this is most relevant in the context of extension +modules. The compiled code of an extension module is tied to an operating system +and processor architecture, and often also to the version of the Python +interpreter (unless the :ref:`Python stable ABI ` is used). + +For pure-Python packages, the difference between sdists and wheels is less +marked. There is normally one single wheel, for all platforms and Python +versions. Python is an interpreted language, which does not need ahead-of-time +compilation, so wheels contain ``.py`` files just like sdists. + +If you are wondering about ``.pyc`` bytecode files: they are not included in +wheels, since they are cheap to generate, and including them would unnecessarily +force a huge number of packages to distribute one wheel per Python version +instead of one single wheel. Instead, installers like :ref:`pip` generate them +while installing the package. + +With that being said, there are still important differences between sdists and +wheels, even for pure Python projects. Wheels are meant to contain exactly what +is to be installed, and nothing more. In particular, wheels should never include +tests and documentation, while sdists commonly do. Also, the wheel format is +more complex than sdist. For example, it includes a special file -- called +``RECORD`` -- that lists all files in the wheel along with a hash of their +content, as a safety check of the download's integrity. + +At a glance, you might wonder if wheels are really needed for "plain and basic" +pure Python projects. Keep in mind that due to the flexibility of sdists, +installers like pip cannot install from sdists directly -- they need to first +build a wheel, by invoking the :term:`build backend` that the sdist specifies +(the build backend may do all sorts of transformations while building the wheel, +such as compiling C extensions). For this reason, even for a pure Python +project, you should always upload *both* an sdist and a wheel to PyPI or other +package indices. This makes installation much faster for your users, since a +wheel is directly installable. By only including files that must be installed, +wheels also make for smaller downloads. + +On the technical level, a wheel is a ZIP archive (unlike sdists which are TAR +archives). You can inspect its contents by unpacking it as a normal ZIP archive, +e.g., using ``unzip`` on UNIX platforms like Linux and macOS, ``Expand-Archive`` +in Powershell on Windows, or :ref:`the command line interface of Python's +zipfile module `. This can be very useful to check +that the wheel includes all the files you need it to. + +Inside a wheel, you will find the package's files, plus an additional directory +called :samp:`{package_name}-{version}.dist-info`. This directory contains +various files, including a ``METADATA`` file which is the equivalent of +``PKG-INFO`` in sdists, as well as ``RECORD``. This can be useful to ensure no +files are missing from your wheels. + +The file name of a wheel (ignoring some rarely used features) looks like this: +:samp:`{package_name}-{version}-{python_tag}-{abi_tag}-{platform_tag}.whl`. +This naming convention identifies which platforms and Python versions the wheel +is compatible with. For example, the name ``pip-23.3.1-py3-none-any.whl`` means +that: + +- (``py3``) This wheel can be installed on any implementation of Python 3, + whether CPython, the most widely used Python implementation, or an alternative + implementation like PyPy_; +- (``none``) It does not depend on the Python version; +- (``any``) It does not depend on the platform. + +The pattern ``py3-none-any`` is common for pure Python projects. Packages with +extension modules typically ship multiple wheels with more complex tags. + +All technical details on the wheel format can be found in the :ref:`wheel +specification `. + + +.. _egg-format: +.. _`Wheel vs Egg`: + +What about eggs? +================ + +"Egg" is an old package format that has been replaced with the wheel format. It +should not be used anymore. Since August 2023, PyPI `rejects egg uploads +`_. + +Here's a breakdown of the important differences between wheel and egg. + +* The egg format was introduced by :ref:`setuptools` in 2004, whereas the wheel + format was introduced by :pep:`427` in 2012. + +* Wheel has an :doc:`official standard specification + `. Egg did not. + +* Wheel is a :term:`distribution ` format, i.e a packaging + format. [#wheel-importable]_ Egg was both a distribution format and a runtime + installation format (if left zipped), and was designed to be importable. + +* Wheel archives do not include ``.pyc`` files. Therefore, when the distribution + only contains Python files (i.e. no compiled extensions), and is compatible + with Python 2 and 3, it's possible for a wheel to be "universal", similar to + an :term:`sdist `. + +* Wheel uses standard :ref:`.dist-info directories + `. Egg used ``.egg-info``. + +* Wheel has a :ref:`richer file naming convention `. A + single wheel archive can indicate its compatibility with a number of Python + language versions and implementations, ABIs, and system architectures. + +* Wheel is versioned. Every wheel file contains the version of the wheel + specification and the implementation that packaged it. + +* Wheel is internally organized by `sysconfig path type + `_, + therefore making it easier to convert to other formats. + +-------------------------------------------------------------------------------- + +.. [#core-metadata-format] This format is email-based. Although this would + be unlikely to be chosen today, backwards compatibility considerations lead to + it being kept as the canonical format. From the user point of view, this + is mostly invisible, since the metadata is specified by the user in a way + understood by the build backend, typically ``[project]`` in ``pyproject.toml``, + and translated by the build backend into ``PKG-INFO``. + +.. [#wheel-importable] Circumstantially, in some cases, wheels can be used + as an importable runtime format, although :ref:`this is not officially supported + at this time `. + + + +.. _pip-pypi: https://pypi.org/project/pip/23.3.1/#files +.. _pypi: https://pypi.org +.. _pypi-eggs-deprecation: https://blog.pypi.org/posts/2023-06-26-deprecate-egg-uploads/ +.. _pypy: https://pypy.org diff --git a/source/discussions/wheel-vs-egg.rst b/source/discussions/wheel-vs-egg.rst deleted file mode 100644 index d4a1114fb..000000000 --- a/source/discussions/wheel-vs-egg.rst +++ /dev/null @@ -1,55 +0,0 @@ -.. _`Wheel vs Egg`: - -============ -Wheel vs Egg -============ - -:term:`Wheel` and :term:`Egg` are both packaging formats that aim to support the -use case of needing an install artifact that doesn't require building or -compilation, which can be costly in testing and production workflows. - -The :term:`Egg` format was introduced by :ref:`setuptools` in 2004, whereas the -:term:`Wheel` format was introduced by :pep:`427` in 2012. - -:term:`Wheel` is currently considered the standard for :term:`built ` and :term:`binary ` packaging for Python. - -Here's a breakdown of the important differences between :term:`Wheel` and :term:`Egg`. - - -* :term:`Wheel` has an :doc:`official standard specification - `. - :term:`Egg` did not. - -* :term:`Wheel` is a :term:`distribution ` format, i.e a packaging - format. [1]_ :term:`Egg` was both a distribution format and a runtime - installation format (if left zipped), and was designed to be importable. - -* :term:`Wheel` archives do not include .pyc files. Therefore, when the - distribution only contains Python files (i.e. no compiled extensions), and is - compatible with Python 2 and 3, it's possible for a wheel to be "universal", - similar to an :term:`sdist `. - -* :term:`Wheel` uses :pep:`PEP376-compliant <376>` ``.dist-info`` - directories. Egg used ``.egg-info``. - -* :term:`Wheel` has a :pep:`richer file naming convention <425>`. A single - wheel archive can indicate its compatibility with a number of Python language - versions and implementations, ABIs, and system architectures. - -* :term:`Wheel` is versioned. Every wheel file contains the version of the wheel - specification and the implementation that packaged it. - -* :term:`Wheel` is internally organized by `sysconfig path type - `_, - therefore making it easier to convert to other formats. - -* :term:`Egg` uploads have been disabled for upload to PyPI, per :pep:`715`. - Read the `deprecation notice `_ - for more information. - ----- - -.. [1] Circumstantially, in some cases, wheels can be used as an importable - runtime format, although :ref:`this is not officially supported at this time - `. diff --git a/source/specifications/binary-distribution-format.rst b/source/specifications/binary-distribution-format.rst index 6637fed2e..7d2c4e2a0 100644 --- a/source/specifications/binary-distribution-format.rst +++ b/source/specifications/binary-distribution-format.rst @@ -84,6 +84,8 @@ Place ``.dist-info`` at the end of the archive. File Format ----------- +.. _wheel-file-name-spec: + File name convention '''''''''''''''''''' From 5af20bf30596aa9e00254377c11aa408538d8a6e Mon Sep 17 00:00:00 2001 From: Jean Abou Samra Date: Wed, 15 Nov 2023 23:42:45 +0100 Subject: [PATCH 005/121] Update glossary with references to the new "Package formats" discussion --- source/glossary.rst | 19 ++++++++----------- 1 file changed, 8 insertions(+), 11 deletions(-) diff --git a/source/glossary.rst b/source/glossary.rst index 1f55871fa..218c21168 100644 --- a/source/glossary.rst +++ b/source/glossary.rst @@ -47,11 +47,11 @@ Glossary A :term:`Distribution ` format containing files and metadata that only need to be moved to the correct location on the target system, to be installed. :term:`Wheel` is such a format, whereas - distutil's :term:`Source Distribution ` is not, in that it requires a build step before it can be installed. This format does not imply that Python files have to be precompiled (:term:`Wheel` intentionally does not include compiled - Python files). + Python files). See :ref:`package-formats` for more information. Distribution Package @@ -73,9 +73,8 @@ Glossary Egg A :term:`Built Distribution` format introduced by :ref:`setuptools`, - which is being replaced by :term:`Wheel`. For details, see - :doc:`The Internal Structure of Python Eggs ` and - `Python Eggs `_ + which has been replaced by :term:`Wheel`. For details, see + :ref:`egg-format`. Extension Module @@ -240,7 +239,8 @@ Glossary A :term:`distribution ` format (usually generated using ``python -m build --sdist``) that provides metadata and the essential source files needed for installing by a tool like :ref:`pip`, - or for generating a :term:`Built Distribution`. + or for generating a :term:`Built Distribution`. See :ref:`package-formats` + for more information. System Package @@ -266,11 +266,8 @@ Glossary Wheel - A :term:`Built Distribution` format introduced by an official - :doc:`standard specification - `, - which is intended to replace the :term:`Egg` format. Wheel is currently - supported by :ref:`pip`. + The standard :term:`Built Distribution` format. + See :ref:`package-formats` for more information. Working Set From 421bb9157a7cc3050f1e245f2465ba8eef6e617b Mon Sep 17 00:00:00 2001 From: konstin Date: Wed, 21 Feb 2024 10:16:16 +0100 Subject: [PATCH 006/121] RFC: Clarify that the direct_url.json url field must be a spec-compliant url Clarify that the `url` field in `direct_url.json` must be a valid url. --- source/specifications/direct-url-data-structure.rst | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/source/specifications/direct-url-data-structure.rst b/source/specifications/direct-url-data-structure.rst index da4d959e4..01687ded2 100644 --- a/source/specifications/direct-url-data-structure.rst +++ b/source/specifications/direct-url-data-structure.rst @@ -10,11 +10,6 @@ This document specifies a JSON-serializable abstract data structure that can rep URLs to python projects and distribution artifacts such as VCS source trees, local source trees, source distributions and wheels. -The representation of the components of this data structure as a :rfc:`1738` URL -is not formally specified at time of writing. A common representation is the pip URL -format. Other examples are provided in the :ref:`Version specifier specification `. - - Specification ============= @@ -22,8 +17,9 @@ The Direct URL Data Structure MUST be a dictionary, serializable to JSON accordi :rfc:`8259`. It MUST contain at least two fields. The first one is ``url``, with -type ``string``. Depending on what ``url`` refers to, the second field MUST be -one of ``vcs_info`` (if ``url`` is a VCS reference), ``archive_info`` (if +type ``string``. Its content must be a valid URL according to the +`WHATWG URL Standard `_. Depending on what ``url`` refers to, +the second field MUST be one of ``vcs_info`` (if ``url`` is a VCS reference), ``archive_info`` (if ``url`` is a source archives or a wheel), or ``dir_info`` (if ``url`` is a local directory). These info fields have a (possibly empty) subdictionary as value, with the possible keys defined below. @@ -396,3 +392,4 @@ History .. _archive-info-hashes: https://discuss.python.org/t/22299 +.. _whatwg-url-standard: https://url.spec.whatwg.org/ From 9e976ee1e0867453dfc667df55787c3d03220536 Mon Sep 17 00:00:00 2001 From: konstin Date: Wed, 21 Feb 2024 10:56:12 +0100 Subject: [PATCH 007/121] Clarify merging direct_url.json into urls paragraph --- source/specifications/direct-url-data-structure.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/source/specifications/direct-url-data-structure.rst b/source/specifications/direct-url-data-structure.rst index 01687ded2..26dc39eaa 100644 --- a/source/specifications/direct-url-data-structure.rst +++ b/source/specifications/direct-url-data-structure.rst @@ -10,6 +10,11 @@ This document specifies a JSON-serializable abstract data structure that can rep URLs to python projects and distribution artifacts such as VCS source trees, local source trees, source distributions and wheels. +At time of writing, it is not formally specified how to merge the parts of this +file into single URL that can be passed to tools. A common representation is the +pip URL format, other examples are provided in the +:ref:`Version specifier specification `. + Specification ============= From a8d19777dbe28ce08192e30847485240f8ce6004 Mon Sep 17 00:00:00 2001 From: konstin Date: Wed, 21 Feb 2024 19:36:51 +0100 Subject: [PATCH 008/121] Link to pip docs --- source/specifications/direct-url-data-structure.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/source/specifications/direct-url-data-structure.rst b/source/specifications/direct-url-data-structure.rst index 26dc39eaa..d9972dc37 100644 --- a/source/specifications/direct-url-data-structure.rst +++ b/source/specifications/direct-url-data-structure.rst @@ -12,7 +12,7 @@ source trees, source distributions and wheels. At time of writing, it is not formally specified how to merge the parts of this file into single URL that can be passed to tools. A common representation is the -pip URL format, other examples are provided in the +pip URL format (`VCS Support `_), other examples are provided in the :ref:`Version specifier specification `. Specification @@ -397,4 +397,5 @@ History .. _archive-info-hashes: https://discuss.python.org/t/22299 +.. _pip-vcs-support: https://pip.pypa.io/en/stable/topics/vcs-support/ .. _whatwg-url-standard: https://url.spec.whatwg.org/ From aad6bf5921e355deeb0f6bf3e8466f077581a35b Mon Sep 17 00:00:00 2001 From: konstin Date: Wed, 21 Feb 2024 19:36:59 +0100 Subject: [PATCH 009/121] New paragraph --- source/specifications/direct-url-data-structure.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/source/specifications/direct-url-data-structure.rst b/source/specifications/direct-url-data-structure.rst index d9972dc37..a14ebba98 100644 --- a/source/specifications/direct-url-data-structure.rst +++ b/source/specifications/direct-url-data-structure.rst @@ -23,8 +23,10 @@ The Direct URL Data Structure MUST be a dictionary, serializable to JSON accordi It MUST contain at least two fields. The first one is ``url``, with type ``string``. Its content must be a valid URL according to the -`WHATWG URL Standard `_. Depending on what ``url`` refers to, -the second field MUST be one of ``vcs_info`` (if ``url`` is a VCS reference), ``archive_info`` (if +`WHATWG URL Standard `_. + +Depending on what ``url`` refers to, the second field MUST be one of ``vcs_info`` +(if ``url`` is a VCS reference), ``archive_info`` (if ``url`` is a source archives or a wheel), or ``dir_info`` (if ``url`` is a local directory). These info fields have a (possibly empty) subdictionary as value, with the possible keys defined below. From bba849252c4bed9e7a615375eece739496852d02 Mon Sep 17 00:00:00 2001 From: konsti Date: Thu, 22 Feb 2024 10:50:50 +0100 Subject: [PATCH 010/121] Update source/specifications/direct-url-data-structure.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Stéphane Bidoul --- source/specifications/direct-url-data-structure.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/specifications/direct-url-data-structure.rst b/source/specifications/direct-url-data-structure.rst index a14ebba98..9afe5acd5 100644 --- a/source/specifications/direct-url-data-structure.rst +++ b/source/specifications/direct-url-data-structure.rst @@ -11,7 +11,7 @@ URLs to python projects and distribution artifacts such as VCS source trees, loc source trees, source distributions and wheels. At time of writing, it is not formally specified how to merge the parts of this -file into single URL that can be passed to tools. A common representation is the +data structure into single URL that can be passed to tools. A common representation is the pip URL format (`VCS Support `_), other examples are provided in the :ref:`Version specifier specification `. From 66c29296dfe8a0276b05f733eb0bd0d2d8c3e8c4 Mon Sep 17 00:00:00 2001 From: konsti Date: Sat, 2 Mar 2024 16:18:34 +0100 Subject: [PATCH 011/121] Update source/specifications/direct-url-data-structure.rst Co-authored-by: chrysle --- source/specifications/direct-url-data-structure.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/specifications/direct-url-data-structure.rst b/source/specifications/direct-url-data-structure.rst index 9afe5acd5..d73eea4ae 100644 --- a/source/specifications/direct-url-data-structure.rst +++ b/source/specifications/direct-url-data-structure.rst @@ -11,7 +11,7 @@ URLs to python projects and distribution artifacts such as VCS source trees, loc source trees, source distributions and wheels. At time of writing, it is not formally specified how to merge the parts of this -data structure into single URL that can be passed to tools. A common representation is the +data structure into a single URL that can be passed to tools. A common representation is the pip URL format (`VCS Support `_), other examples are provided in the :ref:`Version specifier specification `. From 0f441406f49b28bd8eca6c6258ab743b75f0d342 Mon Sep 17 00:00:00 2001 From: konsti Date: Sat, 2 Mar 2024 16:18:41 +0100 Subject: [PATCH 012/121] typo Co-authored-by: chrysle --- source/specifications/direct-url-data-structure.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/specifications/direct-url-data-structure.rst b/source/specifications/direct-url-data-structure.rst index d73eea4ae..2dbcdae91 100644 --- a/source/specifications/direct-url-data-structure.rst +++ b/source/specifications/direct-url-data-structure.rst @@ -27,7 +27,7 @@ type ``string``. Its content must be a valid URL according to the Depending on what ``url`` refers to, the second field MUST be one of ``vcs_info`` (if ``url`` is a VCS reference), ``archive_info`` (if -``url`` is a source archives or a wheel), or ``dir_info`` (if ``url`` is a +``url`` is a source archive or a wheel), or ``dir_info`` (if ``url`` is a local directory). These info fields have a (possibly empty) subdictionary as value, with the possible keys defined below. From 35dbd1efa5b46fba1971bcdf01f4ef24351acf2b Mon Sep 17 00:00:00 2001 From: Guen Prawiroatmodjo Date: Wed, 6 Mar 2024 12:33:08 -0800 Subject: [PATCH 013/121] Update publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst --- ...tribution-releases-using-github-actions-ci-cd-workflows.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst b/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst index 99ac3a9e2..10c45b219 100644 --- a/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst +++ b/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst @@ -169,7 +169,8 @@ Firstly, it uses the `sigstore/gh-action-sigstore-python GitHub Action`_ to sign the distribution packages. In the next step, an empty GitHub Release from the current tag is created using the ``gh`` CLI. Note this step can be further customised. See the `gh release documentation `_ -as a reference. +as a reference. To enable writing to GitHub Release you may need to manage your ``GITHUB_TOKEN`` +permissions, see the `GitHub documentation `_. Finally, the signed distributions are uploaded to the GitHub Release. From fa39abdfb542f8f19d40a35476d0b5d66c600071 Mon Sep 17 00:00:00 2001 From: Guen Prawiroatmodjo Date: Wed, 6 Mar 2024 15:00:51 -0800 Subject: [PATCH 014/121] Add GITHUB_TOKEN instructions to tip admonition --- ...ution-releases-using-github-actions-ci-cd-workflows.rst | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst b/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst index 10c45b219..1f3d66ac8 100644 --- a/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst +++ b/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst @@ -169,8 +169,11 @@ Firstly, it uses the `sigstore/gh-action-sigstore-python GitHub Action`_ to sign the distribution packages. In the next step, an empty GitHub Release from the current tag is created using the ``gh`` CLI. Note this step can be further customised. See the `gh release documentation `_ -as a reference. To enable writing to GitHub Release you may need to manage your ``GITHUB_TOKEN`` -permissions, see the `GitHub documentation `_. +as a reference. + +.. tip:: + + You may need to manage your ``GITHUB_TOKEN`` permissions to enable creating the GitHub Release. See the `GitHub documentation `_ for instructions. Specifically, the token needs `content.write` permissions. Finally, the signed distributions are uploaded to the GitHub Release. From ac0a64aabb95135525284a5f90b62055c4a74c2b Mon Sep 17 00:00:00 2001 From: Guen Prawiroatmodjo Date: Wed, 6 Mar 2024 15:05:14 -0800 Subject: [PATCH 015/121] rst ``code`` is two backticks --- ...stribution-releases-using-github-actions-ci-cd-workflows.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst b/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst index 1f3d66ac8..6456dd182 100644 --- a/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst +++ b/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst @@ -173,7 +173,7 @@ as a reference. .. tip:: - You may need to manage your ``GITHUB_TOKEN`` permissions to enable creating the GitHub Release. See the `GitHub documentation `_ for instructions. Specifically, the token needs `content.write` permissions. + You may need to manage your ``GITHUB_TOKEN`` permissions to enable creating the GitHub Release. See the `GitHub documentation `_ for instructions. Specifically, the token needs ``content.write`` permissions. Finally, the signed distributions are uploaded to the GitHub Release. From c766f090ee923b739fb0b29d004f90e418268f53 Mon Sep 17 00:00:00 2001 From: Guen Prawiroatmodjo Date: Wed, 6 Mar 2024 15:07:38 -0800 Subject: [PATCH 016/121] Fix typo: it should be ``contents: write`` --- ...stribution-releases-using-github-actions-ci-cd-workflows.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst b/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst index 6456dd182..006b39f8b 100644 --- a/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst +++ b/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst @@ -173,7 +173,7 @@ as a reference. .. tip:: - You may need to manage your ``GITHUB_TOKEN`` permissions to enable creating the GitHub Release. See the `GitHub documentation `_ for instructions. Specifically, the token needs ``content.write`` permissions. + You may need to manage your ``GITHUB_TOKEN`` permissions to enable creating the GitHub Release. See the `GitHub documentation `_ for instructions. Specifically, the token needs ``contents: write`` permissions. Finally, the signed distributions are uploaded to the GitHub Release. From 643b211ea2795937d208fdb055b203a8c0e1aa1e Mon Sep 17 00:00:00 2001 From: Guen Prawiroatmodjo Date: Wed, 6 Mar 2024 22:48:27 -0800 Subject: [PATCH 017/121] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Sviatoslav Sydorenko (Святослав Сидоренко) --- ...bution-releases-using-github-actions-ci-cd-workflows.rst | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst b/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst index 006b39f8b..049fba15c 100644 --- a/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst +++ b/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst @@ -173,7 +173,11 @@ as a reference. .. tip:: - You may need to manage your ``GITHUB_TOKEN`` permissions to enable creating the GitHub Release. See the `GitHub documentation `_ for instructions. Specifically, the token needs ``contents: write`` permissions. + You may need to manage your ``GITHUB_TOKEN`` permissions to + enable creating the GitHub Release. See the `GitHub + documentation `_ + for instructions. Specifically, the token needs the + ``contents: write`` permission. Finally, the signed distributions are uploaded to the GitHub Release. From d68a810030f1daffad6387142f1cf01a4a5a112b Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Mon, 19 Feb 2024 19:35:39 +0000 Subject: [PATCH 018/121] [pre-commit.ci] pre-commit autoupdate MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit updates: - [github.com/astral-sh/ruff-pre-commit: v0.2.1 → v0.2.2](https://github.com/astral-sh/ruff-pre-commit/compare/v0.2.1...v0.2.2) --- .pre-commit-config.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 3c24cfc46..af1c55010 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -34,7 +34,7 @@ repos: - id: rst-inline-touching-normal - repo: https://github.com/astral-sh/ruff-pre-commit - rev: v0.2.1 + rev: v0.2.2 hooks: - id: ruff - id: ruff-format From a0bdc2f1eb5e9dd561c49714e5103947464cbb52 Mon Sep 17 00:00:00 2001 From: Brad Campbell Date: Tue, 12 Mar 2024 14:43:37 -0400 Subject: [PATCH 019/121] guides: stand-alone-tools: update in 2024 The `cowsay` package now requires a `-t` argument. I also noticed the output from pipx has changed a bit over time, so I updated the output to match the current format. --- ...talling-stand-alone-command-line-tools.rst | 23 +++++++++++-------- 1 file changed, 13 insertions(+), 10 deletions(-) diff --git a/source/guides/installing-stand-alone-command-line-tools.rst b/source/guides/installing-stand-alone-command-line-tools.rst index ecc44a487..8578a3b28 100644 --- a/source/guides/installing-stand-alone-command-line-tools.rst +++ b/source/guides/installing-stand-alone-command-line-tools.rst @@ -54,11 +54,11 @@ For example: .. code-block:: console $ pipx install cowsay - installed package cowsay 2.0, Python 3.6.2+ - These binaries are now globally available + installed package cowsay 6.1, installed using Python 3.12.2 + These apps are now globally available - cowsay done! ✨ 🌟 ✨ - $ cowsay moo + $ cowsay -t moo ___ < moo > === @@ -77,18 +77,21 @@ available, use ``pipx list``: .. code-block:: console $ pipx list - venvs are in /Users/user/.local/pipx/venvs - symlinks to binaries are in /Users/user/.local/bin - package black 18.9b0, Python 3.6.2+ + venvs are in /Users/user/Library/Application Support/pipx/venvs + apps are exposed on your $PATH at /Users/user/.local/bin + manual pages are exposed at /Users/user/.local/share/man + package black 24.2.0, installed using Python 3.12.2 - black - blackd - package cowsay 2.0, Python 3.6.2+ + package cowsay 6.1, installed using Python 3.12.2 - cowsay - package mypy 0.660, Python 3.6.2+ + package mypy 1.9.0, installed using Python 3.12.2 - dmypy - mypy + - mypyc - stubgen - package nox 2018.10.17, Python 3.6.2+ + - stubtest + package nox 2024.3.2, installed using Python 3.12.2 - nox - tox-to-nox @@ -120,7 +123,7 @@ in a temporary, ephemeral environment. For example: .. code-block:: bash - pipx run cowsay moooo + pipx run cowsay -t moooo To see the full list of commands pipx offers, run: From 2572190c9841373b8763af9948262862ae1a090a Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Tue, 12 Mar 2024 22:23:06 +0000 Subject: [PATCH 020/121] [pre-commit.ci] pre-commit autoupdate MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit updates: - [github.com/astral-sh/ruff-pre-commit: v0.2.2 → v0.3.2](https://github.com/astral-sh/ruff-pre-commit/compare/v0.2.2...v0.3.2) --- .pre-commit-config.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index af1c55010..7e6d4359a 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -34,7 +34,7 @@ repos: - id: rst-inline-touching-normal - repo: https://github.com/astral-sh/ruff-pre-commit - rev: v0.2.2 + rev: v0.3.2 hooks: - id: ruff - id: ruff-format From 0b4a494425ba208a07cb2f8acfd3f0ea107d20d0 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Mon, 8 Apr 2024 19:55:56 +0000 Subject: [PATCH 021/121] [pre-commit.ci] pre-commit autoupdate MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit updates: - [github.com/pre-commit/pre-commit-hooks: v4.5.0 → v4.6.0](https://github.com/pre-commit/pre-commit-hooks/compare/v4.5.0...v4.6.0) - [github.com/astral-sh/ruff-pre-commit: v0.3.2 → v0.3.5](https://github.com/astral-sh/ruff-pre-commit/compare/v0.3.2...v0.3.5) --- .pre-commit-config.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 7e6d4359a..d5b2fe281 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -1,6 +1,6 @@ repos: - repo: https://github.com/pre-commit/pre-commit-hooks - rev: v4.5.0 + rev: v4.6.0 hooks: - id: check-added-large-files - id: check-case-conflict @@ -34,7 +34,7 @@ repos: - id: rst-inline-touching-normal - repo: https://github.com/astral-sh/ruff-pre-commit - rev: v0.3.2 + rev: v0.3.5 hooks: - id: ruff - id: ruff-format From 88449eb3c36f9a834b041fd08cf0052dccaf9313 Mon Sep 17 00:00:00 2001 From: Clemens Brunner Date: Thu, 11 Apr 2024 10:32:48 +0200 Subject: [PATCH 022/121] Update packages installed in venv --- source/tutorials/installing-packages.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/tutorials/installing-packages.rst b/source/tutorials/installing-packages.rst index 0e80642ae..817148d06 100644 --- a/source/tutorials/installing-packages.rst +++ b/source/tutorials/installing-packages.rst @@ -224,8 +224,8 @@ environments. Currently, there are two common tools for creating Python virtual environments: * :doc:`venv ` is available by default in Python 3.3 and later, and installs - :ref:`pip` and :ref:`setuptools` into created virtual environments in - Python 3.4 and later. + :ref:`pip` into created virtual environments in Python 3.4 and later + (Python versions prior to 3.12 also installed :ref:`setuptools`). * :ref:`virtualenv` needs to be installed separately, but supports Python 2.7+ and Python 3.3+, and :ref:`pip`, :ref:`setuptools` and :ref:`wheel` are always installed into created virtual environments by default (regardless of From c5a697f68873a904373353173696715b67db9e1d Mon Sep 17 00:00:00 2001 From: Ofek Lev Date: Fri, 12 Apr 2024 11:23:07 -0400 Subject: [PATCH 023/121] Update language for the direct URL data structure --- source/specifications/direct-url-data-structure.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/source/specifications/direct-url-data-structure.rst b/source/specifications/direct-url-data-structure.rst index 2dbcdae91..231198ee8 100644 --- a/source/specifications/direct-url-data-structure.rst +++ b/source/specifications/direct-url-data-structure.rst @@ -59,7 +59,9 @@ as a dictionary with the following keys: so an installer can hand it off without transformation to a checkout/download command of the VCS. - A ``requested_revision`` key (type ``string``) MAY be present naming a - branch/tag/ref/commit/revision/etc (in a format compatible with the VCS). + branch/tag/ref/commit/revision/etc (in a format compatible with the VCS). This field + MUST match the revision requested by the user and MUST NOT exist when the user did + not select a specific revision. - A ``commit_id`` key (type ``string``) MUST be present, containing the exact commit/revision number that was/is to be installed. If the VCS supports commit-hash From 547a95ab3e34416441d414ee3cca8111737e0682 Mon Sep 17 00:00:00 2001 From: Henry Schreiner Date: Mon, 15 Apr 2024 23:29:19 -0400 Subject: [PATCH 024/121] pyproject.toml: specify description is one line --- source/specifications/pyproject-toml.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/source/specifications/pyproject-toml.rst b/source/specifications/pyproject-toml.rst index 1580b3772..efa562a73 100644 --- a/source/specifications/pyproject-toml.rst +++ b/source/specifications/pyproject-toml.rst @@ -180,7 +180,8 @@ Users SHOULD prefer to specify already-normalized versions. - Corresponding :ref:`core metadata ` field: :ref:`Summary ` -The summary description of the project. +The summary description of the project in one line. Tools MAY error +if this includes multiple lines. ``readme`` From cb6808acf09642401e5a06b3f56516b2a05d3fa2 Mon Sep 17 00:00:00 2001 From: sam rodriguez Date: Tue, 30 Apr 2024 12:17:34 +0200 Subject: [PATCH 025/121] Update glossary.rst fix seeming typo and add link to the correct term --- source/glossary.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/glossary.rst b/source/glossary.rst index 218c21168..bff0b0426 100644 --- a/source/glossary.rst +++ b/source/glossary.rst @@ -16,7 +16,7 @@ Glossary A library that takes a source tree or :term:`source distribution ` - and builds a source distribution or :term:`wheel ` from it. + and builds a :term:`built distribution ` or :term:`wheel ` from it. The build is delegated to the backend by a :term:`frontend `. All backends offer a standardized interface. From 05f231be5237e616cc861312c33974a318e11491 Mon Sep 17 00:00:00 2001 From: sam rodriguez Date: Thu, 2 May 2024 12:26:10 +0200 Subject: [PATCH 026/121] Clearer phrasing --- source/glossary.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/source/glossary.rst b/source/glossary.rst index bff0b0426..297398255 100644 --- a/source/glossary.rst +++ b/source/glossary.rst @@ -14,9 +14,8 @@ Glossary Build Backend - A library that takes a source tree or - :term:`source distribution ` - and builds a :term:`built distribution ` or :term:`wheel ` from it. + A library that takes a source tree + and builds a :term:`source distribution ` or :term:`built distribution ` from it. The build is delegated to the backend by a :term:`frontend `. All backends offer a standardized interface. From d8f425f264409951ac037b2e0500624249c6f71c Mon Sep 17 00:00:00 2001 From: wyattscarpenter Date: Fri, 3 May 2024 00:02:42 -0400 Subject: [PATCH 027/121] Update packaging-projects.rst: rephrase first explanation of __init.py__ --- source/tutorials/packaging-projects.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/source/tutorials/packaging-projects.rst b/source/tutorials/packaging-projects.rst index 761b2748f..095abd19f 100644 --- a/source/tutorials/packaging-projects.rst +++ b/source/tutorials/packaging-projects.rst @@ -54,8 +54,10 @@ Create the following file structure locally: The directory containing the Python files should match the project name. This simplifies the configuration and is more obvious to users who install the package. -:file:`__init__.py` is recommended to import the directory as a regular package, -even if as is our case for this tutorial that file is empty [#namespace-packages]_. +Creating the file :file:`__init__.py` is recommended because the existence of a +:file:`__init__.py` file allows users to import the directory as a regular package, +even if (as is the case for this tutorial) :file:`__init__.py` is empty. +[#namespace-packages]_ :file:`example.py` is an example of a module within the package that could contain the logic (functions, classes, constants, etc.) of your package. From 9808d5d06c77d0a25b0c86433212116d34d8ae8f Mon Sep 17 00:00:00 2001 From: wyattscarpenter Date: Fri, 3 May 2024 00:06:26 -0400 Subject: [PATCH 028/121] Update packaging-projects.rst: you know, I reckon people say "a*n* __init__.py file" --- source/tutorials/packaging-projects.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/tutorials/packaging-projects.rst b/source/tutorials/packaging-projects.rst index 095abd19f..4c205e28f 100644 --- a/source/tutorials/packaging-projects.rst +++ b/source/tutorials/packaging-projects.rst @@ -54,9 +54,9 @@ Create the following file structure locally: The directory containing the Python files should match the project name. This simplifies the configuration and is more obvious to users who install the package. -Creating the file :file:`__init__.py` is recommended because the existence of a +Creating the file :file:`__init__.py` is recommended because the existence of an :file:`__init__.py` file allows users to import the directory as a regular package, -even if (as is the case for this tutorial) :file:`__init__.py` is empty. +even if (as is the case in this tutorial) :file:`__init__.py` is empty. [#namespace-packages]_ :file:`example.py` is an example of a module within the package that could From 3f2c72d68e5aa4ab4785831531c590adf6d2006d Mon Sep 17 00:00:00 2001 From: William Woodruff Date: Sun, 5 May 2024 13:43:45 -0400 Subject: [PATCH 029/121] publish-to-test-pypi: bump action versions --- .../github-actions-ci-cd-sample/publish-to-test-pypi.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml b/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml index 72a3eb7b2..3bd06cccc 100644 --- a/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml +++ b/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml @@ -10,7 +10,7 @@ jobs: steps: - uses: actions/checkout@v4 - name: Set up Python - uses: actions/setup-python@v4 + uses: actions/setup-python@v5 with: python-version: "3.x" - name: Install pypa/build @@ -68,7 +68,7 @@ jobs: name: python-package-distributions path: dist/ - name: Sign the dists with Sigstore - uses: sigstore/gh-action-sigstore-python@v1.2.3 + uses: sigstore/gh-action-sigstore-python@v2.1.1 with: inputs: >- ./dist/*.tar.gz From 167ef2d7345c420e0b48602bdc3e3d3b682b31e7 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Mon, 6 May 2024 19:42:56 +0000 Subject: [PATCH 030/121] [pre-commit.ci] pre-commit autoupdate MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit updates: - [github.com/astral-sh/ruff-pre-commit: v0.3.5 → v0.4.3](https://github.com/astral-sh/ruff-pre-commit/compare/v0.3.5...v0.4.3) --- .pre-commit-config.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index d5b2fe281..b1cc54c6e 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -34,7 +34,7 @@ repos: - id: rst-inline-touching-normal - repo: https://github.com/astral-sh/ruff-pre-commit - rev: v0.3.5 + rev: v0.4.3 hooks: - id: ruff - id: ruff-format From 9ddfba16ad4954e17efdbf2e55a63f66f12c6010 Mon Sep 17 00:00:00 2001 From: Karolina Surma Date: Mon, 6 May 2024 16:20:17 +0200 Subject: [PATCH 031/121] Add glossary definitions of packaging and metadata terms The definitions were originally included in PEP 639, refining and extending the existing glossary terms. Having the unified vocabulary in place is essential to accurately describe the complex Python packaging landscape. Co-Authored-By: C.A.M. Gerlach --- source/glossary.rst | 109 +++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 107 insertions(+), 2 deletions(-) diff --git a/source/glossary.rst b/source/glossary.rst index 218c21168..e2e7b6334 100644 --- a/source/glossary.rst +++ b/source/glossary.rst @@ -54,6 +54,39 @@ Glossary Python files). See :ref:`package-formats` for more information. + Built Metadata + + The concrete form :term:`Core Metadata` takes + when included inside an installed :term:`Project` (``METADATA`` file) + or a :term:`Distribution Archive` + (``PKG-INFO`` in a + :term:`Sdist ` + and ``METADATA`` in a :term:`Wheel`). + + + Core Metadata + + The :ref:`specification ` + and the set of :term:`Core Metadata Field`\s it defines + that describe key static attributes of + a :term:`Distribution Package` or :term:`Installed Project`. + + + Core Metadata Field + + A single key-value pair + (or sequence of such with the same name, for multiple-use fields) + defined in the :term:`Core Metadata` spec + and stored in the :term:`Built Metadata`. + Notably, distinct from a :term:`Pyproject Metadata Key`. + + + Distribution Archive + + The physical distribution artifact (i.e. a file on disk) + for a :term:`Distribution Package`. + + Distribution Package A versioned archive file that contains Python :term:`packages ` is located. + + + Project Source Tree + + The on-disk format of a :term:`Project` used for development, + containing its raw source code before being packaged + into a + :term:`Source Distribution ` + or :term:`Built Distribution`. + + + Project Source Metadata + + Metadata defined by the package author + in a :term:`Project`'s :term:`source tree `, + to be transformed into :term:`Core Metadata field`\s + in the :term:`Built Metadata` + by the project's build backend. + Can be written as :term:`Pyproject Metadata`, + or in a tool-specific format + (under the ``[tool]`` table in ``pyproject.toml``, + or in a tool's own configuration file). + + Pure Module A :term:`Module` written in Python and contained in a single ``.py`` file (and possibly associated ``.pyc`` and/or ``.pyo`` files). + Pyproject Metadata + + The :term:`Project Source Metadata` format + defined by the :ref:`declaring-project-metadata` specification + and originally introduced in :pep:`621`, + stored as :term:`Pyproject Metadata Key`\s + under the ``[project]`` table of a :term:`pyproject.toml` file. + Notably, *not* a tool-specific source metadata format + under the ``[tool]`` table in ``pyproject.toml``. + + + Pyproject Metadata Key + + A top-level TOML key in the ``[project]`` table in ``pyproject.toml``; + part of the :term:`Pyproject Metadata`. + Notably, distinct from a :term:`Core Metadata Field`. + + + Pyproject Metadata Subkey + + A second-level TOML key under a table-valued + :term:`Pyproject Metadata Key`. + + Python Packaging Authority (PyPA) PyPA is a working group that maintains many of the relevant @@ -236,7 +329,7 @@ Glossary Source Distribution (or "sdist") - A :term:`distribution ` format (usually generated + A :term:`distribution ` format (usually generated using ``python -m build --sdist``) that provides metadata and the essential source files needed for installing by a tool like :ref:`pip`, or for generating a :term:`Built Distribution`. See :ref:`package-formats` @@ -264,10 +357,22 @@ Glossary wide. For more information, see the section on :ref:`Creating and using Virtual Environments`. + + Wheel Format Wheel - The standard :term:`Built Distribution` format. + The standard :term:`Built Distribution` format + originally introduced in :pep:`427` + and defined by the :ref:`binary-distribution-format` specification. See :ref:`package-formats` for more information. + Not to be confused with its reference implementation, + the :term:`Wheel Project`. + + + Wheel Project + + The PyPA reference implementation of the :term:`Wheel Format`. + Working Set From 25426b36dd702c43e4c6f78b75cc42d3c740e6ec Mon Sep 17 00:00:00 2001 From: Karolina Surma <33810531+befeleme@users.noreply.github.com> Date: Tue, 7 May 2024 09:57:20 +0200 Subject: [PATCH 032/121] Apply suggestions from code review Co-authored-by: chrysle <96722107+chrysle@users.noreply.github.com> --- source/glossary.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/glossary.rst b/source/glossary.rst index e2e7b6334..f6675fef9 100644 --- a/source/glossary.rst +++ b/source/glossary.rst @@ -211,7 +211,7 @@ Glossary in a :term:`Project`'s :term:`source tree `, to be transformed into :term:`Core Metadata field`\s in the :term:`Built Metadata` - by the project's build backend. + by the project's :term:`build backend `. Can be written as :term:`Pyproject Metadata`, or in a tool-specific format (under the ``[tool]`` table in ``pyproject.toml``, @@ -371,7 +371,7 @@ Glossary Wheel Project - The PyPA reference implementation of the :term:`Wheel Format`. + The PyPA reference implementation of the :term:`Wheel Format`; see :ref:`wheel`. Working Set From 706b0f157bab3935d53ec9a7700985e09c2563d8 Mon Sep 17 00:00:00 2001 From: Ofek Lev Date: Wed, 8 May 2024 09:39:04 -0400 Subject: [PATCH 033/121] Add reference for inline script metadata spec --- source/specifications/inline-script-metadata.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/source/specifications/inline-script-metadata.rst b/source/specifications/inline-script-metadata.rst index 352614e81..f40b9ac4a 100644 --- a/source/specifications/inline-script-metadata.rst +++ b/source/specifications/inline-script-metadata.rst @@ -1,3 +1,5 @@ +.. _inline-script-metadata: + ====================== Inline script metadata ====================== From abf27b61cd8ccad51a9c4f04609a5573d54c1f35 Mon Sep 17 00:00:00 2001 From: sam rodriguez Date: Mon, 13 May 2024 04:40:41 +0200 Subject: [PATCH 034/121] Update source/glossary.rst Co-authored-by: chrysle <96722107+chrysle@users.noreply.github.com> --- source/glossary.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/source/glossary.rst b/source/glossary.rst index 297398255..9d53e40eb 100644 --- a/source/glossary.rst +++ b/source/glossary.rst @@ -15,7 +15,8 @@ Glossary Build Backend A library that takes a source tree - and builds a :term:`source distribution ` or :term:`built distribution ` from it. + and builds a :term:`source distribution ` or + :term:`built distribution ` from it. The build is delegated to the backend by a :term:`frontend `. All backends offer a standardized interface. From 627ed17bb001aeda664ee6e82493703b99706b7b Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Mon, 13 May 2024 02:40:46 +0000 Subject: [PATCH 035/121] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- source/glossary.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/glossary.rst b/source/glossary.rst index 9d53e40eb..58b096f46 100644 --- a/source/glossary.rst +++ b/source/glossary.rst @@ -15,7 +15,7 @@ Glossary Build Backend A library that takes a source tree - and builds a :term:`source distribution ` or + and builds a :term:`source distribution ` or :term:`built distribution ` from it. The build is delegated to the backend by a :term:`frontend `. From 01a03ce0c4ddb6a503c808bf4202f763131adba7 Mon Sep 17 00:00:00 2001 From: Geoffrey Thomas Date: Wed, 22 May 2024 16:40:15 -0400 Subject: [PATCH 036/121] binary-distribution-format: Update a mention of distutils --- source/specifications/binary-distribution-format.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/specifications/binary-distribution-format.rst b/source/specifications/binary-distribution-format.rst index e2f65411b..211019f85 100644 --- a/source/specifications/binary-distribution-format.rst +++ b/source/specifications/binary-distribution-format.rst @@ -43,8 +43,8 @@ Wheel installation notionally consists of two phases: destination path. Each subdirectory of ``distribution-1.0.data/`` is a key into a dict of destination directories, such as ``distribution-1.0.data/(purelib|platlib|headers|scripts|data)``. - The initially supported paths are taken from - ``distutils.command.install``. + These subdirectories are `installation paths defined by sysconfig + `_. c. If applicable, update scripts starting with ``#!python`` to point to the correct interpreter. d. Update ``distribution-1.0.dist-info/RECORD`` with the installed From 5901ab5d4489328e1be14e62b2b0f3bda17860ae Mon Sep 17 00:00:00 2001 From: Victor Blomqvist Date: Sun, 26 May 2024 21:16:25 +0200 Subject: [PATCH 037/121] Create considerations_for_binary_wheels.rst --- .../discussions/considerations_for_binary_wheels.rst | 12 ++++++++++++ 1 file changed, 12 insertions(+) create mode 100644 source/discussions/considerations_for_binary_wheels.rst diff --git a/source/discussions/considerations_for_binary_wheels.rst b/source/discussions/considerations_for_binary_wheels.rst new file mode 100644 index 000000000..f5e1e20f8 --- /dev/null +++ b/source/discussions/considerations_for_binary_wheels.rst @@ -0,0 +1,12 @@ +================================ +Considerations for binary wheels +================================ + +Python packages with native code have a set of unique challenges not present +in pure packages. The more complex the native code, the more complex the +packaging can become. Issues arrise around topics such as non-Python compiled +dependencies ("native dependencies"), the importance of the ABI (Application +Binary Interface) of native code, dependency on SIMD code and cross +compilation. In depth dicussion of these and many more topics and issues around + native packaging is available at + `pypackaging-native`. From 413893d0c1af1e33707232d9f0b48e29b421bac4 Mon Sep 17 00:00:00 2001 From: Victor Blomqvist Date: Sun, 26 May 2024 21:17:47 +0200 Subject: [PATCH 038/121] And binary wheel discussion to index --- source/discussions/index.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/source/discussions/index.rst b/source/discussions/index.rst index d262bcff2..02ceba602 100644 --- a/source/discussions/index.rst +++ b/source/discussions/index.rst @@ -16,3 +16,4 @@ specific topic. If you're just trying to get stuff done, see package-formats src-layout-vs-flat-layout setup-py-deprecated + considerations_for_binary_wheels From a548da992ffd394699873f9a9359dc22df61b9ab Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Sun, 26 May 2024 19:19:46 +0000 Subject: [PATCH 039/121] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- .../discussions/considerations_for_binary_wheels.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/source/discussions/considerations_for_binary_wheels.rst b/source/discussions/considerations_for_binary_wheels.rst index f5e1e20f8..861e7794e 100644 --- a/source/discussions/considerations_for_binary_wheels.rst +++ b/source/discussions/considerations_for_binary_wheels.rst @@ -2,11 +2,11 @@ Considerations for binary wheels ================================ -Python packages with native code have a set of unique challenges not present -in pure packages. The more complex the native code, the more complex the -packaging can become. Issues arrise around topics such as non-Python compiled -dependencies ("native dependencies"), the importance of the ABI (Application -Binary Interface) of native code, dependency on SIMD code and cross +Python packages with native code have a set of unique challenges not present +in pure packages. The more complex the native code, the more complex the +packaging can become. Issues arrise around topics such as non-Python compiled +dependencies ("native dependencies"), the importance of the ABI (Application +Binary Interface) of native code, dependency on SIMD code and cross compilation. In depth dicussion of these and many more topics and issues around - native packaging is available at + native packaging is available at `pypackaging-native`. From 380b8d19be61104df65dac7c547d180ab056ef58 Mon Sep 17 00:00:00 2001 From: Victor Blomqvist Date: Sun, 26 May 2024 21:27:21 +0200 Subject: [PATCH 040/121] Fix link in considerations_for_binary_wheels.rst --- source/discussions/considerations_for_binary_wheels.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/discussions/considerations_for_binary_wheels.rst b/source/discussions/considerations_for_binary_wheels.rst index 861e7794e..4158de1ea 100644 --- a/source/discussions/considerations_for_binary_wheels.rst +++ b/source/discussions/considerations_for_binary_wheels.rst @@ -9,4 +9,4 @@ dependencies ("native dependencies"), the importance of the ABI (Application Binary Interface) of native code, dependency on SIMD code and cross compilation. In depth dicussion of these and many more topics and issues around native packaging is available at - `pypackaging-native`. + `pypackaging-native`_. From 203c79d9527f66ae90cb385929f537616c845223 Mon Sep 17 00:00:00 2001 From: Victor Blomqvist Date: Mon, 27 May 2024 21:29:08 +0200 Subject: [PATCH 041/121] Update source/discussions/considerations_for_binary_wheels.rst Co-authored-by: chrysle <96722107+chrysle@users.noreply.github.com> --- source/discussions/considerations_for_binary_wheels.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/discussions/considerations_for_binary_wheels.rst b/source/discussions/considerations_for_binary_wheels.rst index 4158de1ea..49d89e394 100644 --- a/source/discussions/considerations_for_binary_wheels.rst +++ b/source/discussions/considerations_for_binary_wheels.rst @@ -7,6 +7,6 @@ in pure packages. The more complex the native code, the more complex the packaging can become. Issues arrise around topics such as non-Python compiled dependencies ("native dependencies"), the importance of the ABI (Application Binary Interface) of native code, dependency on SIMD code and cross -compilation. In depth dicussion of these and many more topics and issues around +compilation. In depth discussion of these and many more topics and issues around native packaging is available at `pypackaging-native`_. From 639ef8a21f07da1bfc4010da2247a3412bf25d04 Mon Sep 17 00:00:00 2001 From: Victor Blomqvist Date: Mon, 27 May 2024 21:29:20 +0200 Subject: [PATCH 042/121] Update source/discussions/considerations_for_binary_wheels.rst Co-authored-by: chrysle <96722107+chrysle@users.noreply.github.com> --- source/discussions/considerations_for_binary_wheels.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/source/discussions/considerations_for_binary_wheels.rst b/source/discussions/considerations_for_binary_wheels.rst index 49d89e394..cfca706c7 100644 --- a/source/discussions/considerations_for_binary_wheels.rst +++ b/source/discussions/considerations_for_binary_wheels.rst @@ -8,5 +8,4 @@ packaging can become. Issues arrise around topics such as non-Python compiled dependencies ("native dependencies"), the importance of the ABI (Application Binary Interface) of native code, dependency on SIMD code and cross compilation. In depth discussion of these and many more topics and issues around - native packaging is available at - `pypackaging-native`_. +native packaging is available at `pypackaging-native `_. From 5a89e74e83b92cfaa455dbedf87869ed4641ada9 Mon Sep 17 00:00:00 2001 From: Victor Blomqvist Date: Sat, 1 Jun 2024 21:35:50 +0200 Subject: [PATCH 043/121] Added link to pypackaging-native on packaging binary extensions page --- .../discussions/considerations_for_binary_wheels.rst | 11 ----------- source/discussions/index.rst | 1 - source/guides/packaging-binary-extensions.rst | 12 ++++++++++++ 3 files changed, 12 insertions(+), 12 deletions(-) delete mode 100644 source/discussions/considerations_for_binary_wheels.rst diff --git a/source/discussions/considerations_for_binary_wheels.rst b/source/discussions/considerations_for_binary_wheels.rst deleted file mode 100644 index cfca706c7..000000000 --- a/source/discussions/considerations_for_binary_wheels.rst +++ /dev/null @@ -1,11 +0,0 @@ -================================ -Considerations for binary wheels -================================ - -Python packages with native code have a set of unique challenges not present -in pure packages. The more complex the native code, the more complex the -packaging can become. Issues arrise around topics such as non-Python compiled -dependencies ("native dependencies"), the importance of the ABI (Application -Binary Interface) of native code, dependency on SIMD code and cross -compilation. In depth discussion of these and many more topics and issues around -native packaging is available at `pypackaging-native `_. diff --git a/source/discussions/index.rst b/source/discussions/index.rst index 02ceba602..d262bcff2 100644 --- a/source/discussions/index.rst +++ b/source/discussions/index.rst @@ -16,4 +16,3 @@ specific topic. If you're just trying to get stuff done, see package-formats src-layout-vs-flat-layout setup-py-deprecated - considerations_for_binary_wheels diff --git a/source/guides/packaging-binary-extensions.rst b/source/guides/packaging-binary-extensions.rst index 589ed89c8..b664d68a4 100644 --- a/source/guides/packaging-binary-extensions.rst +++ b/source/guides/packaging-binary-extensions.rst @@ -403,3 +403,15 @@ a Debian system, see the following articles: * `What are (c)python extension modules? `_ * `Releasing the gil `_ * `Writing cpython extension modules using C++ `_ + +Additional considerations for binary wheels +------------------------------------------- + +The `pypackaging-native `_ website has +additional coverage of packaging Python packages with native code. It aims to +provide an overview of the most important packaging issues for such projects, +with in-depth explanations and references. + +Topics cover for example non-Python compiled dependencies ("native dependencies"), +the importance of the ABI (Application Binary Interface) of native code, +dependency on SIMD code and cross compilation. From fb2192df714ec14879ec2ef7e37050481339512b Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Sat, 1 Jun 2024 19:36:03 +0000 Subject: [PATCH 044/121] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- source/guides/packaging-binary-extensions.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/source/guides/packaging-binary-extensions.rst b/source/guides/packaging-binary-extensions.rst index b664d68a4..ff7298658 100644 --- a/source/guides/packaging-binary-extensions.rst +++ b/source/guides/packaging-binary-extensions.rst @@ -407,11 +407,11 @@ a Debian system, see the following articles: Additional considerations for binary wheels ------------------------------------------- -The `pypackaging-native `_ website has -additional coverage of packaging Python packages with native code. It aims to -provide an overview of the most important packaging issues for such projects, +The `pypackaging-native `_ website has +additional coverage of packaging Python packages with native code. It aims to +provide an overview of the most important packaging issues for such projects, with in-depth explanations and references. -Topics cover for example non-Python compiled dependencies ("native dependencies"), -the importance of the ABI (Application Binary Interface) of native code, -dependency on SIMD code and cross compilation. +Topics cover for example non-Python compiled dependencies ("native dependencies"), +the importance of the ABI (Application Binary Interface) of native code, +dependency on SIMD code and cross compilation. From bd9956a0f90865ce704bb19587ab6c1129bb4c80 Mon Sep 17 00:00:00 2001 From: Victor Blomqvist Date: Sat, 1 Jun 2024 21:57:05 +0200 Subject: [PATCH 045/121] Minor improvement of text --- source/guides/packaging-binary-extensions.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/guides/packaging-binary-extensions.rst b/source/guides/packaging-binary-extensions.rst index b664d68a4..25a897d2e 100644 --- a/source/guides/packaging-binary-extensions.rst +++ b/source/guides/packaging-binary-extensions.rst @@ -412,6 +412,6 @@ additional coverage of packaging Python packages with native code. It aims to provide an overview of the most important packaging issues for such projects, with in-depth explanations and references. -Topics cover for example non-Python compiled dependencies ("native dependencies"), +Example of topics are non-Python compiled dependencies ("native dependencies"), the importance of the ABI (Application Binary Interface) of native code, dependency on SIMD code and cross compilation. From ce3653dc5f0f7376cc240954ecac71528ce2022e Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Sat, 1 Jun 2024 19:58:24 +0000 Subject: [PATCH 046/121] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- source/guides/packaging-binary-extensions.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/guides/packaging-binary-extensions.rst b/source/guides/packaging-binary-extensions.rst index 4a3be2cc3..de8a9d2d6 100644 --- a/source/guides/packaging-binary-extensions.rst +++ b/source/guides/packaging-binary-extensions.rst @@ -412,6 +412,6 @@ additional coverage of packaging Python packages with native code. It aims to provide an overview of the most important packaging issues for such projects, with in-depth explanations and references. -Examples of topics covered are non-Python compiled dependencies ("native -dependencies"), the importance of the ABI (Application Binary Interface) of +Examples of topics covered are non-Python compiled dependencies ("native +dependencies"), the importance of the ABI (Application Binary Interface) of native code, dependency on SIMD code and cross compilation. From f70787f91f8e8eee48365e60b576f0ff70285ab2 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Mon, 17 Jun 2024 19:46:45 +0000 Subject: [PATCH 047/121] [pre-commit.ci] pre-commit autoupdate MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit updates: - [github.com/codespell-project/codespell: v2.2.6 → v2.3.0](https://github.com/codespell-project/codespell/compare/v2.2.6...v2.3.0) - [github.com/astral-sh/ruff-pre-commit: v0.4.3 → v0.4.9](https://github.com/astral-sh/ruff-pre-commit/compare/v0.4.3...v0.4.9) --- .pre-commit-config.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index b1cc54c6e..de44b7a34 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -12,7 +12,7 @@ repos: - id: trailing-whitespace - repo: https://github.com/codespell-project/codespell - rev: v2.2.6 + rev: v2.3.0 hooks: - id: codespell args: ["-L", "ned,ist,oder", "--skip", "*.po"] @@ -34,7 +34,7 @@ repos: - id: rst-inline-touching-normal - repo: https://github.com/astral-sh/ruff-pre-commit - rev: v0.4.3 + rev: v0.4.9 hooks: - id: ruff - id: ruff-format From 82280c02107fa1b3f946de89325f1575cdd8287b Mon Sep 17 00:00:00 2001 From: Alyssa Coghlan Date: Wed, 19 Jun 2024 21:37:22 +1000 Subject: [PATCH 048/121] Add HTML snippet for Plausible metrics Metrics are only collected for the main packaging.python.org documentation deployments. Closes #1561 --- source/conf.py | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/source/conf.py b/source/conf.py index 831f9c9ea..be5f7f149 100644 --- a/source/conf.py +++ b/source/conf.py @@ -1,6 +1,14 @@ # -- Project information --------------------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information +import os + +# Some options are only enabled for the main packaging.python.org deployment builds +RTD_BUILD = bool(os.getenv("READTHEDOCS")) +RTD_PR_BUILD = RTD_BUILD and os.getenv("READTHEDOCS_VERSION_TYPE") == "external" +RTD_URL = os.getenv("READTHEDOCS_CANONICAL_URL") +RTD_CANONICAL_BUILD = RTD_BUILD and not RTD_PR_BUILD and "packaging.python.org" in RTD_URL + project = "Python Packaging User Guide" copyright = "2013–2020, PyPA" @@ -55,6 +63,15 @@ html_favicon = "assets/py.png" html_last_updated_fmt = "" +_metrics_js_files = [ + ("https://plausible.io/js/script.js", {"data-domain": "packaging.python.org"}) +] +html_js_files = [] +if RTD_CANONICAL_BUILD: + # Enable collection of the visitor metrics reported at + # https://plausible.io/packaging.python.org + html_js_files.extend(_metrics_js_files) + # -- Options for HTML help output ------------------------------------------------------ # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-help-output From 5bf53f3eba538f4e8953ca66f36ddb5d3e8963d9 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Wed, 19 Jun 2024 11:37:57 +0000 Subject: [PATCH 049/121] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- source/conf.py | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/source/conf.py b/source/conf.py index be5f7f149..3817ce1d3 100644 --- a/source/conf.py +++ b/source/conf.py @@ -7,7 +7,9 @@ RTD_BUILD = bool(os.getenv("READTHEDOCS")) RTD_PR_BUILD = RTD_BUILD and os.getenv("READTHEDOCS_VERSION_TYPE") == "external" RTD_URL = os.getenv("READTHEDOCS_CANONICAL_URL") -RTD_CANONICAL_BUILD = RTD_BUILD and not RTD_PR_BUILD and "packaging.python.org" in RTD_URL +RTD_CANONICAL_BUILD = ( + RTD_BUILD and not RTD_PR_BUILD and "packaging.python.org" in RTD_URL +) project = "Python Packaging User Guide" From c37de0523ac61c8b2a9608a9e7b2314c88d293b0 Mon Sep 17 00:00:00 2001 From: Alyssa Coghlan Date: Wed, 19 Jun 2024 23:22:36 +1000 Subject: [PATCH 050/121] Defer loading metrics JS --- source/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/conf.py b/source/conf.py index 3817ce1d3..92c1290cc 100644 --- a/source/conf.py +++ b/source/conf.py @@ -66,7 +66,7 @@ html_last_updated_fmt = "" _metrics_js_files = [ - ("https://plausible.io/js/script.js", {"data-domain": "packaging.python.org"}) + ("https://plausible.io/js/script.js", {"data-domain": "packaging.python.org", "defer": "defer"}) ] html_js_files = [] if RTD_CANONICAL_BUILD: From db35d2764a9ad62dedf231b75bab05d1046ead4c Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Wed, 19 Jun 2024 13:22:48 +0000 Subject: [PATCH 051/121] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- source/conf.py | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/source/conf.py b/source/conf.py index 92c1290cc..cd459ffb2 100644 --- a/source/conf.py +++ b/source/conf.py @@ -66,7 +66,10 @@ html_last_updated_fmt = "" _metrics_js_files = [ - ("https://plausible.io/js/script.js", {"data-domain": "packaging.python.org", "defer": "defer"}) + ( + "https://plausible.io/js/script.js", + {"data-domain": "packaging.python.org", "defer": "defer"}, + ) ] html_js_files = [] if RTD_CANONICAL_BUILD: From 4af7da079f97a91fdb8f53155be84258bf1f524d Mon Sep 17 00:00:00 2001 From: Alyssa Coghlan Date: Thu, 20 Jun 2024 02:26:34 +1000 Subject: [PATCH 052/121] Use intersphinx reference --- source/specifications/binary-distribution-format.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/specifications/binary-distribution-format.rst b/source/specifications/binary-distribution-format.rst index 211019f85..692e6f642 100644 --- a/source/specifications/binary-distribution-format.rst +++ b/source/specifications/binary-distribution-format.rst @@ -43,8 +43,8 @@ Wheel installation notionally consists of two phases: destination path. Each subdirectory of ``distribution-1.0.data/`` is a key into a dict of destination directories, such as ``distribution-1.0.data/(purelib|platlib|headers|scripts|data)``. - These subdirectories are `installation paths defined by sysconfig - `_. + These subdirectories are :ref:`installation paths defined by sysconfig + `_. c. If applicable, update scripts starting with ``#!python`` to point to the correct interpreter. d. Update ``distribution-1.0.dist-info/RECORD`` with the installed From 5c432f6a043a0988ab5814f978c6387daf28765a Mon Sep 17 00:00:00 2001 From: Alyssa Coghlan Date: Thu, 20 Jun 2024 02:29:44 +1000 Subject: [PATCH 053/121] Fix ref syntax and target name --- source/specifications/binary-distribution-format.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/specifications/binary-distribution-format.rst b/source/specifications/binary-distribution-format.rst index 692e6f642..8da38357a 100644 --- a/source/specifications/binary-distribution-format.rst +++ b/source/specifications/binary-distribution-format.rst @@ -44,7 +44,7 @@ Wheel installation notionally consists of two phases: is a key into a dict of destination directories, such as ``distribution-1.0.data/(purelib|platlib|headers|scripts|data)``. These subdirectories are :ref:`installation paths defined by sysconfig - `_. + `. c. If applicable, update scripts starting with ``#!python`` to point to the correct interpreter. d. Update ``distribution-1.0.dist-info/RECORD`` with the installed From 77a87f2f6ce25f38e3672d05bd7ee378157de0b5 Mon Sep 17 00:00:00 2001 From: Daniel Schultz Date: Thu, 20 Jun 2024 14:27:13 -0400 Subject: [PATCH 054/121] Fix a typo --- source/guides/writing-pyproject-toml.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/guides/writing-pyproject-toml.rst b/source/guides/writing-pyproject-toml.rst index 938ebbb93..e82bd893d 100644 --- a/source/guides/writing-pyproject-toml.rst +++ b/source/guides/writing-pyproject-toml.rst @@ -340,7 +340,7 @@ or you can write the name of the license: license = {text = "MIT License"} If you are using a standard, well-known license, it is not necessary to use this -field. Instead, you should one of the :ref:`classifiers` starting with ``License +field. Instead, you should use one of the :ref:`classifiers` starting with ``License ::``. (As a general rule, it is a good idea to use a standard, well-known license, both to avoid confusion and because some organizations avoid software whose license is unapproved.) From c0953f394e467281a77afa9c42a41ee7d8bcbdb2 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Mon, 24 Jun 2024 19:47:21 +0000 Subject: [PATCH 055/121] [pre-commit.ci] pre-commit autoupdate MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit updates: - [github.com/astral-sh/ruff-pre-commit: v0.4.9 → v0.4.10](https://github.com/astral-sh/ruff-pre-commit/compare/v0.4.9...v0.4.10) --- .pre-commit-config.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index de44b7a34..c6372ec30 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -34,7 +34,7 @@ repos: - id: rst-inline-touching-normal - repo: https://github.com/astral-sh/ruff-pre-commit - rev: v0.4.9 + rev: v0.4.10 hooks: - id: ruff - id: ruff-format From 3a4616755d742e8c7c29b88e2e686e50ce6452b4 Mon Sep 17 00:00:00 2001 From: Matthew Donoughe Date: Tue, 21 May 2024 09:26:36 -0400 Subject: [PATCH 056/121] allow trailing comma in version_many --- source/specifications/dependency-specifiers.rst | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/source/specifications/dependency-specifiers.rst b/source/specifications/dependency-specifiers.rst index b6c867084..e35d22b14 100644 --- a/source/specifications/dependency-specifiers.rst +++ b/source/specifications/dependency-specifiers.rst @@ -66,7 +66,7 @@ URI is defined in :rfc:`std-66 <3986>`):: version_cmp = wsp* '<' | '<=' | '!=' | '==' | '>=' | '>' | '~=' | '===' version = wsp* ( letterOrDigit | '-' | '_' | '.' | '*' | '+' | '!' )+ version_one = version_cmp version wsp* - version_many = version_one (wsp* ',' version_one)* + version_many = version_one (',' version_one)* (',' wsp*)? versionspec = ( '(' version_many ')' ) | version_many urlspec = '@' wsp* @@ -303,7 +303,7 @@ The complete parsley grammar:: version_cmp = wsp* <'<=' | '<' | '!=' | '==' | '>=' | '>' | '~=' | '==='> version = wsp* <( letterOrDigit | '-' | '_' | '.' | '*' | '+' | '!' )+> version_one = version_cmp:op version:v wsp* -> (op, v) - version_many = version_one:v1 (wsp* ',' version_one)*:v2 -> [v1] + v2 + version_many = version_one:v1 (',' version_one)*:v2 (',' wsp*)? -> [v1] + v2 versionspec = ('(' version_many:v ')' ->v) | version_many urlspec = '@' wsp* marker_op = version_cmp | (wsp* 'in') | (wsp* 'not' wsp+ 'in') @@ -424,6 +424,7 @@ A test program - if the grammar is in a string ``grammar``: "name", "name<=1", "name>=3", + "name>=3,", "name>=3,<2", "name@http://foo.com", "name [fred,bar] @ http://foo.com ; python_version=='2.7'", @@ -481,6 +482,9 @@ History ``'.'.join(platform.python_version_tuple()[:2])``, to accommodate potential future versions of Python with 2-digit major and minor versions (e.g. 3.10). [#future_versions]_ +- May 2024: The definition of ``version_many`` was changed to allow trailing + commas, matching with the behavior of the Python implementation that has been + in use since late 2022. References From e496a99cb2b89fd496b4522e4fea40aa4311bfd7 Mon Sep 17 00:00:00 2001 From: Matthew Donoughe Date: Wed, 26 Jun 2024 08:10:26 -0400 Subject: [PATCH 057/121] update month --- source/specifications/dependency-specifiers.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/specifications/dependency-specifiers.rst b/source/specifications/dependency-specifiers.rst index e35d22b14..d6713f713 100644 --- a/source/specifications/dependency-specifiers.rst +++ b/source/specifications/dependency-specifiers.rst @@ -482,7 +482,7 @@ History ``'.'.join(platform.python_version_tuple()[:2])``, to accommodate potential future versions of Python with 2-digit major and minor versions (e.g. 3.10). [#future_versions]_ -- May 2024: The definition of ``version_many`` was changed to allow trailing +- June 2024: The definition of ``version_many`` was changed to allow trailing commas, matching with the behavior of the Python implementation that has been in use since late 2022. From 8891fa5417c7ed0b60fab07c276d237cce8624ff Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A2muran=20=C4=B0mran?= <73625486+kamurani@users.noreply.github.com> Date: Mon, 29 Jul 2024 15:45:21 +1000 Subject: [PATCH 058/121] fix typo --- source/guides/writing-pyproject-toml.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/guides/writing-pyproject-toml.rst b/source/guides/writing-pyproject-toml.rst index e82bd893d..18a717a55 100644 --- a/source/guides/writing-pyproject-toml.rst +++ b/source/guides/writing-pyproject-toml.rst @@ -130,7 +130,7 @@ only field that cannot be marked as dynamic. [project] name = "spam-eggs" -The project name must consists of ASCII letters, digits, underscores "``_``", +The project name must consist of ASCII letters, digits, underscores "``_``", hyphens "``-``" and periods "``.``". It must not start or end with an underscore, hyphen or period. From 4a5cbf920c6a7c7a37e155ff4c74c27a118d3e0b Mon Sep 17 00:00:00 2001 From: chrysle Date: Sat, 23 Dec 2023 15:21:43 +0100 Subject: [PATCH 059/121] Update "Dropping older Python versions" guide --- .../guides/dropping-older-python-versions.rst | 93 +++++++++++-------- 1 file changed, 53 insertions(+), 40 deletions(-) diff --git a/source/guides/dropping-older-python-versions.rst b/source/guides/dropping-older-python-versions.rst index c0c2b4434..1804f35c2 100644 --- a/source/guides/dropping-older-python-versions.rst +++ b/source/guides/dropping-older-python-versions.rst @@ -4,23 +4,17 @@ Dropping support for older Python versions ========================================== -Dropping support for older Python versions is supported by the standard :ref:`core-metadata` 1.2 specification via a "Requires-Python" attribute. +Dropping support for older Python versions is supported by the standard :ref:`core-metadata` 1.2 specification via a :ref:`"Requires-Python" ` attribute. Metadata 1.2+ clients, such as Pip 9.0+, will adhere to this specification by matching the current Python runtime and comparing it with the required version in the package metadata. If they do not match, it will attempt to install the last package distribution that supported that Python runtime. -This mechanism can be used to drop support for older Python versions, by amending the "Requires-Python" attribute in the package metadata. - -This guide is specifically for users of :ref:`setuptools`, other packaging tools such as ``flit`` may offer similar functionality but users will need to consult relevant documentation. +This mechanism can be used to drop support for older Python versions, by amending the ``Requires-Python`` attribute in the package metadata. Requirements ------------ -This workflow requires that: - -1. The publisher is using the latest version of :ref:`setuptools`, -2. The latest version of :ref:`twine` is used to upload the package, -3. The user installing the package has at least Pip 9.0, or a client that supports the Metadata 1.2 specification. +This workflow requires that the user installing the package has at least Pip 9.0, or a client that supports the Metadata 1.2 specification. Dealing with the universal wheels --------------------------------- @@ -52,42 +46,50 @@ explicitly set ``universal`` to ``0``: Defining the Python version required ------------------------------------ -1. Download the newest version of Setuptools -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Ensure that before you generate source distributions or binary distributions, you update Setuptools and install twine. +1. Install twine +~~~~~~~~~~~~~~~~ +Ensure that you have twine available at its latest version. Steps: .. tab:: Unix/macOS .. code-block:: bash - python3 -m pip install --upgrade setuptools twine + python3 -m pip install --upgrade twine .. tab:: Windows .. code-block:: bat - py -m pip install --upgrade setuptools twine - -``setuptools`` version should be above 24.0.0. + py -m pip install --upgrade twine 2. Specify the version ranges for supported Python distributions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -You can specify version ranges and exclusion rules, such as at least Python 3. Or, Python 2.7, 3.4 and beyond. - -Examples: +You can specify version ranges and exclusion rules (complying with the :ref:`version-specifiers` specification), +such as at least Python 3. Or, Python 2.7, 3.4 and beyond: .. code-block:: text - Requires-Python: ">=3" - Requires-Python: ">2.7,!=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*" + Requires-Python: ">= 3" + Requires-Python: ">= 2.7, != 3.0.*, != 3.1.*, != 3.2.*, != 3.3.*" + + +The way to set those values is within your :file:`pyproject.toml`. The :ref:`requires-python` field of the +``[project]`` table corresponds to the ``Requires-Python`` metadata field. + +.. code-block:: toml -The way to set those values is within the call to ``setup`` within your -:file:`setup.py` script. This will insert the ``Requires-Python`` -metadata values based on the argument you provide in ``python_requires``. + [build-system] + ... + + [project] + requires-python = ">= 3.8" # At least Python 3.8 + + +For :ref:`setuptools` users, another way to achieve this is using the ``python_requires`` parameter +in the call to ``setup`` within your :file:`setup.py` script. .. code-block:: python @@ -96,43 +98,54 @@ metadata values based on the argument you provide in ``python_requires``. setup( # Your setup arguments - python_requires='>=2.7', # Your supported Python ranges + python_requires='>= 3.8', ) +It is warned against adding upper bounds to the version ranges, e. g. ``">= 3.8 < 3.10"``. This can cause different errors +and version conflicts. See the `discourse discussion`_ for more information. + 3. Validating the Metadata before publishing ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Within a Python source package (the zip or the tar-gz file you download) is a text file called PKG-INFO. -This file is generated by :ref:`distutils` or :ref:`setuptools` when it generates the source package. -The file contains a set of keys and values, the list of keys is part of the PyPa standard metadata format. +This file is generated by the build backend when it generates the source package. +The file contains a set of keys and values, the list of keys is part of the PyPA standard metadata format. You can see the contents of the generated file like this: .. code-block:: bash - tar xfO dist/my-package-1.0.0.tar.gz my-package-1.0.0/PKG-INFO + tar xf dist/my-package-1.0.0.tar.gz my-package-1.0.0/PKG-INFO -O Validate that the following is in place, before publishing the package: - If you have upgraded correctly, the Metadata-Version value should be 1.2 or higher. -- The Requires-Python field is set and matches your specification in setup.py. +- The ``Requires-Python`` field is set and matches your specification in the configuration file. -4. Using Twine to publish +4. Publishing the package ~~~~~~~~~~~~~~~~~~~~~~~~~ -Twine has a number of advantages, apart from being faster it is now the supported method for publishing packages. +Proceed as suggested in :ref:`Uploading your Project to PyPI`. -Make sure you are using the newest version of Twine, at least 1.9. - -Dropping a Python release +Dropping a Python version ------------------------- -Once you have published a package with the Requires-Python metadata, you can then make a further update removing that Python runtime from support. +In principle, at least metadata support for Python versions should be kept as long as possible, because +once that has been dropped, people still depending on a version will be forced to downgrade. +If however supporting a specific version becomes a blocker for a new feature or other issues occur, the metadata +``Requires-Python`` should be amended. Of course this also depends on whether the project needs to be stable and +well-covered for a wider range of users. + +Each version compatibility change should have an own release. + +For example, you published version 1.0.0 of your package with ``Requires-Python: ">= 2.7"`` metadata. + +If you then update the version string to ``">= 3.5"``, and publish a new version 2.0.0 of your package, any users running Pip 9.0+ from version 2.7 will have version 1.0.0 of the package installed, and any ``>= 3.5`` users will receive version 2.0.0. -It must be done in this order for the automated fallback to work. +It may be a good idea to create a minor release, stating that it is the last one compatible with the Python version to be removed, just before dropping that version. -For example, you published the Requires-Python: ">=2.7" as version 1.0.0 of your package. +When dropping a Python version, it might also be rewarding to upgrade the project's code syntax generally, apart from updating the versions used in visible places (like the testing environment). Tools like pyupgrade_ can simplify this task. -If you were then to update the version string to ">=3.5", and publish a new version 2.0.0 of your package, any users running Pip 9.0+ from version 2.7 will -have version 1.0.0 of the package installed, and any >=3.5 users will receive version 2.0.0. +.. _discourse discussion: https://discuss.python.org/t/requires-python-upper-limits/12663 +.. _pyupgrade: https://pypi.org/project/pyupgrade/ From a02e0691a89d59d128302ff4223e443d7476c439 Mon Sep 17 00:00:00 2001 From: chrysle <96722107+chrysle@users.noreply.github.com> Date: Fri, 5 Jul 2024 16:11:49 +0200 Subject: [PATCH 060/121] Apply review comments MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Sviatoslav Sydorenko (Святослав Сидоренко) <578543+webknjaz@users.noreply.github.com> Co-authored-by: Jean Abou Samra <37271310+jeanas@users.noreply.github.com> Co-authored-by: Edgar Ramírez Mondragón <16805946+edgarrmondragon@users.noreply.github.com> --- .../guides/dropping-older-python-versions.rst | 64 ++++++++----------- 1 file changed, 28 insertions(+), 36 deletions(-) diff --git a/source/guides/dropping-older-python-versions.rst b/source/guides/dropping-older-python-versions.rst index 1804f35c2..9fdc35fa8 100644 --- a/source/guides/dropping-older-python-versions.rst +++ b/source/guides/dropping-older-python-versions.rst @@ -4,9 +4,9 @@ Dropping support for older Python versions ========================================== -Dropping support for older Python versions is supported by the standard :ref:`core-metadata` 1.2 specification via a :ref:`"Requires-Python" ` attribute. +The ability to drop support for older Python versions is enabled by the standard :ref:`core-metadata` 1.2 specification via the :ref:`"Requires-Python" ` attribute. -Metadata 1.2+ clients, such as Pip 9.0+, will adhere to this specification by matching the current Python runtime and comparing it with the required version +Metadata 1.2+ clients, such as Pip, will adhere to this specification by matching the current Python runtime and comparing it with the required version in the package metadata. If they do not match, it will attempt to install the last package distribution that supported that Python runtime. This mechanism can be used to drop support for older Python versions, by amending the ``Requires-Python`` attribute in the package metadata. @@ -14,18 +14,17 @@ This mechanism can be used to drop support for older Python versions, by amendin Requirements ------------ -This workflow requires that the user installing the package has at least Pip 9.0, or a client that supports the Metadata 1.2 specification. +This workflow requires that the user installing the package uses Pip [#]_, or another client that supports the Metadata 1.2 specification. Dealing with the universal wheels --------------------------------- -Traditionally, projects providing Python code that is semantically +Traditionally, :ref:`setuptools` projects providing Python code that is semantically compatible with both Python 2 and Python 3, produce :term:`wheels ` that have a ``py2.py3`` tag in their names. When dropping support for Python 2, it is important not to forget to change this tag to just ``py3``. It is often configured within :file:`setup.cfg` under -the ``[bdist_wheel]`` section by setting ``universal = 1`` if they -use setuptools. +the ``[bdist_wheel]`` section by setting ``universal = 1``. If you use this method, either remove this option or section, or explicitly set ``universal`` to ``0``: @@ -37,11 +36,10 @@ explicitly set ``universal`` to ``0``: [bdist_wheel] universal = 0 # Make the generated wheels have "py3" tag -.. tip:: +.. hint:: - Since it is possible to override the :file:`setup.cfg` settings via - CLI flags, make sure that your scripts don't have ``--universal`` in - your package creation scripts. + Regarding :ref:`deprecated ` direct ``setup.py`` invocations, + passing the ``--universal`` flag on the command line could override this setting. Defining the Python version required ------------------------------------ @@ -68,16 +66,16 @@ Steps: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ You can specify version ranges and exclusion rules (complying with the :ref:`version-specifiers` specification), -such as at least Python 3. Or, Python 2.7, 3.4 and beyond: +such as at least Python 3. Or, Python 3.7, 3.8, 3.13 and beyond: .. code-block:: text Requires-Python: ">= 3" - Requires-Python: ">= 2.7, != 3.0.*, != 3.1.*, != 3.2.*, != 3.3.*" + Requires-Python: ">= 3.7, != 3.9.*, != 3.10.*, != 3.11.*, != 3.12.*" -The way to set those values is within your :file:`pyproject.toml`. The :ref:`requires-python` field of the -``[project]`` table corresponds to the ``Requires-Python`` metadata field. +Those values can be set within your :file:`pyproject.toml`. The :ref:`requires-python` configuration field +corresponds to the ``Requires-Python`` metadata field. .. code-block:: toml @@ -89,34 +87,29 @@ The way to set those values is within your :file:`pyproject.toml`. The :ref:`req For :ref:`setuptools` users, another way to achieve this is using the ``python_requires`` parameter -in the call to ``setup`` within your :file:`setup.py` script. - -.. code-block:: python - - from setuptools import setup - +in your :file:`setup.cfg` config or the :file:`setup.py` script. ``setuptools < 61`` does not support +declaring the package metadata in :file:`pyproject.toml`. - setup( - # Your setup arguments - python_requires='>= 3.8', - ) +Consult the ``setuptools`` `dependency-management`_ documentation for information about the appropriate +way to configure each of these files. -It is warned against adding upper bounds to the version ranges, e. g. ``">= 3.8 < 3.10"``. This can cause different errors -and version conflicts. See the `discourse discussion`_ for more information. +.. caution:: + It is warned against adding upper bounds to the version ranges, e. g. ``">= 3.8 < 3.10"``. This can cause different errors + and version conflicts. See the `discourse-discussion`_ for more information. 3. Validating the Metadata before publishing ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Within a Python source package (the zip or the tar-gz file you download) is a text file called PKG-INFO. -This file is generated by the build backend when it generates the source package. +This file is generated by the :term:`build backend ` when it generates the source package. The file contains a set of keys and values, the list of keys is part of the PyPA standard metadata format. You can see the contents of the generated file like this: .. code-block:: bash - tar xf dist/my-package-1.0.0.tar.gz my-package-1.0.0/PKG-INFO -O + tar xfO dist/my-package-1.0.0.tar.gz my-package-1.0.0/PKG-INFO Validate that the following is in place, before publishing the package: @@ -137,15 +130,14 @@ If however supporting a specific version becomes a blocker for a new feature or ``Requires-Python`` should be amended. Of course this also depends on whether the project needs to be stable and well-covered for a wider range of users. -Each version compatibility change should have an own release. +Each version compatibility change should have its own release. -For example, you published version 1.0.0 of your package with ``Requires-Python: ">= 2.7"`` metadata. - -If you then update the version string to ``">= 3.5"``, and publish a new version 2.0.0 of your package, any users running Pip 9.0+ from version 2.7 will have version 1.0.0 of the package installed, and any ``>= 3.5`` users will receive version 2.0.0. - -It may be a good idea to create a minor release, stating that it is the last one compatible with the Python version to be removed, just before dropping that version. +.. tip:: -When dropping a Python version, it might also be rewarding to upgrade the project's code syntax generally, apart from updating the versions used in visible places (like the testing environment). Tools like pyupgrade_ can simplify this task. + When dropping a Python version, it might also be rewarding to upgrade the project's code syntax generally, apart from updating the versions used in visible places (like the testing environment). Tools like pyupgrade_ can simplify this task. -.. _discourse discussion: https://discuss.python.org/t/requires-python-upper-limits/12663 +.. _discourse-discussion: https://discuss.python.org/t/requires-python-upper-limits/12663 .. _pyupgrade: https://pypi.org/project/pyupgrade/ +.. _dependency-management: https://setuptools.pypa.io/en/latest/userguide/dependency_management.html#python-requirement + +.. [#] Support for the Metadata 1.2 specification has been added in Pip 9.0. From c5723dfac9563d5885ee667c358dbaad3cea92e6 Mon Sep 17 00:00:00 2001 From: chrysle <96722107+chrysle@users.noreply.github.com> Date: Sat, 20 Jul 2024 17:59:53 +0200 Subject: [PATCH 061/121] Use `pyproject.toml` instead of core metadata syntax Better version range examples, tweak grammar, mention `ruff` as helper tool for Python version upgrade Co-authored-by: Jason R. Coombs <308610+jaraco@users.noreply.github.com> --- .../guides/dropping-older-python-versions.rst | 37 ++++++++----------- 1 file changed, 16 insertions(+), 21 deletions(-) diff --git a/source/guides/dropping-older-python-versions.rst b/source/guides/dropping-older-python-versions.rst index 9fdc35fa8..f3945dd6f 100644 --- a/source/guides/dropping-older-python-versions.rst +++ b/source/guides/dropping-older-python-versions.rst @@ -6,7 +6,7 @@ Dropping support for older Python versions The ability to drop support for older Python versions is enabled by the standard :ref:`core-metadata` 1.2 specification via the :ref:`"Requires-Python" ` attribute. -Metadata 1.2+ clients, such as Pip, will adhere to this specification by matching the current Python runtime and comparing it with the required version +Metadata 1.2+ installers, such as Pip, will adhere to this specification by matching the current Python runtime and comparing it with the required version in the package metadata. If they do not match, it will attempt to install the last package distribution that supported that Python runtime. This mechanism can be used to drop support for older Python versions, by amending the ``Requires-Python`` attribute in the package metadata. @@ -14,7 +14,7 @@ This mechanism can be used to drop support for older Python versions, by amendin Requirements ------------ -This workflow requires that the user installing the package uses Pip [#]_, or another client that supports the Metadata 1.2 specification. +This workflow requires that the user installing the package uses Pip [#]_, or another installer that supports the Metadata 1.2 specification. Dealing with the universal wheels --------------------------------- @@ -65,17 +65,9 @@ Steps: 2. Specify the version ranges for supported Python distributions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -You can specify version ranges and exclusion rules (complying with the :ref:`version-specifiers` specification), -such as at least Python 3. Or, Python 3.7, 3.8, 3.13 and beyond: - -.. code-block:: text - - Requires-Python: ">= 3" - Requires-Python: ">= 3.7, != 3.9.*, != 3.10.*, != 3.11.*, != 3.12.*" - - -Those values can be set within your :file:`pyproject.toml`. The :ref:`requires-python` configuration field -corresponds to the ``Requires-Python`` metadata field. +Set the version ranges declaring which Python distributions are supported +within your project's :file:`pyproject.toml`. The :ref:`requires-python` configuration field +corresponds to the :ref:`Requires-Python ` core metadata field: .. code-block:: toml @@ -85,16 +77,19 @@ corresponds to the ``Requires-Python`` metadata field. [project] requires-python = ">= 3.8" # At least Python 3.8 +You can specify version ranges and exclusion rules (complying with the :ref:`version-specifiers` specification), +such as at least Python 3.9. Or, at least Python 3.7 and beyond, skipping the 3.7.0 and 3.7.1 point releases: + +.. code-block:: toml + + requires-python = ">= 3.9" + requires-python = ">= 3.7, != 3.7.0, != 3.7.1" -For :ref:`setuptools` users, another way to achieve this is using the ``python_requires`` parameter -in your :file:`setup.cfg` config or the :file:`setup.py` script. ``setuptools < 61`` does not support -declaring the package metadata in :file:`pyproject.toml`. -Consult the ``setuptools`` `dependency-management`_ documentation for information about the appropriate -way to configure each of these files. +If using the :ref:`setuptools` build backend, consult the `dependency-management`_ documentation for more options. .. caution:: - It is warned against adding upper bounds to the version ranges, e. g. ``">= 3.8 < 3.10"``. This can cause different errors + Avoid adding upper bounds to the version ranges, e. g. ``">= 3.8, < 3.10"``. Doing so can cause different errors and version conflicts. See the `discourse-discussion`_ for more information. 3. Validating the Metadata before publishing @@ -113,7 +108,7 @@ You can see the contents of the generated file like this: Validate that the following is in place, before publishing the package: -- If you have upgraded correctly, the Metadata-Version value should be 1.2 or higher. +- If you have upgraded correctly, the ``Metadata-Version`` value should be 1.2 or higher. - The ``Requires-Python`` field is set and matches your specification in the configuration file. 4. Publishing the package @@ -134,7 +129,7 @@ Each version compatibility change should have its own release. .. tip:: - When dropping a Python version, it might also be rewarding to upgrade the project's code syntax generally, apart from updating the versions used in visible places (like the testing environment). Tools like pyupgrade_ can simplify this task. + When dropping a Python version, it might also be rewarding to upgrade the project's code syntax generally, apart from updating the versions used in visible places (like the testing environment). Tools like pyupgrade_ or `ruff `_ can automate some of this work. .. _discourse-discussion: https://discuss.python.org/t/requires-python-upper-limits/12663 .. _pyupgrade: https://pypi.org/project/pyupgrade/ From 2b6bc988c5f7867de72fb6278b95f745bbf2712f Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Sat, 20 Jul 2024 16:05:06 +0000 Subject: [PATCH 062/121] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- source/guides/dropping-older-python-versions.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/guides/dropping-older-python-versions.rst b/source/guides/dropping-older-python-versions.rst index f3945dd6f..267d7b923 100644 --- a/source/guides/dropping-older-python-versions.rst +++ b/source/guides/dropping-older-python-versions.rst @@ -65,7 +65,7 @@ Steps: 2. Specify the version ranges for supported Python distributions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Set the version ranges declaring which Python distributions are supported +Set the version ranges declaring which Python distributions are supported within your project's :file:`pyproject.toml`. The :ref:`requires-python` configuration field corresponds to the :ref:`Requires-Python ` core metadata field: From f6d6e5ce3165c7ce6b92c8d6b6f2bd9341154565 Mon Sep 17 00:00:00 2001 From: chrysle <96722107+chrysle@users.noreply.github.com> Date: Mon, 29 Jul 2024 10:41:44 +0200 Subject: [PATCH 063/121] Temporarily ignore https://pyscaffold.org, fix Fedora link --- source/conf.py | 1 + source/guides/installing-using-linux-tools.rst | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/source/conf.py b/source/conf.py index cd459ffb2..c777550ce 100644 --- a/source/conf.py +++ b/source/conf.py @@ -132,6 +132,7 @@ # Ignore while StackOverflow is blocking GitHub CI. Ref: # https://github.com/pypa/packaging.python.org/pull/1474 "https://stackoverflow.com/*", + "https://pyscaffold.org/*", ] linkcheck_retries = 5 # Ignore anchors for links to GitHub project pages -- GitHub adds anchors from diff --git a/source/guides/installing-using-linux-tools.rst b/source/guides/installing-using-linux-tools.rst index f0914f8dc..56647f3e9 100644 --- a/source/guides/installing-using-linux-tools.rst +++ b/source/guides/installing-using-linux-tools.rst @@ -51,7 +51,7 @@ To install pip and wheel for the system Python, there are two options: 1. Enable the `EPEL repository `_ using `these instructions - `__. + `__. On EPEL 7, you can install pip and wheel like so: .. code-block:: bash From 85dc060158e2e2f0764033bf9fb4a4ceea0bc0ae Mon Sep 17 00:00:00 2001 From: chrysle <96722107+chrysle@users.noreply.github.com> Date: Sat, 25 May 2024 20:19:01 +0200 Subject: [PATCH 064/121] Add guide on packaging command-line tooling --- .../analyzing-pypi-package-downloads.rst | 2 + source/guides/creating-command-line-tools.rst | 213 ++++++++++++++++++ ...talling-stand-alone-command-line-tools.rst | 2 + source/guides/section-build-and-publish.rst | 1 + 4 files changed, 218 insertions(+) create mode 100644 source/guides/creating-command-line-tools.rst diff --git a/source/guides/analyzing-pypi-package-downloads.rst b/source/guides/analyzing-pypi-package-downloads.rst index 62efea7ab..5fecc99c1 100644 --- a/source/guides/analyzing-pypi-package-downloads.rst +++ b/source/guides/analyzing-pypi-package-downloads.rst @@ -1,3 +1,5 @@ +.. _analyzing-pypi-package-downloads: + ================================ Analyzing PyPI package downloads ================================ diff --git a/source/guides/creating-command-line-tools.rst b/source/guides/creating-command-line-tools.rst new file mode 100644 index 000000000..80aaf30a1 --- /dev/null +++ b/source/guides/creating-command-line-tools.rst @@ -0,0 +1,213 @@ +.. _creating-command-line-tools: + +========================================= +Creating and packaging command-line tools +========================================= + +This guide will walk you through creating and packaging a standalone command-line application +that can be installed with :ref:`pipx`, a tool creating and managing :term:`Python Virtual Environments ` +and exposing the executable scripts of packages (and available manual pages) for use on the command-line. + +Creating the package +==================== + +First of all, we'll need to create a source tree for the :term:`project `. For the sake of an example, we'll +create a simple tool outputting a greeting (a string) for a person based on arguments given on the command-line. + +.. todo:: Advise on the optimal structure of a Python package in another guide or discussion and link to it here. + +This project will adhere to :ref:`src-layout ` and in the end be alike this file tree, +with the top-level folder and package name ``greetings``: + +:: + + . + ├── pyproject.toml + └── src + └── greetings + ├── cli.py + ├── greet.py + ├── __init__.py + └── __main__.py + +The actual code responsible for the tool's functionality will be stored in the file :file:`greet.py`, +named after the main module: + +.. code-block:: python + + def greet(name="", gender="", knight=False, count=1): + greeting = "Greetings, dear " + masculine = gender == "masculine" + feminine = gender == "feminine" + if gender or knight: + salutation = "" + if knight: + salutation = "Sir " + elif masculine: + salutation = "Mr. " + elif feminine: + salutation = "Ms. " + greeting += salutation + if name: + greeting += f"{name}!" + else: + pronoun = "her" if feminine else "his" if masculine or knight else "its" + greeting += f"what's-{pronoun}-name!" + else: + if name: + greeting += f"{name}!" + elif not gender: + greeting += "friend!" + for i in range(0, count): + print(greeting) + +The above function receives several keyword arguments that determine how the greeting to output is constructed. +Now, the command-line interface to provision it with the same needs to be constructed, which is done +in :file:`cli.py`: + +.. code-block:: python + + import argparse + import sys + + from .greet import greet + + _arg_spec = { + '--name': { + 'metavar': 'STRING', + 'type': str, + 'help': 'The (last, if "gender" is given) name of the person to greet', + }, + '--count': { + 'metavar': 'INT', + 'type': int, + 'default': 1, + 'help': 'Number of times to greet the person', + }, + + } + _arg_spec_mutually_exclusive = { + '--gender': { + 'metavar': 'STRING', + 'type': str, + 'help': 'The gender of the person to greet', + }, + '--knight': { + 'action': 'store_true', + 'default': False, + 'help': 'Whether the person is a knight', + }, + } + + + def main(): + parser = argparse.ArgumentParser( + description="Greet a person (semi-)formally." + ) + group = parser.add_mutually_exclusive_group() + for arg, spec in _arg_spec.items(): + parser.add_argument(arg, **spec) + for arg, spec in _arg_spec_mutually_exclusive.items(): + group.add_argument(arg, **spec) + parsed_args = parser.parse_args() + args = { + arg: value + for arg, value in vars(parsed_args).items() + if value is not None + } + # Run the function with the command-line arguments as keyword arguments. + # A more complex setup is normally initialized at this point. + greet(**args) + + + if __name__ == "__main__": + sys.exit(main()) + +The command-line interface is built with :py:mod:`argparse`, a command-line parser which is included in Python's +standard library. It is a bit rudimentary but sufficient for most needs. Another easy-to-use alternative is docopt_; +advanced users are encouraged to make use of click_. + +We'll add an empty :file:`__init__.py` file, too, to define the project as a regular :term:`import package `. + +The file :file:`__main__.py` marks the main entry point for the application when running it via ``python -m greetings``, +so we'll just initizalize the command-line interface here. The first condition isn't necessary, but may be added in order +to make the package runnable directly from the source tree, by prepending the package folder to Python's :py:data:`sys.path`: + +.. code-block:: python + + import os + import sys + + if not __package__: + # Make package runnable from source tree with + # python src/greetings + package_source_path = os.path.dirname(os.path.dirname(__file__)) + sys.path.insert(0, package_source_path) + + if __name__ == "__main__": + from greetings.cli import main + sys.exit(main()) + + +``pyproject.toml`` +------------------ + +The project's :term:`metadata ` is placed in :term:`pyproject.toml`. The :term:`pyproject metadata keys ` and the ``[build-system]`` table may be filled in as described in :ref:`writing-pyproject-toml`. + +For the project to be recognised as a command-line tool, additionally a ``console_scripts`` :ref:`entry point ` (see :ref:`console_scripts`) needs to be added as a :term:`subkey `: + +.. code-block:: toml + + [project.scripts] + greet = "greetings.cli:main" + +Besides, it could prove rewarding to add a ``pipx``-specific entry point, the meaning of which is described below: + +.. code-block:: toml + + [project.entry-points."pipx.run"] + greetings = "greetings.cli:main" + + +Now, the project's source tree is ready to be transformed into a :term:`distribution package `, +which makes it installable. + + +Installing the package with ``pipx`` +==================================== + +After installing ``pipx`` as described in :ref:`installing-stand-alone-command-line-tools`, you're ready to install your project: + +.. code-block:: console + + $ pipx install ./greetings/ + +This will expose the executable script we defined as an entry point and make the command ``greet`` available to you. +Let's test it: + +.. code-block:: console + + $ greet --knight --name Lancelot + Greetings, dear Sir Lancelot! + $ greet --gender feminine --name Parks + Greetings, dear Ms. Parks! + $ greet --gender masculine + Greetings, dear Mr. what's-his-name! + +To just run the program without installing it permanently, you could use ``pipx run``, which will create a temporary (but cached) virtual environment for it: + +.. code-block:: console + + $ pipx run ./greetings/ --knight + +Thanks to the entry point we defined above (which *must* match the package name), ``pipx`` will pick up the executable script as the +default one and run it; otherwise, you'd need to specify the entry point's name explicitly with ``pipx run --spec ./greetings/ greet --knight``. + +Conclusion +========== + +You know by now how to package a command-line application written in Python. A further step could be to distribute you package, +meaning uploading it to a :term:`package index `, most commonly :term:`PyPI `. To do that, follow the instructions at :ref:`Packaging your project`. And once you're done, don't forget to :ref:`do some research ` on how your package is received! + +.. _click: https://click.palletsprojects.com/ +.. _docopt: https://docopt.readthedocs.io/en/latest/ diff --git a/source/guides/installing-stand-alone-command-line-tools.rst b/source/guides/installing-stand-alone-command-line-tools.rst index 8578a3b28..c078fd1e4 100644 --- a/source/guides/installing-stand-alone-command-line-tools.rst +++ b/source/guides/installing-stand-alone-command-line-tools.rst @@ -1,3 +1,5 @@ +.. _installing-stand-alone-command-line-tools: + Installing stand alone command line tools ========================================= diff --git a/source/guides/section-build-and-publish.rst b/source/guides/section-build-and-publish.rst index 2af29d763..8e0c9ab3b 100644 --- a/source/guides/section-build-and-publish.rst +++ b/source/guides/section-build-and-publish.rst @@ -11,6 +11,7 @@ Building and Publishing dropping-older-python-versions packaging-binary-extensions packaging-namespace-packages + creating-command-line-tools creating-and-discovering-plugins using-testpypi making-a-pypi-friendly-readme From 6729b3d1f6fbcf3950fd18b6a37c6ffc4291ee5b Mon Sep 17 00:00:00 2001 From: chrysle <96722107+chrysle@users.noreply.github.com> Date: Mon, 24 Jun 2024 17:08:42 +0200 Subject: [PATCH 065/121] Refine structure Make the guide more easily comprehensible, mention difference between src and flat layout concerning `runpy` behaviour, mention typer CLI parser, tighten language Co-authored-by: Jason R. Coombs <308610+jaraco@users.noreply.github.com> --- .../discussions/src-layout-vs-flat-layout.rst | 24 +++++++ source/guides/creating-command-line-tools.rst | 69 +++++++++++-------- 2 files changed, 63 insertions(+), 30 deletions(-) diff --git a/source/discussions/src-layout-vs-flat-layout.rst b/source/discussions/src-layout-vs-flat-layout.rst index bfa405729..c38968345 100644 --- a/source/discussions/src-layout-vs-flat-layout.rst +++ b/source/discussions/src-layout-vs-flat-layout.rst @@ -79,3 +79,27 @@ layout and the flat layout: ``tox.ini``) and packaging/tooling configuration files (eg: ``setup.py``, ``noxfile.py``) on the import path. This would make certain imports work in editable installations but not regular installations. + +.. _running-cli-from-source-src-layout: + +Running a command-line interface from source with src-layout +============================================================ + +Due to the firstly mentioned specialty of the src layout, a command-line +interface can not be run directly from the :term:`source tree `, +but requires installation of the package in +:doc:`Development Mode ` +for testing purposes. Since this can be unpractical in some situations, +a workaround could be to prepend the package folder to Python's +:py:data:`sys.path` when called via its :file:`__main__.py` file: + +.. code-block:: python + + import os + import sys + + if not __package__: + # Make CLI runnable from source tree with + # python src/package + package_source_path = os.path.dirname(os.path.dirname(__file__)) + sys.path.insert(0, package_source_path) diff --git a/source/guides/creating-command-line-tools.rst b/source/guides/creating-command-line-tools.rst index 80aaf30a1..f7c3fc74a 100644 --- a/source/guides/creating-command-line-tools.rst +++ b/source/guides/creating-command-line-tools.rst @@ -11,8 +11,8 @@ and exposing the executable scripts of packages (and available manual pages) for Creating the package ==================== -First of all, we'll need to create a source tree for the :term:`project `. For the sake of an example, we'll -create a simple tool outputting a greeting (a string) for a person based on arguments given on the command-line. +First of all, create a source tree for the :term:`project `. For the sake of an example, we'll +build a simple tool outputting a greeting (a string) for a person based on arguments given on the command-line. .. todo:: Advise on the optimal structure of a Python package in another guide or discussion and link to it here. @@ -62,7 +62,7 @@ named after the main module: print(greeting) The above function receives several keyword arguments that determine how the greeting to output is constructed. -Now, the command-line interface to provision it with the same needs to be constructed, which is done +Now, construct the command-line interface to provision it with the same, which is done in :file:`cli.py`: .. code-block:: python @@ -125,29 +125,28 @@ in :file:`cli.py`: The command-line interface is built with :py:mod:`argparse`, a command-line parser which is included in Python's standard library. It is a bit rudimentary but sufficient for most needs. Another easy-to-use alternative is docopt_; -advanced users are encouraged to make use of click_. +advanced users are encouraged to make use of click_ or typer_. -We'll add an empty :file:`__init__.py` file, too, to define the project as a regular :term:`import package `. +Now, add an empty :file:`__init__.py` file, to define the project as a regular :term:`import package `. -The file :file:`__main__.py` marks the main entry point for the application when running it via ``python -m greetings``, -so we'll just initizalize the command-line interface here. The first condition isn't necessary, but may be added in order -to make the package runnable directly from the source tree, by prepending the package folder to Python's :py:data:`sys.path`: +The file :file:`__main__.py` marks the main entry point for the application when running it via :mod:`runpy` +(i.e. ``python -m greetings``, which works immediately with flat layout, but requires installation of the package with src layout), +so initizalize the command-line interface here: .. code-block:: python - import os import sys - if not __package__: - # Make package runnable from source tree with - # python src/greetings - package_source_path = os.path.dirname(os.path.dirname(__file__)) - sys.path.insert(0, package_source_path) - if __name__ == "__main__": from greetings.cli import main sys.exit(main()) +.. note:: + + In order to enable calling the command-line interface directly from the :term:`source tree `, + i.e. as ``python src/greetings``, a certain hack could be placed in this file; read more at + :ref:`running-cli-from-source-src-layout`. + ``pyproject.toml`` ------------------ @@ -161,14 +160,6 @@ For the project to be recognised as a command-line tool, additionally a ``consol [project.scripts] greet = "greetings.cli:main" -Besides, it could prove rewarding to add a ``pipx``-specific entry point, the meaning of which is described below: - -.. code-block:: toml - - [project.entry-points."pipx.run"] - greetings = "greetings.cli:main" - - Now, the project's source tree is ready to be transformed into a :term:`distribution package `, which makes it installable. @@ -176,13 +167,14 @@ which makes it installable. Installing the package with ``pipx`` ==================================== -After installing ``pipx`` as described in :ref:`installing-stand-alone-command-line-tools`, you're ready to install your project: +After installing ``pipx`` as described in :ref:`installing-stand-alone-command-line-tools`, install your project: .. code-block:: console - $ pipx install ./greetings/ + $ cd path/to/greetings/ + $ pipx install . -This will expose the executable script we defined as an entry point and make the command ``greet`` available to you. +This will expose the executable script we defined as an entry point and make the command ``greet`` available. Let's test it: .. code-block:: console @@ -194,14 +186,30 @@ Let's test it: $ greet --gender masculine Greetings, dear Mr. what's-his-name! -To just run the program without installing it permanently, you could use ``pipx run``, which will create a temporary (but cached) virtual environment for it: +To just run the program without installing it permanently, use ``pipx run``, which will create a temporary (but cached) virtual environment for it: .. code-block:: console - $ pipx run ./greetings/ --knight + $ pipx run --spec . greet --knight + +This syntax is a bit unpractical, however; as the name of the entry point we defined above does not match the package name, +we need to state explicitly which executable script to run (even though there is only on in existence). + +There is, however, a more practical solution to this problem, in the form of an entry point specific to ``pipx run``. +The same can be defined as follows in :file:`pyproject.toml`: + +.. code-block:: toml + + [project.entry-points."pipx.run"] + greetings = "greetings.cli:main" + + +Thanks to this entry point (which *must* match the package name), ``pipx`` will pick up the executable script as the +default one and run it, which makes this command possible: + +.. code-block:: console -Thanks to the entry point we defined above (which *must* match the package name), ``pipx`` will pick up the executable script as the -default one and run it; otherwise, you'd need to specify the entry point's name explicitly with ``pipx run --spec ./greetings/ greet --knight``. + $ pipx run . --knight Conclusion ========== @@ -211,3 +219,4 @@ meaning uploading it to a :term:`package index `, most commonly : .. _click: https://click.palletsprojects.com/ .. _docopt: https://docopt.readthedocs.io/en/latest/ +.. _typer: https://typer.tiangolo.com/ From 2d7be49b8c179a94eb773bbc702e07df763189ce Mon Sep 17 00:00:00 2001 From: chrysle <96722107+chrysle@users.noreply.github.com> Date: Thu, 4 Jul 2024 17:22:55 +0200 Subject: [PATCH 066/121] Use `typer` for command-line interface creation --- source/guides/creating-command-line-tools.rst | 152 +++++++----------- 1 file changed, 61 insertions(+), 91 deletions(-) diff --git a/source/guides/creating-command-line-tools.rst b/source/guides/creating-command-line-tools.rst index f7c3fc74a..9f040ce7d 100644 --- a/source/guides/creating-command-line-tools.rst +++ b/source/guides/creating-command-line-tools.rst @@ -35,31 +35,40 @@ named after the main module: .. code-block:: python - def greet(name="", gender="", knight=False, count=1): - greeting = "Greetings, dear " - masculine = gender == "masculine" - feminine = gender == "feminine" - if gender or knight: - salutation = "" - if knight: - salutation = "Sir " - elif masculine: - salutation = "Mr. " - elif feminine: - salutation = "Ms. " - greeting += salutation - if name: - greeting += f"{name}!" - else: - pronoun = "her" if feminine else "his" if masculine or knight else "its" - greeting += f"what's-{pronoun}-name!" - else: - if name: - greeting += f"{name}!" - elif not gender: - greeting += "friend!" - for i in range(0, count): - print(greeting) + import typer + from typing_extensions import Annotated + + + def greet( + name: Annotated[str, typer.Argument(help="The (last, if --gender is given) name of the person to greet")] = "", + gender: Annotated[str, typer.Option(help="The gender of the person to greet")] = "", + knight: Annotated[bool, typer.Option(help="Whether the person is a knight")] = False, + count: Annotated[int, typer.Option(help="Number of times to greet the person")] = 1 + ): + greeting = "Greetings, dear " + masculine = gender == "masculine" + feminine = gender == "feminine" + if gender or knight: + salutation = "" + if knight: + salutation = "Sir " + elif masculine: + salutation = "Mr. " + elif feminine: + salutation = "Ms. " + greeting += salutation + if name: + greeting += f"{name}!" + else: + pronoun = "her" if feminine else "his" if masculine or knight else "its" + greeting += f"what's-{pronoun}-name" + else: + if name: + greeting += f"{name}!" + elif not gender: + greeting += "friend!" + for i in range(0, count): + print(greeting) The above function receives several keyword arguments that determine how the greeting to output is constructed. Now, construct the command-line interface to provision it with the same, which is done @@ -67,65 +76,23 @@ in :file:`cli.py`: .. code-block:: python - import argparse - import sys - - from .greet import greet - - _arg_spec = { - '--name': { - 'metavar': 'STRING', - 'type': str, - 'help': 'The (last, if "gender" is given) name of the person to greet', - }, - '--count': { - 'metavar': 'INT', - 'type': int, - 'default': 1, - 'help': 'Number of times to greet the person', - }, - - } - _arg_spec_mutually_exclusive = { - '--gender': { - 'metavar': 'STRING', - 'type': str, - 'help': 'The gender of the person to greet', - }, - '--knight': { - 'action': 'store_true', - 'default': False, - 'help': 'Whether the person is a knight', - }, - } - - - def main(): - parser = argparse.ArgumentParser( - description="Greet a person (semi-)formally." - ) - group = parser.add_mutually_exclusive_group() - for arg, spec in _arg_spec.items(): - parser.add_argument(arg, **spec) - for arg, spec in _arg_spec_mutually_exclusive.items(): - group.add_argument(arg, **spec) - parsed_args = parser.parse_args() - args = { - arg: value - for arg, value in vars(parsed_args).items() - if value is not None - } - # Run the function with the command-line arguments as keyword arguments. - # A more complex setup is normally initialized at this point. - greet(**args) + import typer + from .hello import greet + + + app = typer.Typer() + app.command()(greet) - if __name__ == "__main__": - sys.exit(main()) -The command-line interface is built with :py:mod:`argparse`, a command-line parser which is included in Python's -standard library. It is a bit rudimentary but sufficient for most needs. Another easy-to-use alternative is docopt_; -advanced users are encouraged to make use of click_ or typer_. + if __name__ == "__main__": + app() + +The command-line interface is built with typer_, an easy-to-use CLI parser based on Python type hints. It provides +auto-completion and nicely styled command-line help out of the box. Another option would be :py:mod:`argparse`, +a command-line parser which is included in Python's standard library. It is sufficient for most needs, but requires +a lot of code, usually in ``cli.py``, to function properly. Alternatively, docopt_ makes it possible to create CLI +interfaces based solely on docstrings; advanced users are encouraged to make use of click_ (on which ``typer`` is based). Now, add an empty :file:`__init__.py` file, to define the project as a regular :term:`import package `. @@ -135,11 +102,9 @@ so initizalize the command-line interface here: .. code-block:: python - import sys - if __name__ == "__main__": - from greetings.cli import main - sys.exit(main()) + from greetings.cli import app + app() .. note:: @@ -151,14 +116,15 @@ so initizalize the command-line interface here: ``pyproject.toml`` ------------------ -The project's :term:`metadata ` is placed in :term:`pyproject.toml`. The :term:`pyproject metadata keys ` and the ``[build-system]`` table may be filled in as described in :ref:`writing-pyproject-toml`. +The project's :term:`metadata ` is placed in :term:`pyproject.toml`. The :term:`pyproject metadata keys ` and the ``[build-system]`` table may be filled in as described in :ref:`writing-pyproject-toml`, adding a dependency +on ``typer`` (this tutorial uses version *0.12.3*). For the project to be recognised as a command-line tool, additionally a ``console_scripts`` :ref:`entry point ` (see :ref:`console_scripts`) needs to be added as a :term:`subkey `: .. code-block:: toml [project.scripts] - greet = "greetings.cli:main" + greet = "greetings.cli:app" Now, the project's source tree is ready to be transformed into a :term:`distribution package `, which makes it installable. @@ -179,14 +145,18 @@ Let's test it: .. code-block:: console - $ greet --knight --name Lancelot + $ greet --knight Lancelot Greetings, dear Sir Lancelot! - $ greet --gender feminine --name Parks + $ greet --gender feminine Parks Greetings, dear Ms. Parks! $ greet --gender masculine Greetings, dear Mr. what's-his-name! -To just run the program without installing it permanently, use ``pipx run``, which will create a temporary (but cached) virtual environment for it: +Since this example uses ``typer``, you could now also get an overview of the program's usage by calling it with +the ``--help`` option, or configure completions via the ``--install-completion`` option. + +To just run the program without installing it permanently, use ``pipx run``, which will create a temporary +(but cached) virtual environment for it: .. code-block:: console @@ -201,7 +171,7 @@ The same can be defined as follows in :file:`pyproject.toml`: .. code-block:: toml [project.entry-points."pipx.run"] - greetings = "greetings.cli:main" + greetings = "greetings.cli:app" Thanks to this entry point (which *must* match the package name), ``pipx`` will pick up the executable script as the From 0bdccb0898cd38058722523fead9278e4ead354e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ville=20Skytt=C3=A4?= Date: Mon, 15 Jul 2024 23:35:06 +0300 Subject: [PATCH 067/121] Spelling and grammar fixes --- source/specifications/direct-url-data-structure.rst | 2 +- source/specifications/externally-managed-environments.rst | 2 +- source/specifications/simple-repository-api.rst | 6 +++--- source/specifications/version-specifiers.rst | 2 +- 4 files changed, 6 insertions(+), 6 deletions(-) diff --git a/source/specifications/direct-url-data-structure.rst b/source/specifications/direct-url-data-structure.rst index 231198ee8..9ec8e2e34 100644 --- a/source/specifications/direct-url-data-structure.rst +++ b/source/specifications/direct-url-data-structure.rst @@ -44,7 +44,7 @@ expression: Additionally, the user:password section of the URL MAY be a well-known, non security sensitive string. A typical example is ``git`` -in the case of an URL such as ``ssh://git@gitlab.com/user/repo``. +in the case of a URL such as ``ssh://git@gitlab.com/user/repo``. VCS URLs -------- diff --git a/source/specifications/externally-managed-environments.rst b/source/specifications/externally-managed-environments.rst index 2944eb3da..65fc14a62 100644 --- a/source/specifications/externally-managed-environments.rst +++ b/source/specifications/externally-managed-environments.rst @@ -205,7 +205,7 @@ virtual environment to install packages. Software distributors who have a non-Python-specific package manager that manages libraries in the ``sys.path`` of their Python package -should, in general, ship a ``EXTERNALLY-MANAGED`` file in their +should, in general, ship an ``EXTERNALLY-MANAGED`` file in their standard library directory. For instance, Debian may ship a file in ``/usr/lib/python3.9/EXTERNALLY-MANAGED`` consisting of something like diff --git a/source/specifications/simple-repository-api.rst b/source/specifications/simple-repository-api.rst index b9f87ce7b..0d65a58aa 100644 --- a/source/specifications/simple-repository-api.rst +++ b/source/specifications/simple-repository-api.rst @@ -360,7 +360,7 @@ spec: * All JSON responses will *always* be a JSON object rather than an array or other type. -* While JSON doesn't natively support an URL type, any value that represents an +* While JSON doesn't natively support a URL type, any value that represents an URL in this API may be either absolute or relative as long as they point to the correct location. If relative, they are relative to the current URL as if it were HTML. @@ -616,7 +616,7 @@ likely just be treated the same as a ``406 Not Acceptable`` error. This spec **does** require that if the meta version ``latest`` is being used, the server **MUST** respond with the content type for the actual version that is contained in the response -(i.e. A ``Accept: application/vnd.pypi.simple.latest+json`` request that returns +(i.e. an ``Accept: application/vnd.pypi.simple.latest+json`` request that returns a ``v1.x`` response should have a ``Content-Type`` of ``application/vnd.pypi.simple.v1+json``). @@ -725,7 +725,7 @@ may *optionally* be used instead. URL Parameter ^^^^^^^^^^^^^ -Servers that implement the Simple API may choose to support an URL parameter named +Servers that implement the Simple API may choose to support a URL parameter named ``format`` to allow the clients to request a specific version of the URL. The value of the ``format`` parameter should be **one** of the valid content types. diff --git a/source/specifications/version-specifiers.rst b/source/specifications/version-specifiers.rst index cde0bc49a..a5ba36498 100644 --- a/source/specifications/version-specifiers.rst +++ b/source/specifications/version-specifiers.rst @@ -1178,7 +1178,7 @@ more information on ``file://`` URLs on Windows see Summary of differences from pkg_resources.parse_version ======================================================= -* Note: this comparison is to ``pkg_resourses.parse_version`` as it existed at +* Note: this comparison is to ``pkg_resources.parse_version`` as it existed at the time :pep:`440` was written. After the PEP was accepted, setuptools 6.0 and later versions adopted the behaviour described here. From 342f9eb0a597d33f9c0b0e7cd5d9192c0521e34f Mon Sep 17 00:00:00 2001 From: Chris Barker Date: Thu, 25 Jul 2024 09:34:31 -0700 Subject: [PATCH 068/121] updated single_source_version with a much simpler page -- essentially refering folks to their build system of choice. --- source/single_source_version.rst | 51 ++++++++++++++++++++++++++++++++ 1 file changed, 51 insertions(+) create mode 100644 source/single_source_version.rst diff --git a/source/single_source_version.rst b/source/single_source_version.rst new file mode 100644 index 000000000..206ff5020 --- /dev/null +++ b/source/single_source_version.rst @@ -0,0 +1,51 @@ +.. _`Single sourcing the version`: + +=================================== +Single-sourcing the Project Version +=================================== + +:Page Status: Complete +:Last Reviewed: 2015-09-08 + +One of the challenges in building packages is that the version string can be required in multiple places. + +* It needs to be specified when building the package (e.g. in pyproject.toml) + - That will assure that it is properly assigned in the distribution file name, and in teh installed package. + +* Some projects require that there be a version string available as an attribute in the importable module, e.g:: + + import a_package + print(a_package.__version__) + +While different projects have different needs, it's important to make sure that there is a single source of truth for the version number. + +In general, the options are: + +1) If the code is in a version control system (VCS), e.g. git, then the version can be extracted from the VCS. + +2) The version can be hard-coded into the `pyproject.toml` file -- and the build system can copy it into other locations it may be required. + +3) The version string can be hard-coded into the source code -- either in a special purpose file, such as `_version.txt`, or as a attribute in the `__init__.py`, and the build system can extract it at build time. + +If the version string is not in the source, it can be extracted at runtime with code in `__init__.py`, such as:: + + import importlib.metadata + __version__ = importlib.metadata.version('the_distribution_name') + + +Consult your build system documentation for how to implement your preferred method. + +Put links in to build system docs? +-- I have no idea which are currently robust and maintained -- do we want to get into seeming endorsing particular tools in this doc? + + +* setuptools: + +* hatch: + +* poetry: + +* PyBuilder: + +* Others? + From ce0d4bc9951776e01c55189868dac892b3045c56 Mon Sep 17 00:00:00 2001 From: Chris Barker Date: Thu, 25 Jul 2024 11:17:19 -0700 Subject: [PATCH 069/121] Update source/single_source_version.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Sviatoslav Sydorenko (Святослав Сидоренко) --- source/single_source_version.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/single_source_version.rst b/source/single_source_version.rst index 206ff5020..766247711 100644 --- a/source/single_source_version.rst +++ b/source/single_source_version.rst @@ -9,7 +9,7 @@ Single-sourcing the Project Version One of the challenges in building packages is that the version string can be required in multiple places. -* It needs to be specified when building the package (e.g. in pyproject.toml) +* It needs to be specified when building the package (e.g. in :file:`pyproject.toml`) - That will assure that it is properly assigned in the distribution file name, and in teh installed package. * Some projects require that there be a version string available as an attribute in the importable module, e.g:: From 6cd1b9bb78a9819cab9e74bb6ca735c613e1d983 Mon Sep 17 00:00:00 2001 From: Chris Barker Date: Thu, 25 Jul 2024 11:20:08 -0700 Subject: [PATCH 070/121] Update source/single_source_version.rst Co-authored-by: Thomas A Caswell --- source/single_source_version.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/source/single_source_version.rst b/source/single_source_version.rst index 766247711..c075e56a9 100644 --- a/source/single_source_version.rst +++ b/source/single_source_version.rst @@ -16,6 +16,7 @@ One of the challenges in building packages is that the version string can be req import a_package print(a_package.__version__) +* In the metadata of the artifacts for each of the packaging ecosystems While different projects have different needs, it's important to make sure that there is a single source of truth for the version number. From dbac2356e9d71ee70dc8f3813d44370e0dbffd45 Mon Sep 17 00:00:00 2001 From: Chris Barker Date: Thu, 25 Jul 2024 14:51:07 -0700 Subject: [PATCH 071/121] Added links to build tools --- source/single_source_version.rst | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/source/single_source_version.rst b/source/single_source_version.rst index c075e56a9..e307dd5a7 100644 --- a/source/single_source_version.rst +++ b/source/single_source_version.rst @@ -10,12 +10,13 @@ Single-sourcing the Project Version One of the challenges in building packages is that the version string can be required in multiple places. * It needs to be specified when building the package (e.g. in :file:`pyproject.toml`) - - That will assure that it is properly assigned in the distribution file name, and in teh installed package. + - That will assure that it is properly assigned in the distribution file name, and in the installed package. * Some projects require that there be a version string available as an attribute in the importable module, e.g:: import a_package print(a_package.__version__) + * In the metadata of the artifacts for each of the packaging ecosystems While different projects have different needs, it's important to make sure that there is a single source of truth for the version number. @@ -36,17 +37,15 @@ If the version string is not in the source, it can be extracted at runtime with Consult your build system documentation for how to implement your preferred method. -Put links in to build system docs? --- I have no idea which are currently robust and maintained -- do we want to get into seeming endorsing particular tools in this doc? - +Here are the common ones: -* setuptools: +* `Hatch `_ -* hatch: +* `Setuptools `_ -* poetry: + - `setuptools_scm `_ -* PyBuilder: +* `Flit `_ -* Others? +* `PDM `_ From 438198fafd7fccc1bf76f2fb6191e244961be1ad Mon Sep 17 00:00:00 2001 From: Chris Barker Date: Thu, 25 Jul 2024 14:53:58 -0700 Subject: [PATCH 072/121] swap prefer for require --- source/single_source_version.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/single_source_version.rst b/source/single_source_version.rst index e307dd5a7..46954a8e2 100644 --- a/source/single_source_version.rst +++ b/source/single_source_version.rst @@ -12,7 +12,7 @@ One of the challenges in building packages is that the version string can be req * It needs to be specified when building the package (e.g. in :file:`pyproject.toml`) - That will assure that it is properly assigned in the distribution file name, and in the installed package. -* Some projects require that there be a version string available as an attribute in the importable module, e.g:: +* Some projects prefer that there be a version string available as an attribute in the importable module, e.g:: import a_package print(a_package.__version__) From 51e2c23fa69792d318e388bdf96cbb8c00eafa65 Mon Sep 17 00:00:00 2001 From: Chris Barker Date: Thu, 25 Jul 2024 15:11:36 -0700 Subject: [PATCH 073/121] replace text about __version__ --- source/single_source_version.rst | 22 +++++++++------------- 1 file changed, 9 insertions(+), 13 deletions(-) diff --git a/source/single_source_version.rst b/source/single_source_version.rst index 46954a8e2..8a2eb5cf8 100644 --- a/source/single_source_version.rst +++ b/source/single_source_version.rst @@ -9,15 +9,13 @@ Single-sourcing the Project Version One of the challenges in building packages is that the version string can be required in multiple places. -* It needs to be specified when building the package (e.g. in :file:`pyproject.toml`) +* It needs to be specified when building the package (e.g. in :file:``pyproject.toml``) - That will assure that it is properly assigned in the distribution file name, and in the installed package. -* Some projects prefer that there be a version string available as an attribute in the importable module, e.g:: +* A package may, if the maintainers think it useful, to be able to determine the version of the package from Python code without relying on a package manager's metadata, set a top level ``__version__`` attribute. +The value of ``__version__`` attribute and that passed to the build system can (and should) be kept in sync in :ref:`the build systems's recommended way `. - import a_package - print(a_package.__version__) - -* In the metadata of the artifacts for each of the packaging ecosystems +Should a package not set a top level ``__version__`` attribute, the version can still be accessed using ``importlib.metadata.version("distribution_name")``. While different projects have different needs, it's important to make sure that there is a single source of truth for the version number. @@ -27,17 +25,15 @@ In general, the options are: 2) The version can be hard-coded into the `pyproject.toml` file -- and the build system can copy it into other locations it may be required. -3) The version string can be hard-coded into the source code -- either in a special purpose file, such as `_version.txt`, or as a attribute in the `__init__.py`, and the build system can extract it at build time. - -If the version string is not in the source, it can be extracted at runtime with code in `__init__.py`, such as:: - - import importlib.metadata - __version__ = importlib.metadata.version('the_distribution_name') +3) The version string can be hard-coded into the source code -- either in a special purpose file, such as ``_version.txt``, or as a attribute in the ``__init__.py``, and the build system can extract it at build time. Consult your build system documentation for how to implement your preferred method. -Here are the common ones: +.. _how_to_set_version_links: + +Build System Version Handling +---------------------------- * `Hatch `_ From 6d4aeb3b602f5987843cec7db024a725364f1ed9 Mon Sep 17 00:00:00 2001 From: Chris Barker Date: Fri, 26 Jul 2024 09:39:32 -0700 Subject: [PATCH 074/121] Update source/single_source_version.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Brénainn Woodsend --- source/single_source_version.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/single_source_version.rst b/source/single_source_version.rst index 8a2eb5cf8..2f5f0bc60 100644 --- a/source/single_source_version.rst +++ b/source/single_source_version.rst @@ -28,7 +28,7 @@ In general, the options are: 3) The version string can be hard-coded into the source code -- either in a special purpose file, such as ``_version.txt``, or as a attribute in the ``__init__.py``, and the build system can extract it at build time. -Consult your build system documentation for how to implement your preferred method. +Consult your build system's documentation for their recommended method. .. _how_to_set_version_links: From 49e743d1b91866b7ab22677ae88c87dfc7a362c5 Mon Sep 17 00:00:00 2001 From: Chris Barker Date: Fri, 26 Jul 2024 10:01:56 -0700 Subject: [PATCH 075/121] Update source/single_source_version.rst Co-authored-by: Thomas A Caswell --- source/single_source_version.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/single_source_version.rst b/source/single_source_version.rst index 2f5f0bc60..431b8ec62 100644 --- a/source/single_source_version.rst +++ b/source/single_source_version.rst @@ -15,7 +15,7 @@ One of the challenges in building packages is that the version string can be req * A package may, if the maintainers think it useful, to be able to determine the version of the package from Python code without relying on a package manager's metadata, set a top level ``__version__`` attribute. The value of ``__version__`` attribute and that passed to the build system can (and should) be kept in sync in :ref:`the build systems's recommended way `. -Should a package not set a top level ``__version__`` attribute, the version can still be accessed using ``importlib.metadata.version("distribution_name")``. +In the cases where a package does not set a top level ``__version__`` attribute, the version may still be accessible using ``importlib.metadata.version("distribution_name")``. While different projects have different needs, it's important to make sure that there is a single source of truth for the version number. From 0598c698d133c4679d2535907119f82eb66c0f00 Mon Sep 17 00:00:00 2001 From: Chris Barker Date: Fri, 26 Jul 2024 10:02:18 -0700 Subject: [PATCH 076/121] Update source/single_source_version.rst Co-authored-by: Thomas A Caswell --- source/single_source_version.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/single_source_version.rst b/source/single_source_version.rst index 431b8ec62..ac5c62445 100644 --- a/source/single_source_version.rst +++ b/source/single_source_version.rst @@ -17,7 +17,7 @@ The value of ``__version__`` attribute and that passed to the build system can ( In the cases where a package does not set a top level ``__version__`` attribute, the version may still be accessible using ``importlib.metadata.version("distribution_name")``. -While different projects have different needs, it's important to make sure that there is a single source of truth for the version number. +To ensure that version numbers do not get out of sync, it is recommended that there is a single source of truth for the version number. In general, the options are: From 2a3249985cc35c9ed6f5b632cb2071bf804bdbd7 Mon Sep 17 00:00:00 2001 From: Chris Barker Date: Fri, 26 Jul 2024 10:31:38 -0700 Subject: [PATCH 077/121] updated the __version__ description --- source/single_source_version.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/source/single_source_version.rst b/source/single_source_version.rst index ac5c62445..682ab8d22 100644 --- a/source/single_source_version.rst +++ b/source/single_source_version.rst @@ -12,8 +12,7 @@ One of the challenges in building packages is that the version string can be req * It needs to be specified when building the package (e.g. in :file:``pyproject.toml``) - That will assure that it is properly assigned in the distribution file name, and in the installed package. -* A package may, if the maintainers think it useful, to be able to determine the version of the package from Python code without relying on a package manager's metadata, set a top level ``__version__`` attribute. -The value of ``__version__`` attribute and that passed to the build system can (and should) be kept in sync in :ref:`the build systems's recommended way `. +* A package may set a top level ``__version__`` attribute to provide runtime access to the version of the installed package. If this is done, the value of ``__version__`` attribute and that used by the build system to set the distribution's version should be kept in sync in :ref:`the build systems's recommended way `. In the cases where a package does not set a top level ``__version__`` attribute, the version may still be accessible using ``importlib.metadata.version("distribution_name")``. From d1cbce9c0d6acb5caeee8d59811c4b96cfebe652 Mon Sep 17 00:00:00 2001 From: Chris Barker Date: Tue, 30 Jul 2024 13:08:40 -0700 Subject: [PATCH 078/121] a few suggestions from the PR discussion --- source/single_source_version.rst | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/source/single_source_version.rst b/source/single_source_version.rst index 682ab8d22..63bc3f870 100644 --- a/source/single_source_version.rst +++ b/source/single_source_version.rst @@ -5,7 +5,7 @@ Single-sourcing the Project Version =================================== :Page Status: Complete -:Last Reviewed: 2015-09-08 +:Last Reviewed: 2024-?? One of the challenges in building packages is that the version string can be required in multiple places. @@ -34,13 +34,15 @@ Consult your build system's documentation for their recommended method. Build System Version Handling ---------------------------- -* `Hatch `_ +* `Flit `_ + +* `Hatchling `_ + +* `PDM `_ * `Setuptools `_ - `setuptools_scm `_ -* `Flit `_ -* `PDM `_ From 0fc5aca7f34220df01f482412dd59d89371877ff Mon Sep 17 00:00:00 2001 From: Chris Barker Date: Tue, 30 Jul 2024 11:14:57 -0700 Subject: [PATCH 079/121] Update source/single_source_version.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Sviatoslav Sydorenko (Святослав Сидоренко) --- source/single_source_version.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/single_source_version.rst b/source/single_source_version.rst index 63bc3f870..866073ab9 100644 --- a/source/single_source_version.rst +++ b/source/single_source_version.rst @@ -22,7 +22,7 @@ In general, the options are: 1) If the code is in a version control system (VCS), e.g. git, then the version can be extracted from the VCS. -2) The version can be hard-coded into the `pyproject.toml` file -- and the build system can copy it into other locations it may be required. +2) The version can be hard-coded into the :file:`pyproject.toml` file -- and the build system can copy it into other locations it may be required. 3) The version string can be hard-coded into the source code -- either in a special purpose file, such as ``_version.txt``, or as a attribute in the ``__init__.py``, and the build system can extract it at build time. From 7d60695531dc8adbe65f42cd27d36bd3a988c9cb Mon Sep 17 00:00:00 2001 From: Chris Barker Date: Tue, 30 Jul 2024 11:15:18 -0700 Subject: [PATCH 080/121] Update source/single_source_version.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Sviatoslav Sydorenko (Святослав Сидоренко) --- source/single_source_version.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/single_source_version.rst b/source/single_source_version.rst index 866073ab9..0fa7488c7 100644 --- a/source/single_source_version.rst +++ b/source/single_source_version.rst @@ -10,7 +10,7 @@ Single-sourcing the Project Version One of the challenges in building packages is that the version string can be required in multiple places. * It needs to be specified when building the package (e.g. in :file:``pyproject.toml``) - - That will assure that it is properly assigned in the distribution file name, and in the installed package. + - That will assure that it is properly assigned in the distribution file name, and in the installed package metadata. * A package may set a top level ``__version__`` attribute to provide runtime access to the version of the installed package. If this is done, the value of ``__version__`` attribute and that used by the build system to set the distribution's version should be kept in sync in :ref:`the build systems's recommended way `. From 28c8bcbd0e05edc8c728750327b81d3f0f356827 Mon Sep 17 00:00:00 2001 From: Chris Barker Date: Tue, 30 Jul 2024 11:59:12 -0700 Subject: [PATCH 081/121] Update source/single_source_version.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Sviatoslav Sydorenko (Святослав Сидоренко) --- source/single_source_version.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/single_source_version.rst b/source/single_source_version.rst index 0fa7488c7..a77183a27 100644 --- a/source/single_source_version.rst +++ b/source/single_source_version.rst @@ -9,7 +9,7 @@ Single-sourcing the Project Version One of the challenges in building packages is that the version string can be required in multiple places. -* It needs to be specified when building the package (e.g. in :file:``pyproject.toml``) +* It needs to be specified when building the package (e.g. in :file:`pyproject.toml`) - That will assure that it is properly assigned in the distribution file name, and in the installed package metadata. * A package may set a top level ``__version__`` attribute to provide runtime access to the version of the installed package. If this is done, the value of ``__version__`` attribute and that used by the build system to set the distribution's version should be kept in sync in :ref:`the build systems's recommended way `. From 00d86455f7cacd33ebf3798e6973d0b1b8ee4246 Mon Sep 17 00:00:00 2001 From: Chris Barker Date: Tue, 30 Jul 2024 11:59:28 -0700 Subject: [PATCH 082/121] Update source/single_source_version.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Sviatoslav Sydorenko (Святослав Сидоренко) --- source/single_source_version.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/single_source_version.rst b/source/single_source_version.rst index a77183a27..0e5034b5d 100644 --- a/source/single_source_version.rst +++ b/source/single_source_version.rst @@ -24,7 +24,7 @@ In general, the options are: 2) The version can be hard-coded into the :file:`pyproject.toml` file -- and the build system can copy it into other locations it may be required. -3) The version string can be hard-coded into the source code -- either in a special purpose file, such as ``_version.txt``, or as a attribute in the ``__init__.py``, and the build system can extract it at build time. +3) The version string can be hard-coded into the source code -- either in a special purpose file, such as :file:`_version.txt`, or as a attribute in the :file:`__init__.py`, and the build system can extract it at build time. Consult your build system's documentation for their recommended method. From 50a588f3b8ba35be43fb5090f436bd71d45d9de8 Mon Sep 17 00:00:00 2001 From: Chris Barker Date: Tue, 30 Jul 2024 12:15:02 -0700 Subject: [PATCH 083/121] Update source/single_source_version.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Sviatoslav Sydorenko (Святослав Сидоренко) --- source/single_source_version.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/single_source_version.rst b/source/single_source_version.rst index 0e5034b5d..974a09a68 100644 --- a/source/single_source_version.rst +++ b/source/single_source_version.rst @@ -20,7 +20,7 @@ To ensure that version numbers do not get out of sync, it is recommended that th In general, the options are: -1) If the code is in a version control system (VCS), e.g. git, then the version can be extracted from the VCS. +1) If the code is in a version control system (VCS), e.g. Git, then the version can be extracted from the VCS. 2) The version can be hard-coded into the :file:`pyproject.toml` file -- and the build system can copy it into other locations it may be required. From db4e9884b67e10e9f08aac7955c41d7116650bc9 Mon Sep 17 00:00:00 2001 From: Chris Barker Date: Tue, 30 Jul 2024 13:13:49 -0700 Subject: [PATCH 084/121] minor formatting edit --- source/single_source_version.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/single_source_version.rst b/source/single_source_version.rst index 974a09a68..28d963858 100644 --- a/source/single_source_version.rst +++ b/source/single_source_version.rst @@ -32,7 +32,7 @@ Consult your build system's documentation for their recommended method. .. _how_to_set_version_links: Build System Version Handling ----------------------------- +----------------------------- * `Flit `_ From 83c7f246e1889b5156d8ff1fd95f375ab0fa727e Mon Sep 17 00:00:00 2001 From: Chris Barker Date: Wed, 31 Jul 2024 15:04:58 -0700 Subject: [PATCH 085/121] Update source/single_source_version.rst Co-authored-by: Thomas A Caswell --- source/single_source_version.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/single_source_version.rst b/source/single_source_version.rst index 28d963858..0a3c234be 100644 --- a/source/single_source_version.rst +++ b/source/single_source_version.rst @@ -12,7 +12,7 @@ One of the challenges in building packages is that the version string can be req * It needs to be specified when building the package (e.g. in :file:`pyproject.toml`) - That will assure that it is properly assigned in the distribution file name, and in the installed package metadata. -* A package may set a top level ``__version__`` attribute to provide runtime access to the version of the installed package. If this is done, the value of ``__version__`` attribute and that used by the build system to set the distribution's version should be kept in sync in :ref:`the build systems's recommended way `. +* A package may set a top level ``__version__`` attribute to provide runtime access to the version of the imported package. If this is done, the value of ``__version__`` attribute and that used by the build system to set the distribution's version should be kept in sync in :ref:`the build systems's recommended way `. In the cases where a package does not set a top level ``__version__`` attribute, the version may still be accessible using ``importlib.metadata.version("distribution_name")``. From a1df94c25b95c482a5b9a62b5b6e632eff12fe85 Mon Sep 17 00:00:00 2001 From: Chris Barker Date: Wed, 31 Jul 2024 15:25:49 -0700 Subject: [PATCH 086/121] a few more edits from the PR comments, and adding it back to the index (in the right place?) --- source/single_source_version.rst | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/source/single_source_version.rst b/source/single_source_version.rst index 0a3c234be..3eea6af50 100644 --- a/source/single_source_version.rst +++ b/source/single_source_version.rst @@ -12,9 +12,9 @@ One of the challenges in building packages is that the version string can be req * It needs to be specified when building the package (e.g. in :file:`pyproject.toml`) - That will assure that it is properly assigned in the distribution file name, and in the installed package metadata. -* A package may set a top level ``__version__`` attribute to provide runtime access to the version of the imported package. If this is done, the value of ``__version__`` attribute and that used by the build system to set the distribution's version should be kept in sync in :ref:`the build systems's recommended way `. +* A package may set a top level ``__version__`` attribute to provide runtime access to the version of the imported package. If this is done, the value of ``__version__`` attribute and that used by the build system to set the distribution's version should be kept in sync in :ref:`the build systems's recommended way `. -In the cases where a package does not set a top level ``__version__`` attribute, the version may still be accessible using ``importlib.metadata.version("distribution_name")``. +In any case, The installed distribution version should be accessible using ``importlib.metadata.version("distribution_name")``. To ensure that version numbers do not get out of sync, it is recommended that there is a single source of truth for the version number. @@ -29,11 +29,13 @@ In general, the options are: Consult your build system's documentation for their recommended method. -.. _how_to_set_version_links: +.. _Build system version handling: Build System Version Handling ----------------------------- +The following are links to some build system's documentation for handling version strings. + * `Flit `_ * `Hatchling `_ From ba32cc627044665cccab4d3fe0ac30bf716ac85c Mon Sep 17 00:00:00 2001 From: Chris Barker Date: Wed, 31 Jul 2024 16:58:17 -0700 Subject: [PATCH 087/121] added single_source page back in -- not sure if it's the right section. --- source/discussions/index.rst | 1 + source/{ => discussions}/single_source_version.rst | 0 2 files changed, 1 insertion(+) rename source/{ => discussions}/single_source_version.rst (100%) diff --git a/source/discussions/index.rst b/source/discussions/index.rst index bc1154507..907b61403 100644 --- a/source/discussions/index.rst +++ b/source/discussions/index.rst @@ -13,3 +13,4 @@ specific topic. If you're just trying to get stuff done, see install-requires-vs-requirements wheel-vs-egg src-layout-vs-flat-layout + single_source_version diff --git a/source/single_source_version.rst b/source/discussions/single_source_version.rst similarity index 100% rename from source/single_source_version.rst rename to source/discussions/single_source_version.rst From 476f9160889801d91a6d1e6cf2fa6aba14070c97 Mon Sep 17 00:00:00 2001 From: Chris Barker Date: Thu, 25 Jul 2024 09:34:31 -0700 Subject: [PATCH 088/121] updated single_source_version with a much simpler page -- essentially refering folks to their build system of choice. --- source/single_source_version.rst | 51 ++++++++++++++++++++++++++++++++ 1 file changed, 51 insertions(+) create mode 100644 source/single_source_version.rst diff --git a/source/single_source_version.rst b/source/single_source_version.rst new file mode 100644 index 000000000..206ff5020 --- /dev/null +++ b/source/single_source_version.rst @@ -0,0 +1,51 @@ +.. _`Single sourcing the version`: + +=================================== +Single-sourcing the Project Version +=================================== + +:Page Status: Complete +:Last Reviewed: 2015-09-08 + +One of the challenges in building packages is that the version string can be required in multiple places. + +* It needs to be specified when building the package (e.g. in pyproject.toml) + - That will assure that it is properly assigned in the distribution file name, and in teh installed package. + +* Some projects require that there be a version string available as an attribute in the importable module, e.g:: + + import a_package + print(a_package.__version__) + +While different projects have different needs, it's important to make sure that there is a single source of truth for the version number. + +In general, the options are: + +1) If the code is in a version control system (VCS), e.g. git, then the version can be extracted from the VCS. + +2) The version can be hard-coded into the `pyproject.toml` file -- and the build system can copy it into other locations it may be required. + +3) The version string can be hard-coded into the source code -- either in a special purpose file, such as `_version.txt`, or as a attribute in the `__init__.py`, and the build system can extract it at build time. + +If the version string is not in the source, it can be extracted at runtime with code in `__init__.py`, such as:: + + import importlib.metadata + __version__ = importlib.metadata.version('the_distribution_name') + + +Consult your build system documentation for how to implement your preferred method. + +Put links in to build system docs? +-- I have no idea which are currently robust and maintained -- do we want to get into seeming endorsing particular tools in this doc? + + +* setuptools: + +* hatch: + +* poetry: + +* PyBuilder: + +* Others? + From 0512c222a23ca9118657dc70d20e519c6840f804 Mon Sep 17 00:00:00 2001 From: Chris Barker Date: Thu, 25 Jul 2024 11:17:19 -0700 Subject: [PATCH 089/121] Update source/single_source_version.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Sviatoslav Sydorenko (Святослав Сидоренко) --- source/single_source_version.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/single_source_version.rst b/source/single_source_version.rst index 206ff5020..766247711 100644 --- a/source/single_source_version.rst +++ b/source/single_source_version.rst @@ -9,7 +9,7 @@ Single-sourcing the Project Version One of the challenges in building packages is that the version string can be required in multiple places. -* It needs to be specified when building the package (e.g. in pyproject.toml) +* It needs to be specified when building the package (e.g. in :file:`pyproject.toml`) - That will assure that it is properly assigned in the distribution file name, and in teh installed package. * Some projects require that there be a version string available as an attribute in the importable module, e.g:: From 892d0454094b85fcfb09db855223a2178215143a Mon Sep 17 00:00:00 2001 From: Chris Barker Date: Thu, 25 Jul 2024 11:20:08 -0700 Subject: [PATCH 090/121] Update source/single_source_version.rst Co-authored-by: Thomas A Caswell --- source/single_source_version.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/source/single_source_version.rst b/source/single_source_version.rst index 766247711..c075e56a9 100644 --- a/source/single_source_version.rst +++ b/source/single_source_version.rst @@ -16,6 +16,7 @@ One of the challenges in building packages is that the version string can be req import a_package print(a_package.__version__) +* In the metadata of the artifacts for each of the packaging ecosystems While different projects have different needs, it's important to make sure that there is a single source of truth for the version number. From 6db49ef0cda4b869604679895024fe39f54882b7 Mon Sep 17 00:00:00 2001 From: Chris Barker Date: Thu, 25 Jul 2024 14:51:07 -0700 Subject: [PATCH 091/121] Added links to build tools --- source/single_source_version.rst | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/source/single_source_version.rst b/source/single_source_version.rst index c075e56a9..e307dd5a7 100644 --- a/source/single_source_version.rst +++ b/source/single_source_version.rst @@ -10,12 +10,13 @@ Single-sourcing the Project Version One of the challenges in building packages is that the version string can be required in multiple places. * It needs to be specified when building the package (e.g. in :file:`pyproject.toml`) - - That will assure that it is properly assigned in the distribution file name, and in teh installed package. + - That will assure that it is properly assigned in the distribution file name, and in the installed package. * Some projects require that there be a version string available as an attribute in the importable module, e.g:: import a_package print(a_package.__version__) + * In the metadata of the artifacts for each of the packaging ecosystems While different projects have different needs, it's important to make sure that there is a single source of truth for the version number. @@ -36,17 +37,15 @@ If the version string is not in the source, it can be extracted at runtime with Consult your build system documentation for how to implement your preferred method. -Put links in to build system docs? --- I have no idea which are currently robust and maintained -- do we want to get into seeming endorsing particular tools in this doc? - +Here are the common ones: -* setuptools: +* `Hatch `_ -* hatch: +* `Setuptools `_ -* poetry: + - `setuptools_scm `_ -* PyBuilder: +* `Flit `_ -* Others? +* `PDM `_ From afa38c49a3f65d1c364021a46400ded3f4ac9b19 Mon Sep 17 00:00:00 2001 From: Chris Barker Date: Thu, 25 Jul 2024 14:53:58 -0700 Subject: [PATCH 092/121] swap prefer for require --- source/single_source_version.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/single_source_version.rst b/source/single_source_version.rst index e307dd5a7..46954a8e2 100644 --- a/source/single_source_version.rst +++ b/source/single_source_version.rst @@ -12,7 +12,7 @@ One of the challenges in building packages is that the version string can be req * It needs to be specified when building the package (e.g. in :file:`pyproject.toml`) - That will assure that it is properly assigned in the distribution file name, and in the installed package. -* Some projects require that there be a version string available as an attribute in the importable module, e.g:: +* Some projects prefer that there be a version string available as an attribute in the importable module, e.g:: import a_package print(a_package.__version__) From b9bb45d3fd7d9c6ce47fb44407f59dba3a66d1c2 Mon Sep 17 00:00:00 2001 From: Chris Barker Date: Thu, 25 Jul 2024 15:11:36 -0700 Subject: [PATCH 093/121] replace text about __version__ --- source/single_source_version.rst | 22 +++++++++------------- 1 file changed, 9 insertions(+), 13 deletions(-) diff --git a/source/single_source_version.rst b/source/single_source_version.rst index 46954a8e2..8a2eb5cf8 100644 --- a/source/single_source_version.rst +++ b/source/single_source_version.rst @@ -9,15 +9,13 @@ Single-sourcing the Project Version One of the challenges in building packages is that the version string can be required in multiple places. -* It needs to be specified when building the package (e.g. in :file:`pyproject.toml`) +* It needs to be specified when building the package (e.g. in :file:``pyproject.toml``) - That will assure that it is properly assigned in the distribution file name, and in the installed package. -* Some projects prefer that there be a version string available as an attribute in the importable module, e.g:: +* A package may, if the maintainers think it useful, to be able to determine the version of the package from Python code without relying on a package manager's metadata, set a top level ``__version__`` attribute. +The value of ``__version__`` attribute and that passed to the build system can (and should) be kept in sync in :ref:`the build systems's recommended way `. - import a_package - print(a_package.__version__) - -* In the metadata of the artifacts for each of the packaging ecosystems +Should a package not set a top level ``__version__`` attribute, the version can still be accessed using ``importlib.metadata.version("distribution_name")``. While different projects have different needs, it's important to make sure that there is a single source of truth for the version number. @@ -27,17 +25,15 @@ In general, the options are: 2) The version can be hard-coded into the `pyproject.toml` file -- and the build system can copy it into other locations it may be required. -3) The version string can be hard-coded into the source code -- either in a special purpose file, such as `_version.txt`, or as a attribute in the `__init__.py`, and the build system can extract it at build time. - -If the version string is not in the source, it can be extracted at runtime with code in `__init__.py`, such as:: - - import importlib.metadata - __version__ = importlib.metadata.version('the_distribution_name') +3) The version string can be hard-coded into the source code -- either in a special purpose file, such as ``_version.txt``, or as a attribute in the ``__init__.py``, and the build system can extract it at build time. Consult your build system documentation for how to implement your preferred method. -Here are the common ones: +.. _how_to_set_version_links: + +Build System Version Handling +---------------------------- * `Hatch `_ From 635908378ba7759579afcf509d50cf9166df67b2 Mon Sep 17 00:00:00 2001 From: Chris Barker Date: Fri, 26 Jul 2024 09:39:32 -0700 Subject: [PATCH 094/121] Update source/single_source_version.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Brénainn Woodsend --- source/single_source_version.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/single_source_version.rst b/source/single_source_version.rst index 8a2eb5cf8..2f5f0bc60 100644 --- a/source/single_source_version.rst +++ b/source/single_source_version.rst @@ -28,7 +28,7 @@ In general, the options are: 3) The version string can be hard-coded into the source code -- either in a special purpose file, such as ``_version.txt``, or as a attribute in the ``__init__.py``, and the build system can extract it at build time. -Consult your build system documentation for how to implement your preferred method. +Consult your build system's documentation for their recommended method. .. _how_to_set_version_links: From e6b0ed9b9cc471eef860670e38f8526e617b7a2a Mon Sep 17 00:00:00 2001 From: Chris Barker Date: Fri, 26 Jul 2024 10:01:56 -0700 Subject: [PATCH 095/121] Update source/single_source_version.rst Co-authored-by: Thomas A Caswell --- source/single_source_version.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/single_source_version.rst b/source/single_source_version.rst index 2f5f0bc60..431b8ec62 100644 --- a/source/single_source_version.rst +++ b/source/single_source_version.rst @@ -15,7 +15,7 @@ One of the challenges in building packages is that the version string can be req * A package may, if the maintainers think it useful, to be able to determine the version of the package from Python code without relying on a package manager's metadata, set a top level ``__version__`` attribute. The value of ``__version__`` attribute and that passed to the build system can (and should) be kept in sync in :ref:`the build systems's recommended way `. -Should a package not set a top level ``__version__`` attribute, the version can still be accessed using ``importlib.metadata.version("distribution_name")``. +In the cases where a package does not set a top level ``__version__`` attribute, the version may still be accessible using ``importlib.metadata.version("distribution_name")``. While different projects have different needs, it's important to make sure that there is a single source of truth for the version number. From 54906dae953b022672c13f6645d4273326a0e22f Mon Sep 17 00:00:00 2001 From: Chris Barker Date: Fri, 26 Jul 2024 10:02:18 -0700 Subject: [PATCH 096/121] Update source/single_source_version.rst Co-authored-by: Thomas A Caswell --- source/single_source_version.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/single_source_version.rst b/source/single_source_version.rst index 431b8ec62..ac5c62445 100644 --- a/source/single_source_version.rst +++ b/source/single_source_version.rst @@ -17,7 +17,7 @@ The value of ``__version__`` attribute and that passed to the build system can ( In the cases where a package does not set a top level ``__version__`` attribute, the version may still be accessible using ``importlib.metadata.version("distribution_name")``. -While different projects have different needs, it's important to make sure that there is a single source of truth for the version number. +To ensure that version numbers do not get out of sync, it is recommended that there is a single source of truth for the version number. In general, the options are: From 398b4fbc5d5f92d8fee80bffb8b724b90b96e4f3 Mon Sep 17 00:00:00 2001 From: Chris Barker Date: Fri, 26 Jul 2024 10:31:38 -0700 Subject: [PATCH 097/121] updated the __version__ description --- source/single_source_version.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/source/single_source_version.rst b/source/single_source_version.rst index ac5c62445..682ab8d22 100644 --- a/source/single_source_version.rst +++ b/source/single_source_version.rst @@ -12,8 +12,7 @@ One of the challenges in building packages is that the version string can be req * It needs to be specified when building the package (e.g. in :file:``pyproject.toml``) - That will assure that it is properly assigned in the distribution file name, and in the installed package. -* A package may, if the maintainers think it useful, to be able to determine the version of the package from Python code without relying on a package manager's metadata, set a top level ``__version__`` attribute. -The value of ``__version__`` attribute and that passed to the build system can (and should) be kept in sync in :ref:`the build systems's recommended way `. +* A package may set a top level ``__version__`` attribute to provide runtime access to the version of the installed package. If this is done, the value of ``__version__`` attribute and that used by the build system to set the distribution's version should be kept in sync in :ref:`the build systems's recommended way `. In the cases where a package does not set a top level ``__version__`` attribute, the version may still be accessible using ``importlib.metadata.version("distribution_name")``. From e7d23699b39f4cffcc8a1619f375334f88a207a0 Mon Sep 17 00:00:00 2001 From: Chris Barker Date: Tue, 30 Jul 2024 13:08:40 -0700 Subject: [PATCH 098/121] a few suggestions from the PR discussion --- source/single_source_version.rst | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/source/single_source_version.rst b/source/single_source_version.rst index 682ab8d22..63bc3f870 100644 --- a/source/single_source_version.rst +++ b/source/single_source_version.rst @@ -5,7 +5,7 @@ Single-sourcing the Project Version =================================== :Page Status: Complete -:Last Reviewed: 2015-09-08 +:Last Reviewed: 2024-?? One of the challenges in building packages is that the version string can be required in multiple places. @@ -34,13 +34,15 @@ Consult your build system's documentation for their recommended method. Build System Version Handling ---------------------------- -* `Hatch `_ +* `Flit `_ + +* `Hatchling `_ + +* `PDM `_ * `Setuptools `_ - `setuptools_scm `_ -* `Flit `_ -* `PDM `_ From 0ff8c16eb5605d4350b9ae0c3c4f93e0f450dcb9 Mon Sep 17 00:00:00 2001 From: Chris Barker Date: Tue, 30 Jul 2024 11:14:57 -0700 Subject: [PATCH 099/121] Update source/single_source_version.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Sviatoslav Sydorenko (Святослав Сидоренко) --- source/single_source_version.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/single_source_version.rst b/source/single_source_version.rst index 63bc3f870..866073ab9 100644 --- a/source/single_source_version.rst +++ b/source/single_source_version.rst @@ -22,7 +22,7 @@ In general, the options are: 1) If the code is in a version control system (VCS), e.g. git, then the version can be extracted from the VCS. -2) The version can be hard-coded into the `pyproject.toml` file -- and the build system can copy it into other locations it may be required. +2) The version can be hard-coded into the :file:`pyproject.toml` file -- and the build system can copy it into other locations it may be required. 3) The version string can be hard-coded into the source code -- either in a special purpose file, such as ``_version.txt``, or as a attribute in the ``__init__.py``, and the build system can extract it at build time. From 8529adad95a8e095bf39736918384874306556db Mon Sep 17 00:00:00 2001 From: Chris Barker Date: Tue, 30 Jul 2024 11:15:18 -0700 Subject: [PATCH 100/121] Update source/single_source_version.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Sviatoslav Sydorenko (Святослав Сидоренко) --- source/single_source_version.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/single_source_version.rst b/source/single_source_version.rst index 866073ab9..0fa7488c7 100644 --- a/source/single_source_version.rst +++ b/source/single_source_version.rst @@ -10,7 +10,7 @@ Single-sourcing the Project Version One of the challenges in building packages is that the version string can be required in multiple places. * It needs to be specified when building the package (e.g. in :file:``pyproject.toml``) - - That will assure that it is properly assigned in the distribution file name, and in the installed package. + - That will assure that it is properly assigned in the distribution file name, and in the installed package metadata. * A package may set a top level ``__version__`` attribute to provide runtime access to the version of the installed package. If this is done, the value of ``__version__`` attribute and that used by the build system to set the distribution's version should be kept in sync in :ref:`the build systems's recommended way `. From 840474d649b870236722c9bf72e1341a3b9eaee8 Mon Sep 17 00:00:00 2001 From: Chris Barker Date: Tue, 30 Jul 2024 11:59:12 -0700 Subject: [PATCH 101/121] Update source/single_source_version.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Sviatoslav Sydorenko (Святослав Сидоренко) --- source/single_source_version.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/single_source_version.rst b/source/single_source_version.rst index 0fa7488c7..a77183a27 100644 --- a/source/single_source_version.rst +++ b/source/single_source_version.rst @@ -9,7 +9,7 @@ Single-sourcing the Project Version One of the challenges in building packages is that the version string can be required in multiple places. -* It needs to be specified when building the package (e.g. in :file:``pyproject.toml``) +* It needs to be specified when building the package (e.g. in :file:`pyproject.toml`) - That will assure that it is properly assigned in the distribution file name, and in the installed package metadata. * A package may set a top level ``__version__`` attribute to provide runtime access to the version of the installed package. If this is done, the value of ``__version__`` attribute and that used by the build system to set the distribution's version should be kept in sync in :ref:`the build systems's recommended way `. From 61dc0b8a1bdffd1f5700126ffab11d4b772f9975 Mon Sep 17 00:00:00 2001 From: Chris Barker Date: Tue, 30 Jul 2024 11:59:28 -0700 Subject: [PATCH 102/121] Update source/single_source_version.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Sviatoslav Sydorenko (Святослав Сидоренко) --- source/single_source_version.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/single_source_version.rst b/source/single_source_version.rst index a77183a27..0e5034b5d 100644 --- a/source/single_source_version.rst +++ b/source/single_source_version.rst @@ -24,7 +24,7 @@ In general, the options are: 2) The version can be hard-coded into the :file:`pyproject.toml` file -- and the build system can copy it into other locations it may be required. -3) The version string can be hard-coded into the source code -- either in a special purpose file, such as ``_version.txt``, or as a attribute in the ``__init__.py``, and the build system can extract it at build time. +3) The version string can be hard-coded into the source code -- either in a special purpose file, such as :file:`_version.txt`, or as a attribute in the :file:`__init__.py`, and the build system can extract it at build time. Consult your build system's documentation for their recommended method. From f93293500062f2b1a86923b1132ea344052dad02 Mon Sep 17 00:00:00 2001 From: Chris Barker Date: Tue, 30 Jul 2024 12:15:02 -0700 Subject: [PATCH 103/121] Update source/single_source_version.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Sviatoslav Sydorenko (Святослав Сидоренко) --- source/single_source_version.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/single_source_version.rst b/source/single_source_version.rst index 0e5034b5d..974a09a68 100644 --- a/source/single_source_version.rst +++ b/source/single_source_version.rst @@ -20,7 +20,7 @@ To ensure that version numbers do not get out of sync, it is recommended that th In general, the options are: -1) If the code is in a version control system (VCS), e.g. git, then the version can be extracted from the VCS. +1) If the code is in a version control system (VCS), e.g. Git, then the version can be extracted from the VCS. 2) The version can be hard-coded into the :file:`pyproject.toml` file -- and the build system can copy it into other locations it may be required. From ae2ad095a85cebe23395e7554fa5ec47a42a28a8 Mon Sep 17 00:00:00 2001 From: Chris Barker Date: Tue, 30 Jul 2024 13:13:49 -0700 Subject: [PATCH 104/121] minor formatting edit --- source/single_source_version.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/single_source_version.rst b/source/single_source_version.rst index 974a09a68..28d963858 100644 --- a/source/single_source_version.rst +++ b/source/single_source_version.rst @@ -32,7 +32,7 @@ Consult your build system's documentation for their recommended method. .. _how_to_set_version_links: Build System Version Handling ----------------------------- +----------------------------- * `Flit `_ From 01f66a96054e5164a766238705d7fac3eb1d381b Mon Sep 17 00:00:00 2001 From: Chris Barker Date: Wed, 31 Jul 2024 15:04:58 -0700 Subject: [PATCH 105/121] Update source/single_source_version.rst Co-authored-by: Thomas A Caswell --- source/single_source_version.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/single_source_version.rst b/source/single_source_version.rst index 28d963858..0a3c234be 100644 --- a/source/single_source_version.rst +++ b/source/single_source_version.rst @@ -12,7 +12,7 @@ One of the challenges in building packages is that the version string can be req * It needs to be specified when building the package (e.g. in :file:`pyproject.toml`) - That will assure that it is properly assigned in the distribution file name, and in the installed package metadata. -* A package may set a top level ``__version__`` attribute to provide runtime access to the version of the installed package. If this is done, the value of ``__version__`` attribute and that used by the build system to set the distribution's version should be kept in sync in :ref:`the build systems's recommended way `. +* A package may set a top level ``__version__`` attribute to provide runtime access to the version of the imported package. If this is done, the value of ``__version__`` attribute and that used by the build system to set the distribution's version should be kept in sync in :ref:`the build systems's recommended way `. In the cases where a package does not set a top level ``__version__`` attribute, the version may still be accessible using ``importlib.metadata.version("distribution_name")``. From 9d353a75cc6b3b4171ca5dda95fb2e59a85afa64 Mon Sep 17 00:00:00 2001 From: Chris Barker Date: Wed, 31 Jul 2024 15:25:49 -0700 Subject: [PATCH 106/121] a few more edits from the PR comments, and adding it back to the index (in the right place?) --- source/single_source_version.rst | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/source/single_source_version.rst b/source/single_source_version.rst index 0a3c234be..3eea6af50 100644 --- a/source/single_source_version.rst +++ b/source/single_source_version.rst @@ -12,9 +12,9 @@ One of the challenges in building packages is that the version string can be req * It needs to be specified when building the package (e.g. in :file:`pyproject.toml`) - That will assure that it is properly assigned in the distribution file name, and in the installed package metadata. -* A package may set a top level ``__version__`` attribute to provide runtime access to the version of the imported package. If this is done, the value of ``__version__`` attribute and that used by the build system to set the distribution's version should be kept in sync in :ref:`the build systems's recommended way `. +* A package may set a top level ``__version__`` attribute to provide runtime access to the version of the imported package. If this is done, the value of ``__version__`` attribute and that used by the build system to set the distribution's version should be kept in sync in :ref:`the build systems's recommended way `. -In the cases where a package does not set a top level ``__version__`` attribute, the version may still be accessible using ``importlib.metadata.version("distribution_name")``. +In any case, The installed distribution version should be accessible using ``importlib.metadata.version("distribution_name")``. To ensure that version numbers do not get out of sync, it is recommended that there is a single source of truth for the version number. @@ -29,11 +29,13 @@ In general, the options are: Consult your build system's documentation for their recommended method. -.. _how_to_set_version_links: +.. _Build system version handling: Build System Version Handling ----------------------------- +The following are links to some build system's documentation for handling version strings. + * `Flit `_ * `Hatchling `_ From 1aae700cd7adf7e2c387c1af9ca0b25ad7c3bb16 Mon Sep 17 00:00:00 2001 From: Chris Barker Date: Wed, 31 Jul 2024 16:58:17 -0700 Subject: [PATCH 107/121] added single_source page back in -- not sure if it's the right section. --- source/discussions/index.rst | 1 + source/{ => discussions}/single_source_version.rst | 0 2 files changed, 1 insertion(+) rename source/{ => discussions}/single_source_version.rst (100%) diff --git a/source/discussions/index.rst b/source/discussions/index.rst index d262bcff2..531e5c126 100644 --- a/source/discussions/index.rst +++ b/source/discussions/index.rst @@ -16,3 +16,4 @@ specific topic. If you're just trying to get stuff done, see package-formats src-layout-vs-flat-layout setup-py-deprecated + single_source_version diff --git a/source/single_source_version.rst b/source/discussions/single_source_version.rst similarity index 100% rename from source/single_source_version.rst rename to source/discussions/single_source_version.rst From f130e816f962320ba847efc43c0221477a0c923d Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Thu, 1 Aug 2024 00:21:18 +0000 Subject: [PATCH 108/121] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- source/discussions/single_source_version.rst | 3 --- 1 file changed, 3 deletions(-) diff --git a/source/discussions/single_source_version.rst b/source/discussions/single_source_version.rst index 3eea6af50..5fbb89b00 100644 --- a/source/discussions/single_source_version.rst +++ b/source/discussions/single_source_version.rst @@ -45,6 +45,3 @@ The following are links to some build system's documentation for handling versio * `Setuptools `_ - `setuptools_scm `_ - - - From a08ca8023c0ecb924edb26098ea753b7c7cbb416 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ville=20Skytt=C3=A4?= Date: Mon, 15 Jul 2024 23:31:13 +0300 Subject: [PATCH 109/121] Refer to platform tag as such in use example There's no arch tag. --- source/specifications/platform-compatibility-tags.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/specifications/platform-compatibility-tags.rst b/source/specifications/platform-compatibility-tags.rst index 381b84ca9..740a28a1a 100644 --- a/source/specifications/platform-compatibility-tags.rst +++ b/source/specifications/platform-compatibility-tags.rst @@ -256,7 +256,7 @@ The full list of simple tags is:: for x in pytag.split('.'): for y in abitag.split('.'): - for z in archtag.split('.'): + for z in platformtag.split('.'): yield '-'.join((x, y, z)) A bdist format that implements this scheme should include the expanded From 3d9aced31ab5cf68777fd57dea7a3d22ddc7d84d Mon Sep 17 00:00:00 2001 From: Alyssa Coghlan Date: Thu, 8 Aug 2024 18:25:00 +1000 Subject: [PATCH 110/121] Add Direct URL security heading No changes to the spec, just adding a heading to highlight the notes on avoiding credential leaks. --- source/specifications/direct-url-data-structure.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/source/specifications/direct-url-data-structure.rst b/source/specifications/direct-url-data-structure.rst index 9ec8e2e34..6a4e8fe01 100644 --- a/source/specifications/direct-url-data-structure.rst +++ b/source/specifications/direct-url-data-structure.rst @@ -31,6 +31,9 @@ Depending on what ``url`` refers to, the second field MUST be one of ``vcs_info` local directory). These info fields have a (possibly empty) subdictionary as value, with the possible keys defined below. +Security Considerations +----------------------- + When persisted, ``url`` MUST be stripped of any sensitive authentication information, for security reasons. From c6a145509b9acc17121bb619ef7265d12bf3b4a7 Mon Sep 17 00:00:00 2001 From: "Eden Ross Duff, MSc" Date: Sun, 11 Aug 2024 21:42:12 -0500 Subject: [PATCH 111/121] clarify ``Provides-Dist`` example to match warehouse wheel metadata validation --- source/specifications/core-metadata.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/specifications/core-metadata.rst b/source/specifications/core-metadata.rst index 90793c791..fb6570fbb 100644 --- a/source/specifications/core-metadata.rst +++ b/source/specifications/core-metadata.rst @@ -725,7 +725,7 @@ This field may be followed by an environment marker after a semicolon. Examples:: Provides-Dist: OtherProject - Provides-Dist: AnotherProject (3.4) + Provides-Dist: AnotherProject==3.4 Provides-Dist: virtual_package; python_version >= "3.4" .. _core-metadata-obsoletes-dist: From e9713306df7753e9fe7397ff559cbbcb9d4cae00 Mon Sep 17 00:00:00 2001 From: Stephen Nixon <45946693+arrowtype@users.noreply.github.com> Date: Fri, 16 Aug 2024 22:48:58 -0400 Subject: [PATCH 112/121] Update creating-command-line-tools.rst to fix typo MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The import statement, as written, fails. It doesn’t match the name of the file that is set up with the greet() function. --- source/guides/creating-command-line-tools.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/guides/creating-command-line-tools.rst b/source/guides/creating-command-line-tools.rst index 9f040ce7d..49ce0c9ed 100644 --- a/source/guides/creating-command-line-tools.rst +++ b/source/guides/creating-command-line-tools.rst @@ -78,7 +78,7 @@ in :file:`cli.py`: import typer - from .hello import greet + from .greet import greet app = typer.Typer() From bf026f9978ada745dac68b658f31382cf3f1aab3 Mon Sep 17 00:00:00 2001 From: hutcho Date: Tue, 20 Aug 2024 16:40:15 +1000 Subject: [PATCH 113/121] Clarified note on [build-system] and [project] Used clearer wording, instead of referring to tables as 'former' and 'latter'. Grammar cleanup. --- source/guides/writing-pyproject-toml.rst | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/source/guides/writing-pyproject-toml.rst b/source/guides/writing-pyproject-toml.rst index 18a717a55..a705fde1e 100644 --- a/source/guides/writing-pyproject-toml.rst +++ b/source/guides/writing-pyproject-toml.rst @@ -22,19 +22,19 @@ three possible TOML tables in this file. .. note:: - There is a significant difference between the ``[build-system]`` and - ``[project]`` tables. The former should always be present, regardless of - which build backend you use (since it *defines* the tool you use). The latter - is understood by *most* build backends, but some build backends use a - different format. + The ``[build-system]`` table should always be present, + regardless of which build backend you use (``[build-system]`` *defines* the + build tool you use). - At the time of writing this (November 2023), Poetry_ is a notable build - backend that does not use the ``[project]`` table (it uses the - ``[tool.poetry]`` table instead). + On the other hand, the ``[project]`` table is understood by *most* build + backends, but some build backends use a different format. + As of August 2024, Poetry_ is a notable build backend that does not use + the ``[project]`` table, it uses the ``[tool.poetry]`` table instead. Also, the setuptools_ build backend supports both the ``[project]`` table, - and the older format in ``setup.cfg`` or ``setup.py``. For new projects, it - is recommended to use the ``[project]`` table, and keep ``setup.py`` only if + and the older format in ``setup.cfg`` or ``setup.py``. + + For new projects, use the ``[project]`` table, and keep ``setup.py`` only if some programmatic configuration is needed (such as building C extensions), but the ``setup.cfg`` and ``setup.py`` formats are still valid. See :ref:`setup-py-deprecated`. From 854030bc7c34f852c07f413afc051a8f1f685181 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Tue, 20 Aug 2024 06:42:43 +0000 Subject: [PATCH 114/121] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- source/guides/writing-pyproject-toml.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/source/guides/writing-pyproject-toml.rst b/source/guides/writing-pyproject-toml.rst index a705fde1e..d11b8a87c 100644 --- a/source/guides/writing-pyproject-toml.rst +++ b/source/guides/writing-pyproject-toml.rst @@ -24,15 +24,15 @@ three possible TOML tables in this file. The ``[build-system]`` table should always be present, regardless of which build backend you use (``[build-system]`` *defines* the - build tool you use). + build tool you use). - On the other hand, the ``[project]`` table is understood by *most* build + On the other hand, the ``[project]`` table is understood by *most* build backends, but some build backends use a different format. - As of August 2024, Poetry_ is a notable build backend that does not use - the ``[project]`` table, it uses the ``[tool.poetry]`` table instead. + As of August 2024, Poetry_ is a notable build backend that does not use + the ``[project]`` table, it uses the ``[tool.poetry]`` table instead. Also, the setuptools_ build backend supports both the ``[project]`` table, - and the older format in ``setup.cfg`` or ``setup.py``. + and the older format in ``setup.cfg`` or ``setup.py``. For new projects, use the ``[project]`` table, and keep ``setup.py`` only if some programmatic configuration is needed (such as building C extensions), From 0aefb9e6df908047a3c0323e7e488c82294e88df Mon Sep 17 00:00:00 2001 From: Chris Barker Date: Wed, 21 Aug 2024 16:48:49 -0700 Subject: [PATCH 115/121] Update source/discussions/single_source_version.rst Co-authored-by: Philipp A. --- source/discussions/single_source_version.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/discussions/single_source_version.rst b/source/discussions/single_source_version.rst index 5fbb89b00..f08dc19cc 100644 --- a/source/discussions/single_source_version.rst +++ b/source/discussions/single_source_version.rst @@ -10,11 +10,11 @@ Single-sourcing the Project Version One of the challenges in building packages is that the version string can be required in multiple places. * It needs to be specified when building the package (e.g. in :file:`pyproject.toml`) - - That will assure that it is properly assigned in the distribution file name, and in the installed package metadata. + This will make it available in the installed package’s metadata, from where it will be accessible at runtime using ``importlib.metadata.version("distribution_name")``. -* A package may set a top level ``__version__`` attribute to provide runtime access to the version of the imported package. If this is done, the value of ``__version__`` attribute and that used by the build system to set the distribution's version should be kept in sync in :ref:`the build systems's recommended way `. +* A package may set a top level ``__version__`` attribute to provide an alternative means of runtime access to the version of the imported package. If this is done, the value of ``__version__`` attribute and that used by the build system to set the distribution's version should be kept in sync in :ref:`the build systems's recommended way `. -In any case, The installed distribution version should be accessible using ``importlib.metadata.version("distribution_name")``. +* If the code is in in a version control system (VCS), e.g. Git, the version may appear in a *tag* such as ``v1.2.3``. To ensure that version numbers do not get out of sync, it is recommended that there is a single source of truth for the version number. From 3b05459a595a4cbf83f6ea007436a7182a4bdd4a Mon Sep 17 00:00:00 2001 From: Chris Barker Date: Wed, 21 Aug 2024 17:18:22 -0700 Subject: [PATCH 116/121] normalized the page file name --- source/discussions/index.rst | 2 +- .../{single_source_version.rst => single-source-version.rst} | 0 2 files changed, 1 insertion(+), 1 deletion(-) rename source/discussions/{single_source_version.rst => single-source-version.rst} (100%) diff --git a/source/discussions/index.rst b/source/discussions/index.rst index 531e5c126..1f5ff1f2b 100644 --- a/source/discussions/index.rst +++ b/source/discussions/index.rst @@ -16,4 +16,4 @@ specific topic. If you're just trying to get stuff done, see package-formats src-layout-vs-flat-layout setup-py-deprecated - single_source_version + single-source-version diff --git a/source/discussions/single_source_version.rst b/source/discussions/single-source-version.rst similarity index 100% rename from source/discussions/single_source_version.rst rename to source/discussions/single-source-version.rst From c335757c2783a9a6245bb1955c3f107f62e9d602 Mon Sep 17 00:00:00 2001 From: Chris Barker Date: Thu, 22 Aug 2024 12:17:03 -0700 Subject: [PATCH 117/121] Update source/discussions/single-source-version.rst Co-authored-by: Anderson Bravalheri --- source/discussions/single-source-version.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/discussions/single-source-version.rst b/source/discussions/single-source-version.rst index f08dc19cc..74ecb6989 100644 --- a/source/discussions/single-source-version.rst +++ b/source/discussions/single-source-version.rst @@ -12,7 +12,7 @@ One of the challenges in building packages is that the version string can be req * It needs to be specified when building the package (e.g. in :file:`pyproject.toml`) This will make it available in the installed package’s metadata, from where it will be accessible at runtime using ``importlib.metadata.version("distribution_name")``. -* A package may set a top level ``__version__`` attribute to provide an alternative means of runtime access to the version of the imported package. If this is done, the value of ``__version__`` attribute and that used by the build system to set the distribution's version should be kept in sync in :ref:`the build systems's recommended way `. +* A package may set a module attribute (e.g., ``__version__``) to provide an alternative means of runtime access to the version of the imported package. If this is done, the value of the attribute and that used by the build system to set the distribution's version should be kept in sync in :ref:`the build systems's recommended way `. * If the code is in in a version control system (VCS), e.g. Git, the version may appear in a *tag* such as ``v1.2.3``. From b35bd14a3ce8a8081aee7f51d45c84b061b2a7f6 Mon Sep 17 00:00:00 2001 From: Chris Barker Date: Thu, 22 Aug 2024 12:23:21 -0700 Subject: [PATCH 118/121] Update source/discussions/single-source-version.rst Co-authored-by: Anderson Bravalheri --- source/discussions/single-source-version.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/discussions/single-source-version.rst b/source/discussions/single-source-version.rst index 74ecb6989..05c2f962e 100644 --- a/source/discussions/single-source-version.rst +++ b/source/discussions/single-source-version.rst @@ -24,7 +24,7 @@ In general, the options are: 2) The version can be hard-coded into the :file:`pyproject.toml` file -- and the build system can copy it into other locations it may be required. -3) The version string can be hard-coded into the source code -- either in a special purpose file, such as :file:`_version.txt`, or as a attribute in the :file:`__init__.py`, and the build system can extract it at build time. +3) The version string can be hard-coded into the source code -- either in a special purpose file, such as :file:`_version.txt`, or as a attribute in a module, such as :file:`__init__.py`, and the build system can extract it at build time. Consult your build system's documentation for their recommended method. From e0cb805e371e7144d8398f8e301ab345a3ffaf0f Mon Sep 17 00:00:00 2001 From: Chris Barker Date: Thu, 22 Aug 2024 12:26:05 -0700 Subject: [PATCH 119/121] Update source/discussions/single-source-version.rst Co-authored-by: Anderson Bravalheri --- source/discussions/single-source-version.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/discussions/single-source-version.rst b/source/discussions/single-source-version.rst index 05c2f962e..2e7241cd7 100644 --- a/source/discussions/single-source-version.rst +++ b/source/discussions/single-source-version.rst @@ -42,6 +42,6 @@ The following are links to some build system's documentation for handling versio * `PDM `_ -* `Setuptools `_ +* `Setuptools `_ - `setuptools_scm `_ From b120a516ed3a986ae68149112cd8ad3fff98d5af Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sviatoslav=20Sydorenko=20=28=D0=A1=D0=B2=D1=8F=D1=82=D0=BE?= =?UTF-8?q?=D1=81=D0=BB=D0=B0=D0=B2=20=D0=A1=D0=B8=D0=B4=D0=BE=D1=80=D0=B5?= =?UTF-8?q?=D0=BD=D0=BA=D0=BE=29?= Date: Sat, 24 Aug 2024 02:15:25 +0200 Subject: [PATCH 120/121] Make the single-sourcing discussion label unique --- source/discussions/single-source-version.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/discussions/single-source-version.rst b/source/discussions/single-source-version.rst index 2e7241cd7..115b8ded4 100644 --- a/source/discussions/single-source-version.rst +++ b/source/discussions/single-source-version.rst @@ -1,4 +1,4 @@ -.. _`Single sourcing the version`: +.. _`Single sourcing the version discussion`: =================================== Single-sourcing the Project Version From 4d7e33a875adb9fae0295f5d2995df7b3d41cf0c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sviatoslav=20Sydorenko=20=28=D0=A1=D0=B2=D1=8F=D1=82=D0=BE?= =?UTF-8?q?=D1=81=D0=BB=D0=B0=D0=B2=20=D0=A1=D0=B8=D0=B4=D0=BE=D1=80=D0=B5?= =?UTF-8?q?=D0=BD=D0=BA=D0=BE=29?= Date: Sat, 24 Aug 2024 02:16:42 +0200 Subject: [PATCH 121/121] =?UTF-8?q?=F0=9F=87=BA=F0=9F=87=A6=20Set=20the=20?= =?UTF-8?q?last-reviewed=20date=20in=20the=20single-sourced=20version=20di?= =?UTF-8?q?scussion?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- source/discussions/single-source-version.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/discussions/single-source-version.rst b/source/discussions/single-source-version.rst index 115b8ded4..9bcab6291 100644 --- a/source/discussions/single-source-version.rst +++ b/source/discussions/single-source-version.rst @@ -5,7 +5,7 @@ Single-sourcing the Project Version =================================== :Page Status: Complete -:Last Reviewed: 2024-?? +:Last Reviewed: 2024-08-24 One of the challenges in building packages is that the version string can be required in multiple places.