Misc edits

* address review comments
* go back to semantic cross-references (the build will fail until the
  CPython PR and its backports land, but that's OK)

Author: ncoghlan

source/discussions/single-source-version.rst

@@ -10,33 +10,40 @@ Single-sourcing the Project Version
 Many Python :term:`distribution packages <Distribution Package>` publish a single
 Python :term:`import package <Import Package>` where it is desired that the runtime
 ``__version__`` attribute on the import package report the same version specifier
-as ``importlib.metadata.version`` reports for the distribution package
+as :func:`importlib.metadata.version` reports for the distribution package
 (as described in :ref:`runtime-version-access`).
 
 It is also frequently desired that this version information be derived from a version
 control system *tag* (such as ``v1.2.3``) rather than being manually updated in the
 source code.
 
-To ensure that version numbers do not get out of sync, it may be sufficient to add
-an automated test case that ensures ``package.__version__`` and
-``importlib.metadata.version("package")`` report the same value.
+Some projects may choose to simply live with the data entry duplication, and rely
+on automated testing to ensure the different values do not diverge.
 
 Alternatively, a project's chosen build system may offer a way to define 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.
+1) If the code is in a version control system (VCS), such as 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.
 
 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 an attribute in a module, such as :file:`__init__.py`, and the build
-   system can extract it at build time.
+   such as :file:`_version.txt` (which must then be shipped as part of the project's source distribution
+   package), or as an attribute in a particular module, such as :file:`__init__.py`. The build
+   system can then extract it from the runtime location at build time.
 
 Consult your build system's documentation for their recommended method.
 
+When the intention is that a distribution package and its associated import package
+share the same version, it is recommended that the project include an automated test
+case that ensures ``import_name.__version__`` and ``importlib.metadata.version("dist-name")``
+report the same value (note: for many projects, ``import_name`` and ``dist-name`` will
+be the same name).
+
+
 .. _Build system version handling:
 
 Build System Version Handling

source/discussions/versioning.rst

@@ -178,42 +178,47 @@ Accessing version information at runtime
 
 Version information for all :term:`distribution packages <Distribution Package>`
 that are locally available in the current environment can be obtained at runtime
-using the standard library's ``importlib.metadata.version`` function::
+using the standard library's :func:`importlib.metadata.version` function::
 
    >>> importlib.metadata.version("pip")
    '23.3.2'
 
-Many libraries also choose to version their top level
+Many projects also choose to version their top level
 :term:`import packages <Import Package>` by providing a package level
 ``__version__`` attribute::
 
-   >>> import pip
-   >>> pip.__version__
-   '23.3.2'
+   >>> import cryptography
+   >>> cryptography.__version__
+   '41.0.7'
 
-Import packages are *not* required to be versioned independently of their
-distribution package version information (see the rejected proposal in
-:pep:`PEP 396 <396>`), so this approach to retrieving runtime version
-information should only be used with libraries that are known to provide it.
+This technique can be particularly valuable for CLI applications which want
+to ensure that version query invocations (such as ``pip -V``) run as quickly
+as possible.
 
-Library publishers wishing to ensure their reported distribution package and
+Package publishers wishing to ensure their reported distribution package and
 import package versions are consistent with each other can review the
 :ref:`single-source-version` discussion for potential approaches to doing so.
 
-Some libraries may need to publish version information for external APIs
+However, as import packages and modules are not *required* to publish runtime
+version information in this way (see the rejected proposal in
+:pep:`PEP 396 <396>`), the ``__version__`` attribute should either only be
+queried with interfaces that are known to provide it, or else the querying
+code should be designed to handle the case where the attribute is missing
+[#fallback-to-dist-version]_.
+
+Some projects may need to publish version information for external APIs
 that don't meet the requirements for Python distribution package
-:ref:`version specifiers <version-specifiers>`. Such libraries should
-define their own library-specific ways of obtaining the relevant information
+:ref:`version specifiers <version-specifiers>`. Such projects should
+define their own project-specific ways of obtaining the relevant information
 at runtime. For example, the standard library's :mod:`ssl` module offers
 multiple ways to access the underlying OpenSSL library version::
 
    >>> ssl.OPENSSL_VERSION
    'OpenSSL 3.2.2 4 Jun 2024'
    >>> ssl.OPENSSL_VERSION_INFO
    (3, 2, 0, 2, 0)
-   >>> ssl.OPENSSL_VERSION_NUMBER
-   807403552
-
+   >>> hex(ssl.OPENSSL_VERSION_NUMBER)
+   '0x30200020'
 
 --------------------------------------------------------------------------------
 
@@ -226,6 +231,15 @@ multiple ways to access the underlying OpenSSL library version::
    Brett Cannon <semver-brett-cannon_>`_. For a humoristic take, read about
    ZeroVer_.
 
+.. [#fallback-to-dist-version] A full list mapping the top level names available
+   for import to the distribution packages that provide those import packages and
+   modules may be obtained through the standard library's
+   :func:`importlib.metadata.packages_distributions` function. This means that
+   even code that is attempting to infer a version to report for all importable
+   top-level names has a means to fall back to reporting the distribution
+   version information if no ``__version__`` attribute is defined. Only standard
+   library modules, and modules added via means other than Python package
+   installation would fail to have version information reported in that case.
 
 
 .. _zerover: https://0ver.org