diff --git a/peps/pep-0784.rst b/peps/pep-0784.rst index cd0b9589066..6a8b1700fa1 100644 --- a/peps/pep-0784.rst +++ b/peps/pep-0784.rst @@ -3,12 +3,13 @@ Title: Adding Zstandard to the standard library Author: Emma Harper Smith Sponsor: Gregory P. Smith Discussions-To: https://discuss.python.org/t/87377 -Status: Draft +Status: Accepted Type: Standards Track Created: 06-Apr-2025 Python-Version: 3.14 Post-History: `07-Apr-2025 `__, +Resolution: `25-Apr-2025 `__ Abstract @@ -115,9 +116,8 @@ Both the ``zstd`` and ``zstandard`` import names are claimed by projects on PyPI. To avoid breaking users of one of the existing bindings, this PEP proposes introducing a new namespace for compression libraries, ``compression``. This name is already reserved on PyPI for use in the -standard library. The new Zstandard module will be ``compression.zstd``. -Other compression modules will be re-exported to the ``compression`` namespace -and their current import names will be deprecated. +standard library. The new Zstandard module will be named ``compression.zstd``. +Other compression modules will be re-exported in the new ``compression`` package. Providing a common namespace for compression modules has several advantages. First, it reduces user confusion about where to find compression modules. @@ -220,38 +220,25 @@ Other compression modules New import names ``compression.lzma``, ``compression.bz2``, ``compression.gzip`` and ``compression.zlib`` will be introduced in Python 3.14 re-exporting the contents of the existing ``lzma``, ``bz2``, ``gzip`` and -``zlib`` modules respectively. +``zlib`` modules respectively. The ``compression`` sub-modules will become +the canonical import names going forward. The use of the new compression names +will be promoted over the original top level module names in the Python +documentation when the minimum supported Python version requirements make +that feasible. The ``_compression`` module, given that it is marked private, will be -immediately renamed to ``compression._common.streams``. The new name was +immediately renamed to ``compression._common._streams``. The new name was selected due to the current contents of the module being I/O related helpers for stream APIs (e.g. ``LZMAFile``) in standard library compression modules. -Compression module migration timeline -------------------------------------- - -Existing modules will emit a ``DeprecationWarning`` in the Python -release following the last Python without the ``compression`` module leaving -support. For example, if the ``compression`` namespace is introduced in 3.14, -then the ``DeprecationWarnings`` would be emitted in 3.19, the next release -after 3.13 reaches end of life. These warnings would begin five years after the -introduction of ``compression`` namespace. In accordance with :pep:`387`, in -Python 3.24, five years after the ``DeprecationWarnings`` are added and ten -years after the new ``compression`` namespace is introduced, the existing -modules will be removed and code must use the ``compression`` sub-modules. The -documentation for these modules will be updated to discuss the planned -deprecation and removal timelines. - Backwards Compatibility ======================= -The main compatibility concern is usage of existing standard library -compression APIs with the existing import names. These names will be -deprecated in 3.19 and will be removed in 3.24. Given the long coexistence of -the modules and a 5 year deprecation period, most users will likely migrate to -the new import names well before then. Additionally, a libCST codemod can be -provided to automatically rewrite imports, easing the migration. +This PEP introduces no backwards incompatible changes. There are currently no +plans to deprecate or remove the existing compression modules. Any deprecation +or removal of the existing modules is left to a future decision but will occur +no sooner than 5 years from the acceptance of this PEP. Security Implications @@ -273,8 +260,8 @@ How to Teach This ================= Documentation for the new module is in the reference implementation branch. The -documentation for other modules will be updated to discuss the deprecation of -their existing import names, and how to migrate. +documentation for existing modules will be updated to reference the new names +as well. Reference Implementation @@ -284,8 +271,7 @@ The `reference implementation ` contains the ``_zstd`` C code, the ``compression.zstd`` code, modifications to ``tarfile``, ``shutil``, and ``zipfile``, and tests for each new API and integration added. It also contains the re-exports of other compression -modules. Deprecations for the existing import names will be added once a -decision is reached regarding the open issues. +modules. Rejected Ideas