From 35fac032db0132e9a693439b696c7e30db06c637 Mon Sep 17 00:00:00 2001 From: Emma Harper Smith Date: Fri, 25 Apr 2025 17:00:33 -0700 Subject: [PATCH 1/9] PEP 784: Remove deprecation and removal timeline As requested by the Steering Council --- peps/pep-0784.rst | 36 ++++++++---------------------------- 1 file changed, 8 insertions(+), 28 deletions(-) diff --git a/peps/pep-0784.rst b/peps/pep-0784.rst index cd0b9589066..0282368b9c6 100644 --- a/peps/pep-0784.rst +++ b/peps/pep-0784.rst @@ -115,9 +115,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 to the ``compression`` namespace. Providing a common namespace for compression modules has several advantages. First, it reduces user confusion about where to find compression modules. @@ -227,31 +226,13 @@ 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. Security Implications @@ -273,8 +254,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 +265,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 From 33440fe124f0853ca3cc4c4517bce42b72f6b021 Mon Sep 17 00:00:00 2001 From: Emma Smith Date: Fri, 25 Apr 2025 18:32:02 -0700 Subject: [PATCH 2/9] Add suggestion from Barry Co-authored-by: Barry Warsaw --- peps/pep-0784.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/peps/pep-0784.rst b/peps/pep-0784.rst index 0282368b9c6..daf7518c930 100644 --- a/peps/pep-0784.rst +++ b/peps/pep-0784.rst @@ -116,7 +116,7 @@ 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 named ``compression.zstd``. -Other compression modules will be re-exported to the ``compression`` namespace. +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. From a96adb3c32e68cb112c3cfa3ce4f66e6b262f785 Mon Sep 17 00:00:00 2001 From: Emma Harper Smith Date: Fri, 25 Apr 2025 18:55:06 -0700 Subject: [PATCH 3/9] Mark PEP 784 accepted --- peps/pep-0784.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/peps/pep-0784.rst b/peps/pep-0784.rst index daf7518c930..875bf2ed6e3 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 From 71debeebb99791a0611b8965fe4eb520a699a800 Mon Sep 17 00:00:00 2001 From: Emma Harper Smith Date: Fri, 25 Apr 2025 18:56:53 -0700 Subject: [PATCH 4/9] Add a second underline for resolution link --- peps/pep-0784.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/peps/pep-0784.rst b/peps/pep-0784.rst index 875bf2ed6e3..819f4f91921 100644 --- a/peps/pep-0784.rst +++ b/peps/pep-0784.rst @@ -9,7 +9,7 @@ Created: 06-Apr-2025 Python-Version: 3.14 Post-History: `07-Apr-2025 `__, -Resolution: `25-Apr-2025 `_ +Resolution: `25-Apr-2025 `__ Abstract From c5501548d5628ca61f3fc938af1289e7263fc960 Mon Sep 17 00:00:00 2001 From: Emma Smith Date: Fri, 25 Apr 2025 19:43:56 -0700 Subject: [PATCH 5/9] Use shorter form of discuss URL Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> --- peps/pep-0784.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/peps/pep-0784.rst b/peps/pep-0784.rst index 819f4f91921..ef08c6b9e68 100644 --- a/peps/pep-0784.rst +++ b/peps/pep-0784.rst @@ -9,7 +9,7 @@ Created: 06-Apr-2025 Python-Version: 3.14 Post-History: `07-Apr-2025 `__, -Resolution: `25-Apr-2025 `__ +Resolution: `25-Apr-2025 `__ Abstract From 2ce131663f331ff3fccba08152ab9b104d3b6551 Mon Sep 17 00:00:00 2001 From: Emma Harper Smith Date: Sat, 26 Apr 2025 10:30:36 -0700 Subject: [PATCH 6/9] Add no sooner than verbiage --- peps/pep-0784.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/peps/pep-0784.rst b/peps/pep-0784.rst index ef08c6b9e68..eadef8a8060 100644 --- a/peps/pep-0784.rst +++ b/peps/pep-0784.rst @@ -233,7 +233,8 @@ Backwards Compatibility 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. +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 From 53ab0b588332a0cca3a44123321e9944d2cc9897 Mon Sep 17 00:00:00 2001 From: Emma Harper Smith Date: Sat, 26 Apr 2025 10:36:19 -0700 Subject: [PATCH 7/9] Mention the compression sub-modules should be canonical --- peps/pep-0784.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/peps/pep-0784.rst b/peps/pep-0784.rst index eadef8a8060..585762703ef 100644 --- a/peps/pep-0784.rst +++ b/peps/pep-0784.rst @@ -220,7 +220,8 @@ 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 ``_compression`` module, given that it is marked private, will be immediately renamed to ``compression._common.streams``. The new name was From 9d58ebceecd813964d0715ec587738f2562fef5c Mon Sep 17 00:00:00 2001 From: Emma Harper Smith Date: Sat, 26 Apr 2025 12:28:00 -0700 Subject: [PATCH 8/9] Include statement on documentation Co-authored-by: "Gregory P. Smith" --- peps/pep-0784.rst | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/peps/pep-0784.rst b/peps/pep-0784.rst index 585762703ef..193791b06a7 100644 --- a/peps/pep-0784.rst +++ b/peps/pep-0784.rst @@ -221,7 +221,10 @@ 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. The ``compression`` sub-modules will become -the canonical import names going forward. +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 From 932d216dc3f27f2d039adf960c1b7463df831204 Mon Sep 17 00:00:00 2001 From: Emma Harper Smith Date: Sat, 26 Apr 2025 14:11:09 -0700 Subject: [PATCH 9/9] Update _compression rename to reflect review --- peps/pep-0784.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/peps/pep-0784.rst b/peps/pep-0784.rst index 193791b06a7..6a8b1700fa1 100644 --- a/peps/pep-0784.rst +++ b/peps/pep-0784.rst @@ -227,7 +227,7 @@ 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.