PEP 682: Format Specifier for Signed Zero

.github/CODEOWNERS

@@ -555,6 +555,7 @@ pep-0677.rst  @gvanrossum
 pep-0678.rst  @iritkatriel
 pep-0679.rst  @pablogsal
 pep-0680.rst  @encukou
+pep-0682.rst  @mdickinson
 # ...
 # pep-0754.txt
 # ...

pep-0682.rst

@@ -0,0 +1,183 @@
+PEP: 682
+Title: Format Specifier for Signed Zero
+Author: John Belmonte <john@neggie.net>
+Sponsor: Mark Dickinson <dickinsm@gmail.com>
+Discussions-To:
+Status: Draft
+Type: Standards Track
+Content-Type: text/x-rst
+Created: 29-Jan-2022
+Python-Version: 3.11
+Post-History:
+
+
+Abstract
+========
+
+Though ``float`` and ``Decimal`` types can represent `signed zero`_, in many fields
+of mathematics, negative zero is surprising or unwanted -- especially
+in the context of displaying an (often rounded) numerical result.  This PEP
+proposes an extension to the `string format specification`_, allowing negative
+zero to be normalized to positive zero.
+
+.. _`signed zero`: https://en.wikipedia.org/wiki/Signed_zero
+.. _`string format specification`: https://docs.python.org/3/library/string.html#formatstrings
+
+
+Motivation
+==========
+
+Here is negative zero:
+
+.. code-block:: pycon
+
+    >>> x = -0.
+    >>> x
+    -0.0
+
+When formatting a number, negative zero can result from rounding.  Assuming
+the user's intention is truly to discard precision, the distinction between
+negative and positive zero of the rounded result might be considered an
+unwanted artifact:
+
+.. code-block:: pycon
+
+    >>> for x in (.002, -.001, .060):
+    ...     print(f'{x: .1f}')
+     0.0
+    -0.0
+     0.1
+
+There are various approaches to clearing the sign of a negative zero.  It
+can be achieved without a conditional by adding positive zero:
+
+.. code-block:: pycon
+
+    >>> x = -0.
+    >>> x + 0.
+    0.0
+
+To normalize negative zero when formatting, it is necessary to perform
+a redundant (and error-prone) pre-rounding of the input:
+
+.. code-block:: pycon
+
+    >>> for x in (.002, -.001, .060):
+    ...     print(f'{round(x, 1) + 0.: .1f}')
+     0.0
+     0.0
+     0.1
+
+What we would like instead is a first-class option to normalize negative
+zero, on top of everything else that numerical string formatting already
+offers.
+
+
+Rationale
+=========
+
+There are use cases where negative zero is unwanted in formatted number
+output -- arguably it's the more common case.  Expanding the format
+specification is the best way to support this because number formatting
+already incorporates rounding, and the normalization of negative zero must
+happen after rounding.
+
+While it is possible to pre-round and normalize a number before formatting,
+it's tedious and prone to error if the rounding doesn't precisely match
+that of the format spec.  Furthermore, functions that wrap formatting would
+find themselves having to parse format specs to extract the precision
+information.  For example, consider how this utility for formatting
+one-dimensional numerical arrays would be complicated by such pre-rounding:
+
+.. code-block:: python
+
+    def format_vector(v, format_spec='8.2f'):
+        """Format a vector (any iterable) using given per-term format string."""
+        return f"[{','.join(f'{term:{format_spec}}' for term in v)}]"
+
+The solution must be opt-in, because we can't change the behavior of
+programs that may be expecting or relying on negative zero when formatting
+numbers.
+
+The proposed extension is intentionally ``[sign][z]`` rather than
+``[sign[z]]``.  The default for ``sign`` (``-``) is not widely known or
+explicitly written, so this avoids everyone having to learn it just to use
+the ``z`` option.
+
+While f-strings, built-in ``format``, and ``str.format()`` can access the
+new option, %-formatting cannot.  There is already precedent for not
+extending %-formatting with new options, as was the case for the
+``,`` option (:pep:`378`).
+
+To date, there doesn't appear to be other widely-used languages or libraries
+providing such a formatting option for negative zero.  However, the same
+``z`` option syntax and semantics has been `proposed for C++ std::format()`_.
+While the proposal was withdrawn for C++20, a consensus proposal is promised
+for C++23.  (For what it's worth, the original `feature request`_ prompting
+this PEP was argued without knowledge of the C++ proposal.)
+
+.. _`proposed for C++ std::format()`: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2020/p1496r2.pdf
+.. _`feature request`: https://bugs.python.org/issue45995
+
+
+Specification
+=============
+
+An optional, literal ``z`` is added to the
+`Format Specification Mini-Language`_ following ``sign``:
+
+.. code-block:: text
+
+    [[fill]align][sign][z][#][0][width][grouping_option][.precision][type]
+
+where ``z`` is allowed for numerical types other than integer.  Support for
+``z`` is provided by the ``__format__()`` method of each numeric type,
+allowing the specifier to be used in f-strings, built-in ``format()``, and
+``str.format()``.  The %-formatting style will not support the new option.
+
+Synopsis:
+
+.. code-block:: pycon
+
+    >>> x = -.00001
+    >>> f'{x:z.1f}'
+    '0.0'
+
+    >>> x = decimal.Decimal('-.00001')
+    >>> '{:+z.1f}'.format(x)
+    '+0.0'
+
+.. _`Format Specification Mini-Language`: https://docs.python.org/3/library/string.html#format-specification-mini-language
+
+
+Backwards Compatibility
+=======================
+
+The new formatting behavior is opt-in, so numerical formatting of existing
+programs will not be affected.
+
+
+Reference Implementation
+========================
+
+A reference implementation exists at `pull request #30049`_.
+
+.. _`pull request #30049`: https://github.com/python/cpython/pull/30049
+
+
+Copyright
+=========
+
+This document is placed in the public domain or under the
+CC0-1.0-Universal license, whichever is more permissive.
+
+
+
+..
+   Local Variables:
+   mode: indented-text
+   indent-tabs-mode: nil
+   sentence-end-double-space: t
+   fill-column: 70
+   coding: utf-8
+   End: