[Python-checkins] bpo-39096: Format specification documentation fixes for numeric types (GH-23575)
miss-islington
webhook-mailer at python.org
Fri Dec 18 04:34:32 EST 2020
https://github.com/python/cpython/commit/12032cdec5ae1e56d4e4b8206fb2e9cccc5a9f58
commit: 12032cdec5ae1e56d4e4b8206fb2e9cccc5a9f58
branch: 3.8
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: miss-islington <31488909+miss-islington at users.noreply.github.com>
date: 2020-12-18T01:34:24-08:00
summary:
bpo-39096: Format specification documentation fixes for numeric types (GH-23575)
(cherry picked from commit 886b2e5c7a2caf87070728dba8f18c3d65e51071)
Co-authored-by: Mark Dickinson <mdickinson at enthought.com>
files:
M Doc/library/string.rst
diff --git a/Doc/library/string.rst b/Doc/library/string.rst
index 5542e9b727a6b..54786d0c2ab0d 100644
--- a/Doc/library/string.rst
+++ b/Doc/library/string.rst
@@ -514,6 +514,8 @@ The available presentation types for :class:`float` and
| | this rounds the number to ``p`` significant digits and |
| | then formats the result in either fixed-point format |
| | or in scientific notation, depending on its magnitude. |
+ | | A precision of ``0`` is treated as equivalent to a |
+ | | precision of ``1``. |
| | |
| | The precise rules are as follows: suppose that the |
| | result formatted with presentation type ``'e'`` and |
@@ -528,16 +530,19 @@ The available presentation types for :class:`float` and
| | removed if there are no remaining digits following it, |
| | unless the ``'#'`` option is used. |
| | |
+ | | With no precision given, uses a precision of ``6`` |
+ | | significant digits for :class:`float`. For |
+ | | :class:`~decimal.Decimal`, the coefficient of the result |
+ | | is formed from the coefficient digits of the value; |
+ | | scientific notation is used for values smaller than |
+ | | ``1e-6`` in absolute value and values where the place |
+ | | value of the least significant digit is larger than 1, |
+ | | and fixed-point notation is used otherwise. |
+ | | |
| | Positive and negative infinity, positive and negative |
| | zero, and nans, are formatted as ``inf``, ``-inf``, |
| | ``0``, ``-0`` and ``nan`` respectively, regardless of |
| | the precision. |
- | | |
- | | A precision of ``0`` is treated as equivalent to a |
- | | precision of ``1``. With no precision given, uses a |
- | | precision of ``6`` significant digits for |
- | | :class:`float`, and shows all coefficient digits |
- | | for :class:`~decimal.Decimal`. |
+---------+----------------------------------------------------------+
| ``'G'`` | General format. Same as ``'g'`` except switches to |
| | ``'E'`` if the number gets too large. The |
@@ -550,12 +555,18 @@ The available presentation types for :class:`float` and
| ``'%'`` | Percentage. Multiplies the number by 100 and displays |
| | in fixed (``'f'``) format, followed by a percent sign. |
+---------+----------------------------------------------------------+
- | None | Similar to ``'g'``, except that fixed-point notation, |
- | | when used, has at least one digit past the decimal point.|
- | | The default precision is as high as needed to represent |
- | | the particular value. The overall effect is to match the |
- | | output of :func:`str` as altered by the other format |
- | | modifiers. |
+ | None | For :class:`float` this is the same as ``'g'``, except |
+ | | that when fixed-point notation is used to format the |
+ | | result, it always includes at least one digit past the |
+ | | decimal point. The precision used is as large as needed |
+ | | to represent the given value faithfully. |
+ | | |
+ | | For :class:`~decimal.Decimal`, this is the same as |
+ | | either ``'g'`` or ``'G'`` depending on the value of |
+ | | ``context.capitals`` for the current decimal context. |
+ | | |
+ | | The overall effect is to match the output of :func:`str` |
+ | | as altered by the other format modifiers. |
+---------+----------------------------------------------------------+
More information about the Python-checkins
mailing list