From 3317466061509c83dce257caab3661d52571cab1 Mon Sep 17 00:00:00 2001
From: Teugea Ioan-Teodor <teodor.teugea@gmail.com>
Date: Fri, 30 Oct 2020 00:17:59 +0200
Subject: [PATCH] bpo-42061: Document __format__ for IP addresses (GH-23018)

Automerge-Triggered-By: GH:ericvsmith
---
 Doc/library/ipaddress.rst                     | 36 +++++++++++++++++--
 Doc/tools/susp-ignored.csv                    |  6 ++--
 .../2020-10-28-21-39-45.bpo-42061._x-0sg.rst  |  1 +
 3 files changed, 39 insertions(+), 4 deletions(-)
 create mode 100644 Misc/NEWS.d/next/Documentation/2020-10-28-21-39-45.bpo-42061._x-0sg.rst

diff --git a/Doc/library/ipaddress.rst b/Doc/library/ipaddress.rst
index 5f5e66412da..d6d1f1e3621 100644
--- a/Doc/library/ipaddress.rst
+++ b/Doc/library/ipaddress.rst
@@ -202,6 +202,32 @@ write code that handles both IP versions correctly.  Address objects are
 .. _iana-ipv4-special-registry: https://www.iana.org/assignments/iana-ipv4-special-registry/iana-ipv4-special-registry.xhtml
 .. _iana-ipv6-special-registry: https://www.iana.org/assignments/iana-ipv6-special-registry/iana-ipv6-special-registry.xhtml
 
+.. method:: IPv4Address.__format__(fmt)
+
+   Returns a string representation of the IP address, controlled by
+   an explicit format string.
+   *fmt* can be one of the following: ``'s'``, the default option,
+   equivalent to :func:`str`, ``'b'`` for a zero-padded binary string,
+   ``'X'`` or ``'x'`` for an uppercase or lowercase hexadecimal
+   representation, or ``'n'``, which is equivalent to ``'b'`` for IPv4
+   addresses and ``'x'`` for IPv6. For binary and hexadecimal
+   representations, the form specifier ``'#'`` and the grouping option
+   ``'_'`` are available. ``__format__`` is used by ``format``, ``str.format``
+   and f-strings.
+
+      >>> format(ipaddress.IPv4Address('192.168.0.1'))
+      '192.168.0.1'
+      >>> '{:#b}'.format(ipaddress.IPv4Address('192.168.0.1'))
+      '0b11000000101010000000000000000001'
+      >>> f'{ipaddress.IPv6Address("2001:db8::1000"):s}'
+      '2001:db8::1000'
+      >>> format(ipaddress.IPv6Address('2001:db8::1000'), '_X')
+      '2001_0DB8_0000_0000_0000_0000_0000_1000'
+      >>> '{:#_n}'.format(ipaddress.IPv6Address('2001:db8::1000'))
+      '0x2001_0db8_0000_0000_0000_0000_0000_1000'
+
+   .. versionadded:: 3.9
+
 
 .. class:: IPv6Address(address)
 
@@ -246,8 +272,8 @@ write code that handles both IP versions correctly.  Address objects are
    groups consisting entirely of zeroes included.
 
 
-   For the following attributes, see the corresponding documentation of the
-   :class:`IPv4Address` class:
+   For the following attributes and methods, see the corresponding
+   documentation of the :class:`IPv4Address` class:
 
    .. attribute:: packed
    .. attribute:: reverse_pointer
@@ -297,6 +323,12 @@ write code that handles both IP versions correctly.  Address objects are
       the embedded ``(server, client)`` IP address pair.  For any other
       address, this property will be ``None``.
 
+.. method:: IPv6Address.__format__(fmt)
+
+   Refer to the corresponding method documentation in
+   :class:`IPv4Address`.
+
+   .. versionadded:: 3.9
 
 Conversion to Strings and Integers
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
diff --git a/Doc/tools/susp-ignored.csv b/Doc/tools/susp-ignored.csv
index b15fd32b357..0c1dec70012 100644
--- a/Doc/tools/susp-ignored.csv
+++ b/Doc/tools/susp-ignored.csv
@@ -147,8 +147,10 @@ library/ipaddress,,:db8,IPv6Address('2001:db8::')
 library/ipaddress,,::,IPv6Address('2001:db8::')
 library/ipaddress,,:db8,>>> ipaddress.IPv6Address('2001:db8::1000')
 library/ipaddress,,::,>>> ipaddress.IPv6Address('2001:db8::1000')
-library/ipaddress,,:db8,IPv6Address('2001:db8::1000')
-library/ipaddress,,::,IPv6Address('2001:db8::1000')
+library/ipaddress,,:db8,'2001:db8::1000'
+library/ipaddress,,::,'2001:db8::1000'
+library/ipaddress,231,:db8,">>> f'{ipaddress.IPv6Address(""2001:db8::1000""):s}'"
+library/ipaddress,231,::,">>> f'{ipaddress.IPv6Address(""2001:db8::1000""):s}'"
 library/ipaddress,,::,IPv6Address('ff02::5678%1')
 library/ipaddress,,::,fe80::1234
 library/ipaddress,,:db8,">>> ipaddress.ip_address(""2001:db8::1"").reverse_pointer"
diff --git a/Misc/NEWS.d/next/Documentation/2020-10-28-21-39-45.bpo-42061._x-0sg.rst b/Misc/NEWS.d/next/Documentation/2020-10-28-21-39-45.bpo-42061._x-0sg.rst
new file mode 100644
index 00000000000..b38bb843501
--- /dev/null
+++ b/Misc/NEWS.d/next/Documentation/2020-10-28-21-39-45.bpo-42061._x-0sg.rst
@@ -0,0 +1 @@
+Document __format__ functionality for IP addresses.
\ No newline at end of file