From bee8b4741dd11313572ef80a19e9e08bd78b308d Mon Sep 17 00:00:00 2001 From: gaosiyuan <1264472267@qq.com> Date: Tue, 23 Jun 2026 16:59:35 +0800 Subject: [PATCH 1/2] Fix Sphinx reference warnings in Doc/library/lzma.rst Change :const: to :data: for module-level constants like FORMAT_XZ, CHECK_CRC32, etc. The :const: role doesn't resolve for these in modern Sphinx. Closes #151949 --- Doc/library/lzma.rst | 66 ++++++++++++++++++++++---------------------- 1 file changed, 33 insertions(+), 33 deletions(-) diff --git a/Doc/library/lzma.rst b/Doc/library/lzma.rst index cd72174d54f6e6..7f2fce3755c671 100644 --- a/Doc/library/lzma.rst +++ b/Doc/library/lzma.rst @@ -154,33 +154,33 @@ Compressing and decompressing data in memory The *format* argument specifies what container format should be used. Possible values are: - * :const:`FORMAT_XZ`: The ``.xz`` container format. + * :data:`FORMAT_XZ`: The ``.xz`` container format. This is the default format. - * :const:`FORMAT_ALONE`: The legacy ``.lzma`` container format. + * :data:`FORMAT_ALONE`: The legacy ``.lzma`` container format. This format is more limited than ``.xz`` -- it does not support integrity checks or multiple filters. - * :const:`FORMAT_RAW`: A raw data stream, not using any container format. + * :data:`FORMAT_RAW`: A raw data stream, not using any container format. This format specifier does not support integrity checks, and requires that you always specify a custom filter chain (for both compression and decompression). Additionally, data compressed in this manner cannot be - decompressed using :const:`FORMAT_AUTO` (see :class:`LZMADecompressor`). + decompressed using :data:`FORMAT_AUTO` (see :class:`LZMADecompressor`). The *check* argument specifies the type of integrity check to include in the compressed data. This check is used when decompressing, to ensure that the data has not been corrupted. Possible values are: - * :const:`CHECK_NONE`: No integrity check. + * :data:`CHECK_NONE`: No integrity check. This is the default (and the only acceptable value) for - :const:`FORMAT_ALONE` and :const:`FORMAT_RAW`. + :data:`FORMAT_ALONE` and :data:`FORMAT_RAW`. - * :const:`CHECK_CRC32`: 32-bit Cyclic Redundancy Check. + * :data:`CHECK_CRC32`: 32-bit Cyclic Redundancy Check. - * :const:`CHECK_CRC64`: 64-bit Cyclic Redundancy Check. - This is the default for :const:`FORMAT_XZ`. + * :data:`CHECK_CRC64`: 64-bit Cyclic Redundancy Check. + This is the default for :data:`FORMAT_XZ`. - * :const:`CHECK_SHA256`: 256-bit Secure Hash Algorithm. + * :data:`CHECK_SHA256`: 256-bit Secure Hash Algorithm. If the specified check is not supported, an :class:`LZMAError` is raised. @@ -190,8 +190,8 @@ Compressing and decompressing data in memory The *preset* argument (if provided) should be an integer between ``0`` and ``9`` (inclusive), optionally OR-ed with the constant - :const:`PRESET_EXTREME`. If neither *preset* nor *filters* are given, the - default behavior is to use :const:`PRESET_DEFAULT` (preset level ``6``). + :data:`PRESET_EXTREME`. If neither *preset* nor *filters* are given, the + default behavior is to use :data:`PRESET_DEFAULT` (preset level ``6``). Higher presets produce smaller output, but make the compression process slower. @@ -231,9 +231,9 @@ Compressing and decompressing data in memory once, see :func:`decompress`. The *format* argument specifies the container format that should be used. The - default is :const:`FORMAT_AUTO`, which can decompress both ``.xz`` and - ``.lzma`` files. Other possible values are :const:`FORMAT_XZ`, - :const:`FORMAT_ALONE`, and :const:`FORMAT_RAW`. + default is :data:`FORMAT_AUTO`, which can decompress both ``.xz`` and + ``.lzma`` files. Other possible values are :data:`FORMAT_XZ`, + :data:`FORMAT_ALONE`, and :data:`FORMAT_RAW`. The *memlimit* argument specifies a limit (in bytes) on the amount of memory that the decompressor can use. When this argument is used, decompression will @@ -242,7 +242,7 @@ Compressing and decompressing data in memory The *filters* argument specifies the filter chain that was used to create the stream being decompressed. This argument is required if *format* is - :const:`FORMAT_RAW`, but should not be used for other formats. + :data:`FORMAT_RAW`, but should not be used for other formats. See :ref:`filter-chain-specs` for more information about filter chains. .. note:: @@ -281,7 +281,7 @@ Compressing and decompressing data in memory .. attribute:: check The ID of the integrity check used by the input stream. This may be - :const:`CHECK_UNKNOWN` until enough of the input has been decoded to + :data:`CHECK_UNKNOWN` until enough of the input has been decoded to determine what integrity check it uses. .. attribute:: eof @@ -329,8 +329,8 @@ Miscellaneous Return ``True`` if the given integrity check is supported on this system. - :const:`CHECK_NONE` and :const:`CHECK_CRC32` are always supported. - :const:`CHECK_CRC64` and :const:`CHECK_SHA256` may be unavailable if you are + :data:`CHECK_NONE` and :data:`CHECK_CRC32` are always supported. + :data:`CHECK_CRC64` and :data:`CHECK_SHA256` may be unavailable if you are using a version of :program:`liblzma` that was compiled with a limited feature set. @@ -347,31 +347,31 @@ options. Valid filter IDs are as follows: * Compression filters: - * :const:`FILTER_LZMA1` (for use with :const:`FORMAT_ALONE`) - * :const:`FILTER_LZMA2` (for use with :const:`FORMAT_XZ` and :const:`FORMAT_RAW`) + * :data:`FILTER_LZMA1` (for use with :data:`FORMAT_ALONE`) + * :data:`FILTER_LZMA2` (for use with :data:`FORMAT_XZ` and :data:`FORMAT_RAW`) * Delta filter: - * :const:`FILTER_DELTA` + * :data:`FILTER_DELTA` * Branch-Call-Jump (BCJ) filters: - * :const:`!FILTER_X86` - * :const:`!FILTER_IA64` - * :const:`!FILTER_ARM` - * :const:`!FILTER_ARMTHUMB` - * :const:`!FILTER_POWERPC` - * :const:`!FILTER_SPARC` + * :data:`!FILTER_X86` + * :data:`!FILTER_IA64` + * :data:`!FILTER_ARM` + * :data:`!FILTER_ARMTHUMB` + * :data:`!FILTER_POWERPC` + * :data:`!FILTER_SPARC` The above work on all lzma runtime library versions. - * :const:`!FILTER_ARM64` + * :data:`!FILTER_ARM64` Only works if the lzma version is 5.4.0 or later. .. versionadded:: next - * :const:`!FILTER_RISCV` + * :data:`!FILTER_RISCV` Only works if the lzma version is 5.6.0 or later. @@ -392,11 +392,11 @@ entries in the dictionary representing the filter): * ``lp``: Number of literal position bits. The sum ``lc + lp`` must be at most 4. * ``pb``: Number of position bits; must be at most 4. -* ``mode``: :const:`MODE_FAST` or :const:`MODE_NORMAL`. +* ``mode``: :data:`MODE_FAST` or :data:`MODE_NORMAL`. * ``nice_len``: What should be considered a "nice length" for a match. This should be 273 or less. -* ``mf``: What match finder to use -- :const:`MF_HC3`, :const:`MF_HC4`, - :const:`MF_BT2`, :const:`MF_BT3`, or :const:`MF_BT4`. +* ``mf``: What match finder to use -- :data:`MF_HC3`, :data:`MF_HC4`, + :data:`MF_BT2`, :data:`MF_BT3`, or :data:`MF_BT4`. * ``depth``: Maximum search depth used by match finder. 0 (default) means to select automatically based on other filter options. From 1c9967daeb2e629fa24878aeec908baca4c2ba0e Mon Sep 17 00:00:00 2001 From: NotFoundOvO <1264472267@qq.com> Date: Mon, 29 Jun 2026 18:06:42 +0800 Subject: [PATCH 2/2] fix: add .. data:: directives for all lzma constants and remove from .nitignore - Added .. data:: directives for FORMAT_*, CHECK_*, FILTER_*, PRESET_*, MODE_*, and MF_* constants so Sphinx can resolve cross-references - Changed :data: back to :const: for proper cross-referencing - Removed Doc/library/lzma.rst from Doc/tools/.nitignore - Organized constants into logical sections with labels --- Doc/library/lzma.rst | 240 +++++++++++++++++++++++++++++++++++++------ Doc/tools/.nitignore | 1 - 2 files changed, 206 insertions(+), 35 deletions(-) diff --git a/Doc/library/lzma.rst b/Doc/library/lzma.rst index 7f2fce3755c671..97cda860fa52aa 100644 --- a/Doc/library/lzma.rst +++ b/Doc/library/lzma.rst @@ -29,6 +29,178 @@ from multiple threads, it is necessary to protect it with a lock. decompression, or while initializing the compressor/decompressor state. +.. _lzma-format-constants: + +Format constants +---------------- + +.. data:: FORMAT_XZ + + The ``.xz`` container format. This is the default format. + +.. data:: FORMAT_ALONE + + The legacy ``.lzma`` container format. This format is more limited than + ``.xz`` -- it does not support integrity checks or multiple filters. + +.. data:: FORMAT_RAW + + A raw data stream, not using any container format. This format specifier + does not support integrity checks, and requires that you always specify a + custom filter chain (for both compression and decompression). Additionally, + data compressed in this manner cannot be decompressed using + :const:`FORMAT_AUTO`. + +.. data:: FORMAT_AUTO + + Automatically determine the container format when decompressing. This is + the default for :class:`LZMADecompressor` and :func:`decompress`. + + +.. _lzma-check-constants: + +Check constants +--------------- + +.. data:: CHECK_NONE + + No integrity check. This is the default (and the only acceptable value) + for :const:`FORMAT_ALONE` and :const:`FORMAT_RAW`. + +.. data:: CHECK_CRC32 + + 32-bit Cyclic Redundancy Check. + +.. data:: CHECK_CRC64 + + 64-bit Cyclic Redundancy Check. This is the default for + :const:`FORMAT_XZ`. + +.. data:: CHECK_SHA256 + + 256-bit Secure Hash Algorithm. + +.. data:: CHECK_UNKNOWN + + Used by :attr:`LZMADecompressor.check` when the integrity check type + has not yet been determined. + +.. data:: CHECK_ID_MAX + + Maximum valid check ID. + + +.. _lzma-filter-constants: + +Filter constants +---------------- + +.. data:: FILTER_LZMA1 + + For use with :const:`FORMAT_ALONE`. + +.. data:: FILTER_LZMA2 + + For use with :const:`FORMAT_XZ` and :const:`FORMAT_RAW`. + +.. data:: FILTER_DELTA + + Delta filter. + +.. data:: FILTER_X86 + + Branch-Call-Jump filter for x86. + +.. data:: FILTER_IA64 + + Branch-Call-Jump filter for IA-64. + +.. data:: FILTER_ARM + + Branch-Call-Jump filter for ARM. + +.. data:: FILTER_ARMTHUMB + + Branch-Call-Jump filter for ARM Thumb. + +.. data:: FILTER_POWERPC + + Branch-Call-Jump filter for PowerPC. + +.. data:: FILTER_SPARC + + Branch-Call-Jump filter for SPARC. + +.. data:: FILTER_ARM64 + + Branch-Call-Jump filter for ARM64. Only works if the lzma version + is 5.4.0 or later. + + .. versionadded:: next + +.. data:: FILTER_RISCV + + Branch-Call-Jump filter for RISC-V. Only works if the lzma version + is 5.6.0 or later. + + .. versionadded:: next + + +.. _lzma-preset-constants: + +Preset constants +---------------- + +.. data:: PRESET_DEFAULT + + Default compression preset (level ``6``). + +.. data:: PRESET_EXTREME + + Extreme compression preset flag. Can be OR-ed with a preset level + (0--9) to use extreme mode. + + +.. _lzma-mode-constants: + +Mode constants +-------------- + +.. data:: MODE_FAST + + Fast compression mode. + +.. data:: MODE_NORMAL + + Normal compression mode. + + +.. _lzma-mf-constants: + +Match finder constants +---------------------- + +.. data:: MF_HC3 + + Hash Chain with 3 bytes hash. + +.. data:: MF_HC4 + + Hash Chain with 4 bytes hash. + +.. data:: MF_BT2 + + Binary Tree with 2 bytes hash. + +.. data:: MF_BT3 + + Binary Tree with 3 bytes hash. + +.. data:: MF_BT4 + + Binary Tree with 4 bytes hash. + + Reading and writing compressed files ------------------------------------ @@ -154,33 +326,33 @@ Compressing and decompressing data in memory The *format* argument specifies what container format should be used. Possible values are: - * :data:`FORMAT_XZ`: The ``.xz`` container format. + * :const:`FORMAT_XZ`: The ``.xz`` container format. This is the default format. - * :data:`FORMAT_ALONE`: The legacy ``.lzma`` container format. + * :const:`FORMAT_ALONE`: The legacy ``.lzma`` container format. This format is more limited than ``.xz`` -- it does not support integrity checks or multiple filters. - * :data:`FORMAT_RAW`: A raw data stream, not using any container format. + * :const:`FORMAT_RAW`: A raw data stream, not using any container format. This format specifier does not support integrity checks, and requires that you always specify a custom filter chain (for both compression and decompression). Additionally, data compressed in this manner cannot be - decompressed using :data:`FORMAT_AUTO` (see :class:`LZMADecompressor`). + decompressed using :const:`FORMAT_AUTO` (see :class:`LZMADecompressor`). The *check* argument specifies the type of integrity check to include in the compressed data. This check is used when decompressing, to ensure that the data has not been corrupted. Possible values are: - * :data:`CHECK_NONE`: No integrity check. + * :const:`CHECK_NONE`: No integrity check. This is the default (and the only acceptable value) for - :data:`FORMAT_ALONE` and :data:`FORMAT_RAW`. + :const:`FORMAT_ALONE` and :const:`FORMAT_RAW`. - * :data:`CHECK_CRC32`: 32-bit Cyclic Redundancy Check. + * :const:`CHECK_CRC32`: 32-bit Cyclic Redundancy Check. - * :data:`CHECK_CRC64`: 64-bit Cyclic Redundancy Check. - This is the default for :data:`FORMAT_XZ`. + * :const:`CHECK_CRC64`: 64-bit Cyclic Redundancy Check. + This is the default for :const:`FORMAT_XZ`. - * :data:`CHECK_SHA256`: 256-bit Secure Hash Algorithm. + * :const:`CHECK_SHA256`: 256-bit Secure Hash Algorithm. If the specified check is not supported, an :class:`LZMAError` is raised. @@ -190,8 +362,8 @@ Compressing and decompressing data in memory The *preset* argument (if provided) should be an integer between ``0`` and ``9`` (inclusive), optionally OR-ed with the constant - :data:`PRESET_EXTREME`. If neither *preset* nor *filters* are given, the - default behavior is to use :data:`PRESET_DEFAULT` (preset level ``6``). + :const:`PRESET_EXTREME`. If neither *preset* nor *filters* are given, the + default behavior is to use :const:`PRESET_DEFAULT` (preset level ``6``). Higher presets produce smaller output, but make the compression process slower. @@ -231,18 +403,18 @@ Compressing and decompressing data in memory once, see :func:`decompress`. The *format* argument specifies the container format that should be used. The - default is :data:`FORMAT_AUTO`, which can decompress both ``.xz`` and - ``.lzma`` files. Other possible values are :data:`FORMAT_XZ`, - :data:`FORMAT_ALONE`, and :data:`FORMAT_RAW`. + default is :const:`FORMAT_AUTO`, which can decompress both ``.xz`` and + ``.lzma`` files. Other possible values are :const:`FORMAT_XZ`, + :const:`FORMAT_ALONE`, and :const:`FORMAT_RAW`. The *memlimit* argument specifies a limit (in bytes) on the amount of memory - that the decompressor can use. When this argument is used, decompression will + that the decompressor can use. When this argument is used, decomposition will fail with an :class:`LZMAError` if it is not possible to decompress the input within the given memory limit. The *filters* argument specifies the filter chain that was used to create the stream being decompressed. This argument is required if *format* is - :data:`FORMAT_RAW`, but should not be used for other formats. + :const:`FORMAT_RAW`, but should not be used for other formats. See :ref:`filter-chain-specs` for more information about filter chains. .. note:: @@ -281,7 +453,7 @@ Compressing and decompressing data in memory .. attribute:: check The ID of the integrity check used by the input stream. This may be - :data:`CHECK_UNKNOWN` until enough of the input has been decoded to + :const:`CHECK_UNKNOWN` until enough of the input has been decoded to determine what integrity check it uses. .. attribute:: eof @@ -329,8 +501,8 @@ Miscellaneous Return ``True`` if the given integrity check is supported on this system. - :data:`CHECK_NONE` and :data:`CHECK_CRC32` are always supported. - :data:`CHECK_CRC64` and :data:`CHECK_SHA256` may be unavailable if you are + :const:`CHECK_NONE` and :const:`CHECK_CRC32` are always supported. + :const:`CHECK_CRC64` and :const:`CHECK_SHA256` may be unavailable if you are using a version of :program:`liblzma` that was compiled with a limited feature set. @@ -347,31 +519,31 @@ options. Valid filter IDs are as follows: * Compression filters: - * :data:`FILTER_LZMA1` (for use with :data:`FORMAT_ALONE`) - * :data:`FILTER_LZMA2` (for use with :data:`FORMAT_XZ` and :data:`FORMAT_RAW`) + * :const:`FILTER_LZMA1` (for use with :const:`FORMAT_ALONE`) + * :const:`FILTER_LZMA2` (for use with :const:`FORMAT_XZ` and :const:`FORMAT_RAW`) * Delta filter: - * :data:`FILTER_DELTA` + * :const:`FILTER_DELTA` * Branch-Call-Jump (BCJ) filters: - * :data:`!FILTER_X86` - * :data:`!FILTER_IA64` - * :data:`!FILTER_ARM` - * :data:`!FILTER_ARMTHUMB` - * :data:`!FILTER_POWERPC` - * :data:`!FILTER_SPARC` + * :const:`FILTER_X86` + * :const:`FILTER_IA64` + * :const:`FILTER_ARM` + * :const:`FILTER_ARMTHUMB` + * :const:`FILTER_POWERPC` + * :const:`FILTER_SPARC` The above work on all lzma runtime library versions. - * :data:`!FILTER_ARM64` + * :const:`FILTER_ARM64` Only works if the lzma version is 5.4.0 or later. .. versionadded:: next - * :data:`!FILTER_RISCV` + * :const:`FILTER_RISCV` Only works if the lzma version is 5.6.0 or later. @@ -392,11 +564,11 @@ entries in the dictionary representing the filter): * ``lp``: Number of literal position bits. The sum ``lc + lp`` must be at most 4. * ``pb``: Number of position bits; must be at most 4. -* ``mode``: :data:`MODE_FAST` or :data:`MODE_NORMAL`. +* ``mode``: :const:`MODE_FAST` or :const:`MODE_NORMAL`. * ``nice_len``: What should be considered a "nice length" for a match. This should be 273 or less. -* ``mf``: What match finder to use -- :data:`MF_HC3`, :data:`MF_HC4`, - :data:`MF_BT2`, :data:`MF_BT3`, or :data:`MF_BT4`. +* ``mf``: What match finder to use -- :const:`MF_HC3`, :const:`MF_HC4`, + :const:`MF_BT2`, :const:`MF_BT3`, or :const:`MF_BT4`. * ``depth``: Maximum search depth used by match finder. 0 (default) means to select automatically based on other filter options. diff --git a/Doc/tools/.nitignore b/Doc/tools/.nitignore index 2255c745c00383..ae091966f2def6 100644 --- a/Doc/tools/.nitignore +++ b/Doc/tools/.nitignore @@ -14,7 +14,6 @@ Doc/library/http.server.rst Doc/library/importlib.rst Doc/library/logging.config.rst Doc/library/logging.handlers.rst -Doc/library/lzma.rst Doc/library/mmap.rst Doc/library/multiprocessing.rst Doc/library/optparse.rst