diff --git a/source/discussions/versioning.rst b/source/discussions/versioning.rst index eeea3578c..aee3d25ea 100644 --- a/source/discussions/versioning.rst +++ b/source/discussions/versioning.rst @@ -27,7 +27,7 @@ examples of version numbers [#version-examples]_: - A post-release of an alpha release (possible, but discouraged): ``1.2.0a1.post1`` - A simple version with only two components: ``23.12`` - A simple version with just one component: ``42`` -- A version with an epoch: ``1!1.0`` +- A version with an epoch (discouraged): ``1!1.0`` Projects can use a cycle of pre-releases to support testing by their users before a final release. In order, the steps are: alpha releases, beta releases, @@ -46,13 +46,14 @@ notes. They should not be used for bug fixes; these should be done with a new final release (e.g., incrementing the third component when using semantic versioning). -Finally, epochs, a rarely used feature, serve to fix the sorting order when -changing the versioning scheme. For example, if a project is using calendar -versioning, with versions like 23.12, and switches to semantic versioning, with -versions like 1.0, the comparison between 1.0 and 23.12 will go the wrong way. -To correct this, the new version numbers should have an explicit epoch, as in -"1!1.0", in order to be treated as more recent than the old version numbers. - +Finally, epochs were intended to fix the sorting order when changing the +versioning scheme. For example, if a project was using calendar versioning, with +versions like ``23.12``, and switched to semantic versioning, with versions like +``1.0``, the comparison between ``1.0`` and ``23.12`` would go the wrong way. To +correct this, the new version numbers would have an explicit epoch, as in +``1!1.0``, in order to be treated as more recent than the old version numbers. +However, this is discouraged, and it is preferable to use a higher version +number that is unlikely to cause user confusion, such as ``100.0``. Semantic versioning vs. calendar versioning diff --git a/source/glossary.rst b/source/glossary.rst index 40c041f4c..ab32f077b 100644 --- a/source/glossary.rst +++ b/source/glossary.rst @@ -14,7 +14,7 @@ Glossary Build Backend - A library that takes a source tree + A library that takes a :term:`source tree ` and builds a :term:`source distribution ` or :term:`built distribution ` from it. The build is delegated to the backend by a diff --git a/source/guides/analyzing-pypi-package-downloads.rst b/source/guides/analyzing-pypi-package-downloads.rst index 2ad02fed5..2e2fdb583 100644 --- a/source/guides/analyzing-pypi-package-downloads.rst +++ b/source/guides/analyzing-pypi-package-downloads.rst @@ -333,6 +333,14 @@ Usage: The `pandas-gbq`_ project allows for accessing query results via `Pandas`_. +``ClickPy`` +----------- + +The `ClickPy`_ project provides a public application to visualize download +statistics, with free direct SQL access to the underlying open-source +`ClickHouse`_ database, updated daily. + + References ========== @@ -346,3 +354,5 @@ References .. _google-cloud-bigquery: https://cloud.google.com/bigquery/docs/reference/libraries .. _pandas-gbq: https://pandas-gbq.readthedocs.io/en/latest/ .. _Pandas: https://pandas.pydata.org/ +.. _ClickHouse: https://github.com/ClickHouse/ClickHouse +.. _Clickpy: https://clickpy.clickhouse.com/ diff --git a/source/guides/multi-version-installs.rst b/source/guides/multi-version-installs.rst index a09bc900a..456ee22e2 100644 --- a/source/guides/multi-version-installs.rst +++ b/source/guides/multi-version-installs.rst @@ -37,7 +37,3 @@ time, but that approach does mean that standard command line invocations of the affected tools can't be used - it's necessary to write a custom wrapper script or use ``python3 -c ''`` to invoke the application's main entry point directly. - -Refer to the `pkg_resources documentation -`__ -for more details. diff --git a/source/guides/packaging-namespace-packages.rst b/source/guides/packaging-namespace-packages.rst index 3d929d527..6ff93c4c9 100644 --- a/source/guides/packaging-namespace-packages.rst +++ b/source/guides/packaging-namespace-packages.rst @@ -159,8 +159,7 @@ Legacy namespace packages These two methods, that were used to create namespace packages prior to :pep:`420`, are now considered to be obsolete and should not be used unless you need compatibility -with packages already using this method. Also, :doc:`pkg_resources ` -has been deprecated. +with packages already using one of these methods. To migrate an existing package, all packages sharing the namespace must be migrated simultaneously. @@ -176,7 +175,7 @@ pkgutil-style namespace packages Python 2.3 introduced the :doc:`pkgutil ` module and the :py:func:`python:pkgutil.extend_path` function. This can be used to declare namespace packages that need to be compatible with both Python 2.3+ and Python 3. This -is the recommended approach for the highest level of compatibility. +was the recommended approach for the highest level of compatibility. To create a pkgutil-style namespace package, you need to provide an :file:`__init__.py` file for the namespace package: @@ -216,10 +215,18 @@ in the `pkgutil namespace example project`_. pkg_resources-style namespace packages ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -:doc:`Setuptools ` provides the `pkg_resources.declare_namespace`_ function and +.. warning:: + + The information in this section is obsolete and is no longer functional + (as of Setuptools 82.0.0). It is only retained for historical reference. + + ``pkg_resources`` has been deprecated and was fully removed in Setuptools 82.0.0. + +:doc:`Setuptools ` previously provided the ``pkg_resources.declare_namespace`` function and the ``namespace_packages`` argument to :func:`~setuptools.setup`. Together -these can be used to declare namespace packages. While this approach is no -longer recommended, it is widely present in most existing namespace packages. +these could be used to declare namespace packages. While this approach is no +longer supported, it may still be encountered in environments using older +``setuptools`` versions. If you are creating a new distribution within an existing namespace package that uses this method then it's recommended to continue using this as the different methods are not cross-compatible and it's not advisable to try to migrate an @@ -281,11 +288,3 @@ to :func:`~setuptools.setup` in :file:`setup.py`. For example: packages=find_packages() namespace_packages=['mynamespace'] ) - -A complete working example of two pkg_resources-style namespace packages can be found -in the `pkg_resources namespace example project`_. - -.. _pkg_resources.declare_namespace: - https://setuptools.readthedocs.io/en/latest/pkg_resources.html#namespace-package-support -.. _pkg_resources namespace example project: - https://github.com/pypa/sample-namespace-packages/tree/master/pkg_resources diff --git a/source/shared/build-backend-tabs.rst b/source/shared/build-backend-tabs.rst index 615724616..578241ce6 100644 --- a/source/shared/build-backend-tabs.rst +++ b/source/shared/build-backend-tabs.rst @@ -38,5 +38,5 @@ .. code-block:: toml [build-system] - requires = ["uv_build >= 0.10.0, <0.11.0"] + requires = ["uv_build >= 0.10.7, <0.11.0"] build-backend = "uv_build" diff --git a/source/specifications/pypirc.rst b/source/specifications/pypirc.rst index aeba72b0d..b937a1d62 100644 --- a/source/specifications/pypirc.rst +++ b/source/specifications/pypirc.rst @@ -10,6 +10,11 @@ indexes ` (referred to here as "repositories"), so that you don't have to enter the URL, username, or password whenever you upload a package with :ref:`twine` or :ref:`flit`. +The :file:`.pypirc` file **SHOULD** be UTF-8 encoded. + +Tools that read or write :file:`.pypirc` files may not function correctly +if another character encoding is used. + The format (originally defined by the :ref:`distutils` package) is: .. code-block:: ini diff --git a/source/specifications/version-specifiers.rst b/source/specifications/version-specifiers.rst index 13015794f..e05422ce2 100644 --- a/source/specifications/version-specifiers.rst +++ b/source/specifications/version-specifiers.rst @@ -394,6 +394,21 @@ from an earlier epoch:: 1!1.1 1!2.0 +.. note:: + + Use of nonzero epochs is discouraged. They are often not supported or + discouraged by downstream packaging where Python packages may need to be + consumed, and due to their scarce use they may also not be well supported by + Python packaging tools. + + When version scheme needs to be changed, it is preferable to continue with + monotonically increasing numbers in epoch zero. For example, the version + 2026.x could be unambiguously followed by 3000.x. + + See `Discouraging use of epoch segments in versions + `__ + for the relevant discussion. + .. _version-specifiers-normalization: @@ -590,8 +605,8 @@ and post-releases for minor corrections:: 1.0.dev2 1.0.dev3 1.0.dev4 - 1.0c1 - 1.0c2 + 1.0rc1 + 1.0rc2 1.0 1.0.post1 1.1.dev1 @@ -1273,3 +1288,4 @@ History - May 2025: Clarify that development releases are a form of pre-release when they are handled. - Nov 2025: Make arbitrary equality case insensitivity explicit. +- Jan 2026: The use of epochs was discouraged.