Merge branch 'conda_notes' of https://github.com/ChrisBarker-NOAA/python-packaging-user-guide into conda_notes

Author: ChrisBarker-NOAA

.pre-commit-config.yaml

@@ -1,6 +1,6 @@
 repos:
 - repo: https://github.com/pre-commit/pre-commit-hooks
-  rev: v4.6.0
+  rev: v5.0.0
   hooks:
   - id: check-added-large-files
   - id: check-case-conflict
@@ -34,7 +34,7 @@ repos:
   - id: rst-inline-touching-normal
 
 - repo: https://github.com/astral-sh/ruff-pre-commit
-  rev: v0.4.10
+  rev: v0.7.1
   hooks:
     - id: ruff
     - id: ruff-format

source/contribute.rst

@@ -45,7 +45,7 @@ Tutorials are focused on teaching the reader new concepts by accomplishing a
 goal. They are opinionated step-by-step guides. They do not include extraneous
 warnings or information. `example tutorial-style document`_.
 
-.. _example tutorial-style document: https://docs.djangoproject.com/en/1.11/intro/
+.. _example tutorial-style document: https://docs.djangoproject.com/en/dev/intro/
 
 Guides
 ------

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

source/discussions/setup-py-deprecated.rst

@@ -141,7 +141,6 @@ This guide does not make suggestions of replacement solutions for those commands
     * ``easy_install``
     * ``editable_wheel``
     * ``egg_info``
-    * ``install``
     * ``install_data``
     * ``install_egg_info``
     * ``install_headers``

source/discussions/single-source-version.rst

@@ -0,0 +1,62 @@
+.. _single-source-version:
+
+===================================
+Single-sourcing the Project Version
+===================================
+
+:Page Status: Complete
+:Last Reviewed: 2024-10-07
+
+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 :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.
+
+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), 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` (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
+-----------------------------
+
+The following are links to some build system's documentation for handling version strings.
+
+* `Flit <https://flit.pypa.io/en/stable/>`_
+
+* `Hatchling <https://hatch.pypa.io/1.9/version/>`_
+
+* `PDM <https://pdm-project.org/en/latest/reference/pep621/#__tabbed_1_2>`_
+
+* `Setuptools <https://setuptools.pypa.io/en/latest/userguide/pyproject_config.html#dynamic-metadata>`_
+
+  -  `setuptools_scm <https://setuptools-scm.readthedocs.io/en/latest/>`_

source/discussions/versioning.rst

@@ -153,7 +153,6 @@ numbering scheme that readily conveys the approximate age of a release, but
 doesn't otherwise commit to a particular release cadence within the year.
 
 
-
 Local version identifiers
 =========================
 
@@ -172,6 +171,54 @@ since the latest release, setuptools-scm generates a version like
 "0.5.dev1+gd00980f", or if the repository has untracked changes, like
 "0.5.dev1+gd00980f.d20231217".
 
+.. _runtime-version-access:
+
+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 :func:`importlib.metadata.version` function::
+
+   >>> importlib.metadata.version("cryptography")
+   '41.0.7'
+
+Many projects also choose to version their top level
+:term:`import packages <Import Package>` by providing a package level
+``__version__`` attribute::
+
+   >>> import cryptography
+   >>> cryptography.__version__
+   '41.0.7'
+
+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.
+
+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.
+
+As import packages and modules are not *required* to publish runtime
+version information in this way (see the withdrawn proposal in
+:pep:`PEP 396 <396>`), the ``__version__`` attribute should either only be
+queried with interfaces that are known to provide it (such as a project
+querying its own version or the version of one of its direct dependencies),
+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 aren't the version of the module itself. 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)
+   >>> hex(ssl.OPENSSL_VERSION_NUMBER)
+   '0x30200020'
 
 --------------------------------------------------------------------------------
 
@@ -184,6 +231,15 @@ since the latest release, setuptools-scm generates a version like
    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

source/guides/creating-command-line-tools.rst

@@ -78,7 +78,7 @@ in :file:`cli.py`:
 
     import typer
 
-    from .hello import greet
+    from .greet import greet
 
 
     app = typer.Typer()

source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml

@@ -22,7 +22,7 @@ jobs:
     - name: Build a binary wheel and a source tarball
       run: python3 -m build
     - name: Store the distribution packages
-      uses: actions/upload-artifact@v3
+      uses: actions/upload-artifact@v4
       with:
         name: python-package-distributions
         path: dist/
@@ -42,7 +42,7 @@ jobs:
 
     steps:
     - name: Download all the dists
-      uses: actions/download-artifact@v3
+      uses: actions/download-artifact@v4
       with:
         name: python-package-distributions
         path: dist/
@@ -63,12 +63,12 @@ jobs:
 
     steps:
     - name: Download all the dists
-      uses: actions/download-artifact@v3
+      uses: actions/download-artifact@v4
       with:
         name: python-package-distributions
         path: dist/
     - name: Sign the dists with Sigstore
-      uses: sigstore/gh-action-sigstore-python@v2.1.1
+      uses: sigstore/gh-action-sigstore-python@v3.0.0
       with:
         inputs: >-
           ./dist/*.tar.gz
@@ -107,7 +107,7 @@ jobs:
 
     steps:
     - name: Download all the dists
-      uses: actions/download-artifact@v3
+      uses: actions/download-artifact@v4
       with:
         name: python-package-distributions
         path: dist/

source/guides/packaging-binary-extensions.rst

@@ -403,3 +403,15 @@ a Debian system, see the following articles:
 * `What are (c)python extension modules? <https://thomasnyberg.com/what_are_extension_modules.html>`_
 * `Releasing the gil <https://thomasnyberg.com/releasing_the_gil.html>`_
 * `Writing cpython extension modules using C++ <https://thomasnyberg.com/cpp_extension_modules.html>`_
+
+Additional considerations for binary wheels
+-------------------------------------------
+
+The `pypackaging-native <https://pypackaging-native.github.io/>`_ website has
+additional coverage of packaging Python packages with native code. It aims to
+provide an overview of the most important packaging issues for such projects,
+with in-depth explanations and references.
+
+Examples of topics covered are non-Python compiled dependencies ("native
+dependencies"), the importance of the ABI (Application Binary Interface) of
+native code, dependency on SIMD code and cross compilation.

source/guides/section-build-and-publish.rst

@@ -7,7 +7,6 @@ Building and Publishing
 
    writing-pyproject-toml
    distributing-packages-using-setuptools
-   single-sourcing-package-version
    dropping-older-python-versions
    packaging-binary-extensions
    packaging-namespace-packages