From 342f9eb0a597d33f9c0b0e7cd5d9192c0521e34f Mon Sep 17 00:00:00 2001 From: Chris Barker Date: Thu, 25 Jul 2024 09:34:31 -0700 Subject: [PATCH 01/48] 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 02/48] 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 03/48] 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 04/48] 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 05/48] 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 06/48] 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 07/48] 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 08/48] 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 09/48] 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 10/48] 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 11/48] 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 12/48] 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 13/48] 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 14/48] 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 15/48] 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 16/48] 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 17/48] 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 18/48] 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 19/48] 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 20/48] 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 21/48] 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 22/48] 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 23/48] 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 24/48] 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 25/48] 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 26/48] 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 27/48] 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 28/48] 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 29/48] 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 30/48] 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 31/48] 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 32/48] 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 33/48] 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 34/48] 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 35/48] 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 36/48] 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 37/48] 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 38/48] 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 39/48] 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 40/48] 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 41/48] [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 0aefb9e6df908047a3c0323e7e488c82294e88df Mon Sep 17 00:00:00 2001 From: Chris Barker Date: Wed, 21 Aug 2024 16:48:49 -0700 Subject: [PATCH 42/48] 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 43/48] 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 44/48] 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 45/48] 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 46/48] 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 47/48] 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 48/48] =?UTF-8?q?=F0=9F=87=BA=F0=9F=87=A6=20Set=20the=20la?= =?UTF-8?q?st-reviewed=20date=20in=20the=20single-sourced=20version=20disc?= =?UTF-8?q?ussion?= 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.