[Python-checkins] [3.11] Docs: format sys.float_info properly (GH-108107) (#108131)
AlexWaygood
webhook-mailer at python.org
Sat Aug 19 05:13:12 EDT 2023
https://github.com/python/cpython/commit/0673d4c762d6dc4c742e71e76cee66181c457f24
commit: 0673d4c762d6dc4c742e71e76cee66181c457f24
branch: 3.11
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: AlexWaygood <Alex.Waygood at Gmail.com>
date: 2023-08-19T10:13:09+01:00
summary:
[3.11] Docs: format sys.float_info properly (GH-108107) (#108131)
Docs: format sys.float_info properly (GH-108107)
- Normalise capitalisation and punctuation
- Use attribute markup for named tuple attributes
- Use :c:macro: markup for C macros
- Use a list for the 'rounds' attribute values
- Use list-table, for better .rst readability
- Remove one unneeded sys.float_info.dig link
(cherry picked from commit ca0c6c1f1ef79d10bc49b61d638d87cde265aa94)
Co-authored-by: Erlend E. Aasland <erlend at python.org>
Co-authored-by: Adam Turner <9087854+AA-Turner at users.noreply.github.com>
files:
M Doc/library/sys.rst
diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst
index b5ad0b6860b95..08bf2d13572f4 100644
--- a/Doc/library/sys.rst
+++ b/Doc/library/sys.rst
@@ -570,61 +570,82 @@ always available.
programming language; see section 5.2.4.2.2 of the 1999 ISO/IEC C standard
[C99]_, 'Characteristics of floating types', for details.
- .. tabularcolumns:: |l|l|L|
-
- +---------------------+---------------------+--------------------------------------------------+
- | attribute | float.h macro | explanation |
- +=====================+=====================+==================================================+
- | ``epsilon`` | ``DBL_EPSILON`` | difference between 1.0 and the least value |
- | | | greater than 1.0 that is representable as a float|
- | | | |
- | | | See also :func:`math.ulp`. |
- +---------------------+---------------------+--------------------------------------------------+
- | ``dig`` | ``DBL_DIG`` | maximum number of decimal digits that can be |
- | | | faithfully represented in a float; see below |
- +---------------------+---------------------+--------------------------------------------------+
- | ``mant_dig`` | ``DBL_MANT_DIG`` | float precision: the number of base-``radix`` |
- | | | digits in the significand of a float |
- +---------------------+---------------------+--------------------------------------------------+
- | ``max`` | ``DBL_MAX`` | maximum representable positive finite float |
- +---------------------+---------------------+--------------------------------------------------+
- | ``max_exp`` | ``DBL_MAX_EXP`` | maximum integer *e* such that ``radix**(e-1)`` is|
- | | | a representable finite float |
- +---------------------+---------------------+--------------------------------------------------+
- | ``max_10_exp`` | ``DBL_MAX_10_EXP`` | maximum integer *e* such that ``10**e`` is in the|
- | | | range of representable finite floats |
- +---------------------+---------------------+--------------------------------------------------+
- | ``min`` | ``DBL_MIN`` | minimum representable positive *normalized* float|
- | | | |
- | | | Use :func:`math.ulp(0.0) <math.ulp>` to get the |
- | | | smallest positive *denormalized* representable |
- | | | float. |
- +---------------------+---------------------+--------------------------------------------------+
- | ``min_exp`` | ``DBL_MIN_EXP`` | minimum integer *e* such that ``radix**(e-1)`` is|
- | | | a normalized float |
- +---------------------+---------------------+--------------------------------------------------+
- | ``min_10_exp`` | ``DBL_MIN_10_EXP`` | minimum integer *e* such that ``10**e`` is a |
- | | | normalized float |
- +---------------------+---------------------+--------------------------------------------------+
- | ``radix`` | ``FLT_RADIX`` | radix of exponent representation |
- +---------------------+---------------------+--------------------------------------------------+
- | ``rounds`` | ``FLT_ROUNDS`` | integer representing the rounding mode for |
- | | | floating-point arithmetic. This reflects the |
- | | | value of the system ``FLT_ROUNDS`` macro at |
- | | | interpreter startup time: |
- | | | ``-1`` indeterminable, |
- | | | ``0`` toward zero, |
- | | | ``1`` to nearest, |
- | | | ``2`` toward positive infinity, |
- | | | ``3`` toward negative infinity |
- | | | |
- | | | All other values for ``FLT_ROUNDS`` characterize |
- | | | implementation-defined rounding behavior. |
- +---------------------+---------------------+--------------------------------------------------+
+ .. list-table:: Attributes of the :data:`!float_info` :term:`named tuple`
+ :header-rows: 1
+
+ * - attribute
+ - float.h macro
+ - explanation
+
+ * - .. attribute:: float_info.epsilon
+ - :c:macro:`!DBL_EPSILON`
+ - difference between 1.0 and the least value greater than 1.0 that is
+ representable as a float.
+
+ See also :func:`math.ulp`.
+
+ * - .. attribute:: float_info.dig
+ - :c:macro:`!DBL_DIG`
+ - The maximum number of decimal digits that can be faithfully
+ represented in a float; see below.
+
+ * - .. attribute:: float_info.mant_dig
+ - :c:macro:`!DBL_MANT_DIG`
+ - Float precision: the number of base-``radix`` digits in the
+ significand of a float.
+
+ * - .. attribute:: float_info.max
+ - :c:macro:`!DBL_MAX`
+ - The maximum representable positive finite float.
+
+ * - .. attribute:: float_info.max_exp
+ - :c:macro:`!DBL_MAX_EXP`
+ - The maximum integer *e* such that ``radix**(e-1)`` is a representable
+ finite float.
+
+ * - .. attribute:: float_info.max_10_exp
+ - :c:macro:`!DBL_MAX_10_EXP`
+ - The maximum integer *e* such that ``10**e`` is in the range of
+ representable finite floats.
+
+ * - .. attribute:: float_info.min
+ - :c:macro:`!DBL_MIN`
+ - The minimum representable positive *normalized* float.
+
+ Use :func:`math.ulp(0.0) <math.ulp>` to get the smallest positive
+ *denormalized* representable float.
+
+ * - .. attribute:: float_info.min_exp
+ - :c:macro:`!DBL_MIN_EXP`
+ - The minimum integer *e* such that ``radix**(e-1)`` is a normalized
+ float.
+
+ * - .. attribute:: float_info.min_10_exp
+ - :c:macro:`!DBL_MIN_10_EXP`
+ - The minimum integer *e* such that ``10**e`` is a normalized float.
+
+ * - .. attribute:: float_info.radix
+ - :c:macro:`!FLT_RADIX`
+ - The radix of exponent representation.
+
+ * - .. attribute:: float_info.rounds
+ - :c:macro:`!FLT_ROUNDS`
+ - An integer representing the rounding mode for floating-point arithmetic.
+ This reflects the value of the system :c:macro:`!FLT_ROUNDS` macro
+ at interpreter startup time:
+
+ * ``-1``: indeterminable
+ * ``0``: toward zero
+ * ``1``: to nearest
+ * ``2``: toward positive infinity
+ * ``3``: toward negative infinity
+
+ All other values for :c:macro:`!FLT_ROUNDS` characterize
+ implementation-defined rounding behavior.
The attribute :attr:`sys.float_info.dig` needs further explanation. If
``s`` is any string representing a decimal number with at most
- :attr:`sys.float_info.dig` significant digits, then converting ``s`` to a
+ :attr:`!sys.float_info.dig` significant digits, then converting ``s`` to a
float and back again will recover a string representing the same decimal
value::
More information about the Python-checkins
mailing list