Documentation cleanup.

python · gpshead · Sep 2, 2022 · May 5, 2020 · Jan 19, 2022 · Jan 19, 2022
commit f4372cc5cd6055436c04ab8c13e5bd0f4975d3cd
diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
@@ -5473,23 +5473,23 @@ Integer string conversion length limitation
 ===========================================
 
 CPython has a global limit for converting between :class:`int` and :class:`str`
-to mitigate denial of service attacks. This limit *only* applies to
-non-power-of-two number bases such as decimal. Hexidecimal, octal, and binary
-are not limited. The limit can be configured.
+to mitigate denial of service attacks. This limit *only* applies to decimal or
+other non-power-of-two number bases. Hexidecimal, octal, and binary conversions
+are unlimited. The limit can be configured.
 
-The limit is necessary because CPython's integer type is an abitrary length
-number (commonly known as a bignum) stored in binary form. There exists no
-algorithm that can convert a string to a binary integer or a binary integer to
-a string in linear time, unless the base is a power of 2. Even the best known
-algorithms for base 10 have sub-quadratic complexity. Converting a large value
-such as ``int('1' * 500_000)`` can take over a second on a fast CPU.
+The :class:`int` type in CPython is an abitrary length number stored in binary
+form (commonly known as a "bignum"). There exists no algorithm that can convert
+a string to a binary integer or a binary integer to a string in linear time,
+*unless* the base is a power of 2. Even the best known algorithms for base 10
+have sub-quadratic complexity. Converting a large value such as ``int('1' *
+500_000)`` can take over a second on a fast CPU.
 
 Limiting conversion size offers a practical way to avoid `CVE-2020-10735
 <https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2020-10735>`_.
 
 The limit is applied to the number of digit characters in the input or output
-string. That means that higher bases can process larger numbers before the
-limit triggers. Underscores and the sign are not counted towards the limit.
+string when a non-linear conversion algorithm would be involved.  Underscores
+and the sign are not counted towards the limit.
 
 When an operation would exceed the limit, a :exc:`ValueError` is raised::
 
@@ -5509,12 +5509,12 @@ When an operation would exceed the limit, a :exc:`ValueError` is raised::
    ValueError: Exceeds the limit (4300) for integer string conversion: value has 8599 digits.
    >>> len(hex(i_squared))
    7144
-   >>> assert int(hex(i_squared), base=16) == i
+   >>> assert int(hex(i_squared), base=16) == i  # Hexidecimal is unlimited.
 
-The default limit is 4300 digits as seen in
-:data:`sys.int_info.default_max_str_digits <sys.int_info>`. The smallest limit
-is 640 digits as seen in :data:`sys.int_info.str_digits_check_threshold
-<sys.int_info>`.
+The default limit is 4300 digits as provided in
+:data:`sys.int_info.default_max_str_digits <sys.int_info>`.
+The lowest limit that can be configured is 640 digits as provided in
+:data:`sys.int_info.str_digits_check_threshold <sys.int_info>`.
 
 Verification::
 
@@ -5532,14 +5532,14 @@ Affected APIs
 -------------
 
 The limition only applies to potentially slow conversions between :class:`int`
-and :class:`str`:
+and :class:`str` or :class:`bytes`:
 
 * ``int(string)`` with default base 10.
 * ``int(string, base)`` for all bases that are not a power of 2.
 * ``str(integer)``.
 * ``repr(integer)``
 * any other string conversion to base 10, for example ``f"{integer}"``,
-  ``"{}".format(integer)``, or ``"%d" % integer``.
+  ``"{}".format(integer)``, or ``b"%d" % integer``.
 
 The limitations do not apply to functions with a linear algorithm:
 
@@ -5557,7 +5557,7 @@ Before Python starts up you can use an environment variable or an interpreter
 command line flag to configure the limit:
 
 * :envvar:`PYTHONINTMAXSTRDIGITS`, e.g.
-  ``PYTHONINTMAXSTRDIGITS=640 python3`` to set the limit to ``640`` or
+  ``PYTHONINTMAXSTRDIGITS=640 python3`` to set the limit to 640 or
   ``PYTHONINTMAXSTRDIGITS=0 python3`` to disable the limitation.
 * :option:`-X int_max_str_digits <-X>`, e.g.
   ``python3 -X int_max_str_digits=640``
@@ -5578,8 +5578,8 @@ Information about the default and minimum can be found in :attr:`sys.int_info`:
 
 * :data:`sys.int_info.default_max_str_digits <sys.int_info>` is the compiled-in
   default limit.
-* :data:`sys.int_info.str_digits_check_threshold <sys.int_info>` is the minimum
-  accepted value for the limit.
+* :data:`sys.int_info.str_digits_check_threshold <sys.int_info>` is the lowest
+  accepted value for the limit (other than 0 which disables it).
 
 .. versionadded:: 3.12
 
@@ -5596,16 +5596,16 @@ Information about the default and minimum can be found in :attr:`sys.int_info`:
 
    Test your application thoroughly if you use a low limit. Ensure your tests
    run with the limit set early via the environment or flag so that it applies
-   during startup and even during any installation step that may precompile
-   source to ``.pyc`` files.
+   during startup and even during any installation step that may invoke Python
+   to precompile ``.py`` sources to ``.pyc`` files.
 
 Recommended configuration
 -------------------------
 
 The default :data:`sys.int_info.default_max_str_digits` is expected to be
 reasonable for most applications. If your application requires a different
 limit, set it from your main entry point using Python version agnostic code as
-these APIs were added in patch releases before 3.12.
+these APIs were added in security patch releases in versions before 3.12.
 
 Example::
 

diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst
@@ -502,27 +502,27 @@ always available.
    The :term:`named tuple` *flags* exposes the status of command line
    flags. The attributes are read only.
 
-   ================================== ======================================================================================================
-   attribute                          flag
-   ================================== ======================================================================================================
-   :const:`debug`                     :option:`-d`
-   :const:`inspect`                   :option:`-i`
-   :const:`interactive`               :option:`-i`
-   :const:`isolated`                  :option:`-I`
-   :const:`optimize`                  :option:`-O` or :option:`-OO`
-   :const:`dont_write_bytecode`       :option:`-B`
-   :const:`no_user_site`              :option:`-s`
-   :const:`no_site`                   :option:`-S`
-   :const:`ignore_environment`        :option:`-E`
-   :const:`verbose`                   :option:`-v`
-   :const:`bytes_warning`             :option:`-b`
-   :const:`quiet`                     :option:`-q`
-   :const:`hash_randomization`        :option:`-R`
-   :const:`dev_mode`                  :option:`-X dev <-X>` (:ref:`Python Development Mode <devmode>`)
-   :const:`utf8_mode`                 :option:`-X utf8 <-X>`
-   :const:`safe_path`                 :option:`-P`
-   :const:`int_max_str_digits`        :option:`-X int_max_str_digits <-X>` (:ref:`integer string conversion length limitation <int_max_str_digits>`)
-   ================================== ======================================================================================================
+   ============================= ==============================================================================================================
+   attribute                     flag
+   ============================= ==============================================================================================================
+   :const:`debug`                :option:`-d`
+   :const:`inspect`              :option:`-i`
+   :const:`interactive`          :option:`-i`
+   :const:`isolated`             :option:`-I`
+   :const:`optimize`             :option:`-O` or :option:`-OO`
+   :const:`dont_write_bytecode`  :option:`-B`
+   :const:`no_user_site`         :option:`-s`
+   :const:`no_site`              :option:`-S`
+   :const:`ignore_environment`   :option:`-E`
+   :const:`verbose`              :option:`-v`
+   :const:`bytes_warning`        :option:`-b`
+   :const:`quiet`                :option:`-q`
+   :const:`hash_randomization`   :option:`-R`
+   :const:`dev_mode`             :option:`-X dev <-X>` (:ref:`Python Development Mode <devmode>`)
+   :const:`utf8_mode`            :option:`-X utf8 <-X>`
+   :const:`safe_path`            :option:`-P`
+   :const:`int_max_str_digits`   :option:`-X int_max_str_digits <-X>` (:ref:`integer string conversion length limitation <int_max_str_digits>`)
+   ============================= ==============================================================================================================
 
    .. versionchanged:: 3.2
       Added ``quiet`` attribute for the new :option:`-q` flag.
@@ -729,8 +729,8 @@ always available.
 
 .. function:: get_int_max_str_digits()
 
-   Return current global value for :ref:`integer string conversion length
-   limitation <int_max_str_digits>`. See also :func:`set_int_max_str_digits`
+   Returns the current value for the :ref:`integer string conversion length
+   limitation <int_max_str_digits>`. See also :func:`set_int_max_str_digits`.
 
    .. versionadded:: 3.12
 
@@ -1333,8 +1333,9 @@ always available.
 
 .. function:: set_int_max_str_digits(n)
 
-   Set global interpreter limit for :ref:`integer string conversion length
-   limitation <int_max_str_digits>`. See also :func:`get_int_max_str_digits`
+   Set the :ref:`integer string conversion length limitation
+   <int_max_str_digits>` used by this interpreter. See also
+   :func:`get_int_max_str_digits`.
 
    .. versionadded:: 3.12