From: Miss Islington (bot) <31488909+miss-islington@users.noreply.github.com>
Date: Mon, 17 Jun 2024 06:06:11 +0000 (+0200)
Subject: [3.13] gh-112346: Document the OS byte in `gzip.compress` output change in 3.11 ... 
X-Git-Tag: v3.13.0b3~87
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=3b28e430edfb60964fb3a34d2971d21a9200a4f9;p=thirdparty%2FPython%2Fcpython.git

[3.13] gh-112346: Document the OS byte in `gzip.compress` output change in 3.11 (GH-120480) (#120612)

gh-112346: Document the OS byte in `gzip.compress` output change in 3.11 (GH-120480)
(cherry picked from commit bac4edad69bb20dd9460766e062637cae999e1e0)


gh-112346: Describe the "os" byte in gzip output change.

Co-authored-by: Gregory P. Smith <greg@krypto.org>
---

diff --git a/Doc/library/gzip.rst b/Doc/library/gzip.rst
index 152cba4f653c..6b6e158f6eba 100644
--- a/Doc/library/gzip.rst
+++ b/Doc/library/gzip.rst
@@ -196,7 +196,9 @@ The module defines the following items:
    .. versionchanged:: 3.11
       Speed is improved by compressing all data at once instead of in a
       streamed fashion. Calls with *mtime* set to ``0`` are delegated to
-      :func:`zlib.compress` for better speed.
+      :func:`zlib.compress` for better speed. In this situation the
+      output may contain a gzip header "OS" byte value other than 255
+      "unknown" as supplied by the underlying zlib implementation.
 
    .. versionchanged:: 3.13
       The gzip header OS byte is guaranteed to be set to 255 when this function
diff --git a/Doc/whatsnew/3.11.rst b/Doc/whatsnew/3.11.rst
index 7a74df330a86..b601bd453f5b 100644
--- a/Doc/whatsnew/3.11.rst
+++ b/Doc/whatsnew/3.11.rst
@@ -768,6 +768,21 @@ functools
   (Contributed by Yurii Karabas in :issue:`46014`.)
 
 
+.. _whatsnew311-gzip:
+
+gzip
+----
+
+* The :func:`gzip.compress` function is now faster when used with the
+  **mtime=0** argument as it delegates the compression entirely to a single
+  :func:`zlib.compress` operation. There is one side effect of this change: The
+  gzip file header contains an "OS" byte in its header. That was traditionally
+  always set to a value of 255 representing "unknown" by the :mod:`gzip`
+  module. Now, when using :func:`~gzip.compress` with **mtime=0**, it may be
+  set to a different value by the underlying zlib C library Python was linked
+  against.
+  (See :gh:`112346` for details on the side effect.)
+
 .. _whatsnew311-hashlib:
 
 hashlib