From fb3ec88a5b82c84c0c9b52724cbcecd85ec175f3 Mon Sep 17 00:00:00 2001 From: Chris Barker Date: Thu, 25 Jul 2024 09:34:31 -0700 Subject: [PATCH 01/19] updated single_source_version with a much simpler page -- essentially refering folks to their build system of choice. --- source/single_source_version.rst | 110 +++++++------------------------ 1 file changed, 22 insertions(+), 88 deletions(-) diff --git a/source/single_source_version.rst b/source/single_source_version.rst index 0a80cf3b0..206ff5020 100644 --- a/source/single_source_version.rst +++ b/source/single_source_version.rst @@ -7,111 +7,45 @@ 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. -There are a few techniques to store the version in your project code without duplicating the value stored in -``setup.py``: +* 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. -#. Read the file in ``setup.py`` and parse the version with a regex. Example ( - from `pip setup.py `_):: +* Some projects require that there be a version string available as an attribute in the importable module, e.g:: - def read(*names, **kwargs): - with io.open( - os.path.join(os.path.dirname(__file__), *names), - encoding=kwargs.get("encoding", "utf8") - ) as fp: - return fp.read() + import a_package + print(a_package.__version__) - def find_version(*file_paths): - version_file = read(*file_paths) - version_match = re.search(r"^__version__ = ['\"]([^'\"]*)['\"]", - version_file, re.M) - if version_match: - return version_match.group(1) - raise RuntimeError("Unable to find version string.") +While different projects have different needs, it's important to make sure that there is a single source of truth for the version number. - setup( - ... - version=find_version("package", "__init__.py") - ... - ) +In general, the options are: - .. note:: +1) If the code is in a version control system (VCS), e.g. git, then the version can be extracted from the VCS. - This technique has the disadvantage of having to deal with complexities of regular expressions. +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. -#. Use an external build tool that either manages updating both locations, or - offers an API that both locations can use. +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. - Few tools you could use, in no particular order, and not necessarily complete: - `bumpversion `_, - `changes `_, `zest.releaser `_. +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') -#. Set the value to a ``__version__`` global variable in a dedicated module in - your project (e.g. ``version.py``), then have ``setup.py`` read and ``exec`` the - value into a variable. - Using ``execfile``: +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? - execfile('...sample/version.py') - # now we have a `__version__` variable - # later on we use: __version__ - Using ``exec``: +* setuptools: - :: +* hatch: - version = {} - with open("...sample/version.py") as fp: - exec(fp.read(), version) - # later on we use: version['__version__'] +* poetry: - Example using this technique: `warehouse `_. +* PyBuilder: -#. Place the value in a simple ``VERSION`` text file and have both ``setup.py`` - and the project code read it. +* Others? - :: - - with open(os.path.join(mypackage_root_dir, 'VERSION')) as version_file: - version = version_file.read().strip() - - An advantage with this technique is that it's not specific to Python. Any - tool can read the version. - - .. warning:: - - With this approach you must make sure that the ``VERSION`` file is included in - all your source and binary distributions. - -#. Set the value in ``setup.py``, and have the project code use the - ``pkg_resources`` API. - - :: - - import pkg_resources - assert pkg_resources.get_distribution('pip').version == '1.2.0' - - Be aware that the ``pkg_resources`` API only knows about what's in the - installation metadata, which is not necessarily the code that's currently - imported. - - -#. Set the value to ``__version__`` in ``sample/__init__.py`` and import - ``sample`` in ``setup.py``. - - :: - - import sample - setup( - ... - version=sample.__version__ - ... - ) - - Although this technique is common, beware that it will fail if - ``sample/__init__.py`` imports packages from ``install_requires`` - dependencies, which will very likely not be installed yet when ``setup.py`` - is run. From c7fa00cc8f9dc96871541c9fde9b0aa920198fda Mon Sep 17 00:00:00 2001 From: Chris Barker Date: Thu, 25 Jul 2024 11:17:19 -0700 Subject: [PATCH 02/19] 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 49842a81ebb6ce679cf80eb79bd28898eb129061 Mon Sep 17 00:00:00 2001 From: Chris Barker Date: Thu, 25 Jul 2024 11:20:08 -0700 Subject: [PATCH 03/19] 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 840801fe2a09a1d034994eca697feac5afbe8826 Mon Sep 17 00:00:00 2001 From: Chris Barker Date: Thu, 25 Jul 2024 14:51:07 -0700 Subject: [PATCH 04/19] 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 3724c8d8a12fb08048fa5032fda786770ba4900e Mon Sep 17 00:00:00 2001 From: Chris Barker Date: Thu, 25 Jul 2024 14:53:58 -0700 Subject: [PATCH 05/19] 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 536895675716f9f690fa4c0da9e42ad09b8a59a0 Mon Sep 17 00:00:00 2001 From: Chris Barker Date: Thu, 25 Jul 2024 15:11:36 -0700 Subject: [PATCH 06/19] 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 56db0d96eb05803950678d70bd1ef595f9bca236 Mon Sep 17 00:00:00 2001 From: Chris Barker Date: Fri, 26 Jul 2024 09:39:32 -0700 Subject: [PATCH 07/19] 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 9bace5d6f08515517b282f76dcced8f8bc1dad54 Mon Sep 17 00:00:00 2001 From: Chris Barker Date: Fri, 26 Jul 2024 10:01:56 -0700 Subject: [PATCH 08/19] 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 035c2bd9a356b6bc0ecb89605c6424142baaaa54 Mon Sep 17 00:00:00 2001 From: Chris Barker Date: Fri, 26 Jul 2024 10:02:18 -0700 Subject: [PATCH 09/19] 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 dd1b70ec57e5d7ddec4d3ed3dea026342be2080b Mon Sep 17 00:00:00 2001 From: Chris Barker Date: Fri, 26 Jul 2024 10:31:38 -0700 Subject: [PATCH 10/19] 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 eaf458abf4916784123e53489b319bd2573c5954 Mon Sep 17 00:00:00 2001 From: Chris Barker Date: Tue, 30 Jul 2024 11:14:57 -0700 Subject: [PATCH 11/19] 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 682ab8d22..d4cc0428e 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 29aa220055d75ec59900ca9ea490260c8b691636 Mon Sep 17 00:00:00 2001 From: Chris Barker Date: Tue, 30 Jul 2024 11:15:18 -0700 Subject: [PATCH 12/19] 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 d4cc0428e..296eb31e6 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 de722f6634c04ca010f54aabddcc712d828e146a Mon Sep 17 00:00:00 2001 From: Chris Barker Date: Tue, 30 Jul 2024 11:59:12 -0700 Subject: [PATCH 13/19] 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 296eb31e6..95b80d846 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 63061bdbfc932c3a7fc84a4ae9f5b8ec9e05072f Mon Sep 17 00:00:00 2001 From: Chris Barker Date: Tue, 30 Jul 2024 11:59:28 -0700 Subject: [PATCH 14/19] 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 95b80d846..a2aa74a6d 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 bfdc47466f0b819e7c8fbe9edb38628980a46554 Mon Sep 17 00:00:00 2001 From: Chris Barker Date: Tue, 30 Jul 2024 12:15:02 -0700 Subject: [PATCH 15/19] 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 a2aa74a6d..29579be98 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 c69e2c06b461745b5161ccb359255bc8b7719a57 Mon Sep 17 00:00:00 2001 From: Chris Barker Date: Tue, 30 Jul 2024 13:08:40 -0700 Subject: [PATCH 16/19] 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 648c4278c417ee6b82b1fcd8857d43322c16b403 Mon Sep 17 00:00:00 2001 From: Chris Barker Date: Tue, 30 Jul 2024 13:13:49 -0700 Subject: [PATCH 17/19] 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 b9ced45838866e9bd9d3c5e99ac4f14870ff8c2e Mon Sep 17 00:00:00 2001 From: Chris Barker Date: Wed, 31 Jul 2024 15:04:58 -0700 Subject: [PATCH 18/19] 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 0f5d2d3da700e1ee55b869449ee26b82d7784cc8 Mon Sep 17 00:00:00 2001 From: Chris Barker Date: Wed, 31 Jul 2024 15:25:49 -0700 Subject: [PATCH 19/19] a few more edits from the PR comments, and adding it back to the index (in the right place?) --- source/index.rst | 1 + source/single_source_version.rst | 8 +++++--- 2 files changed, 6 insertions(+), 3 deletions(-) diff --git a/source/index.rst b/source/index.rst index 70933489a..b56ac57cd 100644 --- a/source/index.rst +++ b/source/index.rst @@ -19,6 +19,7 @@ This guide is maintained on `github current installing distributing + single_source_version additional projects glossary 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 `_