From cdd22143db703f22994335cdc67f0755d1b1530e Mon Sep 17 00:00:00 2001
From: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
Date: Fri, 10 Oct 2025 16:32:44 +0100
Subject: [PATCH] gh-101100: Document `zlib` public constants to fix reference
 warnings (GH-139835) (cherry picked from commit
 c7f1da97eb4639a17fb01ef122155bab2f262a34)

Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
Co-authored-by: Victor Stinner <vstinner@python.org>
---
 Doc/library/zlib.rst | 136 ++++++++++++++++++++++++++++++++++++++++++-
 Doc/tools/.nitignore |   1 -
 2 files changed, 133 insertions(+), 4 deletions(-)

diff --git a/Doc/library/zlib.rst b/Doc/library/zlib.rst
index 75ead3c4cb144c..50eae4547a99df 100644
--- a/Doc/library/zlib.rst
+++ b/Doc/library/zlib.rst
@@ -16,7 +16,7 @@ earlier than 1.1.3; 1.1.3 has a `security vulnerability <https://zlib.net/zlib_f
 
 zlib's functions have many options and often need to be used in a particular
 order.  This documentation doesn't attempt to cover all of the permutations;
-consult the zlib manual at http://www.zlib.net/manual.html for authoritative
+consult the `zlib manual <https://www.zlib.net/manual.html>`_ for authoritative
 information.
 
 For reading and writing ``.gz`` files see the :mod:`gzip` module.
@@ -312,6 +312,136 @@ Decompression objects support the following methods and attributes:
    objects.
 
 
+The following constants are available to configure compression and decompression
+behavior:
+
+.. data:: DEFLATED
+
+   The deflate compression method.
+
+
+.. data:: MAX_WBITS
+
+   The maximum window size, expressed as a power of 2.
+   For example, if :const:`!MAX_WBITS` is ``15`` it results in a window size
+   of ``32 KiB``.
+
+
+.. data:: DEF_MEM_LEVEL
+
+   The default memory level for compression objects.
+
+
+.. data:: DEF_BUF_SIZE
+
+   The default buffer size for decompression operations.
+
+
+.. data:: Z_NO_COMPRESSION
+
+   Compression level ``0``.
+
+   .. versionadded:: 3.6
+
+
+.. data:: Z_BEST_SPEED
+
+   Compression level ``1``.
+
+
+.. data:: Z_BEST_COMPRESSION
+
+   Compression level ``9``.
+
+
+.. data:: Z_DEFAULT_COMPRESSION
+
+   Default compression level (``-1``).
+
+
+.. data:: Z_DEFAULT_STRATEGY
+
+   Default compression strategy, for normal data.
+
+
+.. data:: Z_FILTERED
+
+   Compression strategy for data produced by a filter (or predictor).
+
+
+.. data:: Z_HUFFMAN_ONLY
+
+   Compression strategy that forces Huffman coding only.
+
+
+.. data:: Z_RLE
+
+   Compression strategy that limits match distances to one (run-length encoding).
+
+   This constant is only available if Python was compiled with zlib
+   1.2.0.1 or greater.
+
+   .. versionadded:: 3.6
+
+
+.. data:: Z_FIXED
+
+   Compression strategy that prevents the use of dynamic Huffman codes.
+
+   This constant is only available if Python was compiled with zlib
+   1.2.2.2 or greater.
+
+   .. versionadded:: 3.6
+
+
+.. data:: Z_NO_FLUSH
+
+   Flush mode ``0``. No special flushing behavior.
+
+   .. versionadded:: 3.6
+
+
+.. data:: Z_PARTIAL_FLUSH
+
+   Flush mode ``1``. Flush as much output as possible.
+
+
+.. data:: Z_SYNC_FLUSH
+
+   Flush mode ``2``. All output is flushed and the output is aligned to a byte boundary.
+
+
+.. data:: Z_FULL_FLUSH
+
+   Flush mode ``3``. All output is flushed and the compression state is reset.
+
+
+.. data:: Z_FINISH
+
+   Flush mode ``4``. All pending input is processed, no more input is expected.
+
+
+.. data:: Z_BLOCK
+
+   Flush mode ``5``. A deflate block is completed and emitted.
+
+   This constant is only available if Python was compiled with zlib
+   1.2.2.2 or greater.
+
+   .. versionadded:: 3.6
+
+
+.. data:: Z_TREES
+
+   Flush mode ``6``, for inflate operations. Instructs inflate to return when
+   it gets to the next deflate block boundary.
+
+   This constant is only available if Python was compiled with zlib
+   1.2.3.4 or greater.
+
+   .. versionadded:: 3.6
+
+
 Information about the version of the zlib library in use is available through
 the following constants:
 
@@ -347,10 +477,10 @@ the following constants:
    Module :mod:`gzip`
       Reading and writing :program:`gzip`\ -format files.
 
-   http://www.zlib.net
+   https://www.zlib.net
       The zlib library home page.
 
-   http://www.zlib.net/manual.html
+   https://www.zlib.net/manual.html
       The zlib manual explains  the semantics and usage of the library's many
       functions.
 
diff --git a/Doc/tools/.nitignore b/Doc/tools/.nitignore
index 827c5808fa5865..657d720e766179 100644
--- a/Doc/tools/.nitignore
+++ b/Doc/tools/.nitignore
@@ -51,7 +51,6 @@ Doc/library/xml.sax.reader.rst
 Doc/library/xml.sax.rst
 Doc/library/xmlrpc.client.rst
 Doc/library/xmlrpc.server.rst
-Doc/library/zlib.rst
 Doc/whatsnew/2.4.rst
 Doc/whatsnew/2.5.rst
 Doc/whatsnew/2.6.rst