FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

[3.13] gh-151949: Fix Sphinx reference warnings in `Doc/library/lzma.… · python/cpython@df98462 · GitHub

  1. python
  2. cpython

Repository navigation

Commit df98462

Browse files
authored
[3.13] gh-151949: Fix Sphinx reference warnings in Doc/library/lzma.rst (GH-153878) (#154126)
* gh-151949: Fix Sphinx reference warnings in `Doc/library/lzma.rst` (GH-153878) The lzma module constants (FORMAT_*, CHECK_*, PRESET_*, FILTER_*, MODE_* and MF_*) were referenced with the :const: role throughout the module documentation but were never defined as reference targets, producing "reference target not found" warnings under nitpicky mode. Document these public constants with .. data:: directives, following the convention used by the signal, socket and ssl modules, so the existing references resolve. The now-redundant inline descriptions of the format and check constants are condensed into linked references. (cherry picked from commit 1530b38) Co-authored-by: Vyron Vasileiadis <hi@fedonman.com> * Fix nitpicks --------- Co-authored-by: Vyron Vasileiadis <hi@fedonman.com> Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
1 parent 094c884 commit df98462

2 files changed

Lines changed: 111 additions & 33 deletions

File tree

‎Doc/library/lzma.rst‎

Lines changed: 111 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -153,35 +153,14 @@ Compressing and decompressing data in memory
153153
:func:`compress`.
154154

155155
The *format* argument specifies what container format should be used.
156-
Possible values are:
157-
158-
* :const:`FORMAT_XZ`: The ``.xz`` container format.
159-
This is the default format.
160-
161-
* :const:`FORMAT_ALONE`: The legacy ``.lzma`` container format.
162-
This format is more limited than ``.xz`` -- it does not support integrity
163-
checks or multiple filters.
164-
165-
* :const:`FORMAT_RAW`: A raw data stream, not using any container format.
166-
This format specifier does not support integrity checks, and requires that
167-
you always specify a custom filter chain (for both compression and
168-
decompression). Additionally, data compressed in this manner cannot be
169-
decompressed using :const:`FORMAT_AUTO` (see :class:`LZMADecompressor`).
156+
Possible values are :const:`FORMAT_XZ` (the default),
157+
:const:`FORMAT_ALONE` and :const:`FORMAT_RAW`.
170158

171159
The *check* argument specifies the type of integrity check to include in the
172160
compressed data. This check is used when decompressing, to ensure that the
173-
data has not been corrupted. Possible values are:
174-
175-
* :const:`CHECK_NONE`: No integrity check.
176-
This is the default (and the only acceptable value) for
177-
:const:`FORMAT_ALONE` and :const:`FORMAT_RAW`.
178-
179-
* :const:`CHECK_CRC32`: 32-bit Cyclic Redundancy Check.
180-
181-
* :const:`CHECK_CRC64`: 64-bit Cyclic Redundancy Check.
182-
This is the default for :const:`FORMAT_XZ`.
183-
184-
* :const:`CHECK_SHA256`: 256-bit Secure Hash Algorithm.
161+
data has not been corrupted. Possible values are :const:`CHECK_NONE`,
162+
:const:`CHECK_CRC32`, :const:`CHECK_CRC64` (the default for
163+
:const:`FORMAT_XZ`) and :const:`CHECK_SHA256`.
185164

186165
If the specified check is not supported, an :class:`LZMAError` is raised.
187166

@@ -357,12 +336,12 @@ options. Valid filter IDs are as follows:
357336

358337
* Branch-Call-Jump (BCJ) filters:
359338

360-
* :const:`FILTER_X86`
361-
* :const:`FILTER_IA64`
362-
* :const:`FILTER_ARM`
363-
* :const:`FILTER_ARMTHUMB`
364-
* :const:`FILTER_POWERPC`
365-
* :const:`FILTER_SPARC`
339+
* :const:`!FILTER_X86`
340+
* :const:`!FILTER_IA64`
341+
* :const:`!FILTER_ARM`
342+
* :const:`!FILTER_ARMTHUMB`
343+
* :const:`!FILTER_POWERPC`
344+
* :const:`!FILTER_SPARC`
366345

367346
A filter chain can consist of up to 4 filters, and cannot be empty. The last
368347
filter in the chain must be a compression filter, and any other filters must be
@@ -399,6 +378,106 @@ These filters support one option, ``start_offset``. This specifies the address
399378
that should be mapped to the beginning of the input data. The default is 0.
400379

401380

381+
Constants
382+
---------
383+
384+
The following module-level constants are provided for use as the *format*,
385+
*check*, *preset* and *filters* arguments of the classes and functions above.
386+
387+
Container formats:
388+
389+
.. data:: FORMAT_XZ
390+
391+
The ``.xz`` container format.
392+
393+
.. data:: FORMAT_ALONE
394+
395+
The legacy ``.lzma`` container format. This format is more limited than
396+
``.xz`` -- it does not support integrity checks or multiple filters.
397+
398+
.. data:: FORMAT_RAW
399+
400+
A raw data stream, not using any container format. This format specifier
401+
does not support integrity checks, and requires that you always specify a
402+
custom filter chain (for both compression and decompression). Additionally,
403+
data compressed in this manner cannot be decompressed using
404+
:const:`FORMAT_AUTO`.
405+
406+
.. data:: FORMAT_AUTO
407+
408+
Used for decompression only. The container format is detected
409+
automatically, so that both ``.xz`` and ``.lzma`` files can be decompressed.
410+
411+
Integrity checks:
412+
413+
.. data:: CHECK_NONE
414+
415+
No integrity check. This is the default (and the only acceptable value) for
416+
:const:`FORMAT_ALONE` and :const:`FORMAT_RAW`.
417+
418+
.. data:: CHECK_CRC32
419+
420+
A 32-bit Cyclic Redundancy Check.
421+
422+
.. data:: CHECK_CRC64
423+
424+
A 64-bit Cyclic Redundancy Check. This is the default for
425+
:const:`FORMAT_XZ`.
426+
427+
.. data:: CHECK_SHA256
428+
429+
A 256-bit Secure Hash Algorithm.
430+
431+
.. data:: CHECK_UNKNOWN
432+
433+
The integrity check used by a stream could not yet be determined. This may
434+
be the value of the :attr:`LZMADecompressor.check` attribute until enough of
435+
the input has been decoded.
436+
437+
.. data:: CHECK_ID_MAX
438+
439+
The largest supported integrity-check ID.
440+
441+
Compression presets:
442+
443+
.. data:: PRESET_DEFAULT
444+
445+
The default compression preset, equivalent to preset level ``6``.
446+
447+
.. data:: PRESET_EXTREME
448+
449+
A flag that may be bitwise OR-ed with a preset level (``0`` to ``9``) to
450+
select a slower but more thorough variant of that preset.
451+
452+
Filter IDs and options:
453+
454+
.. data:: FILTER_LZMA1
455+
FILTER_LZMA2
456+
457+
The LZMA1 and LZMA2 compression filters. :const:`FILTER_LZMA1` is for use
458+
with :const:`FORMAT_ALONE`, while :const:`FILTER_LZMA2` is for use with
459+
:const:`FORMAT_XZ` and :const:`FORMAT_RAW`.
460+
461+
.. data:: FILTER_DELTA
462+
463+
The delta filter.
464+
465+
.. data:: MODE_FAST
466+
MODE_NORMAL
467+
468+
Compression modes that may be used as the ``mode`` option of a filter
469+
specifier (see :ref:`filter-chain-specs`).
470+
471+
.. data:: MF_HC3
472+
MF_HC4
473+
MF_BT2
474+
MF_BT3
475+
MF_BT4
476+
477+
Match finders that may be used as the ``mf`` option of a filter specifier
478+
(see :ref:`filter-chain-specs`).
479+
480+
402481
Examples
403482
--------
404483

‎Doc/tools/.nitignore‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,6 @@ Doc/library/email.parser.rst
1515
Doc/library/importlib.rst
1616
Doc/library/logging.config.rst
1717
Doc/library/logging.handlers.rst
18-
Doc/library/lzma.rst
1918
Doc/library/mmap.rst
2019
Doc/library/multiprocessing.rst
2120
Doc/library/optparse.rst

0 commit comments

Comments
 (0)
Back | FazBrowse Home | New Git URL