From defdaceb4109b9f0aba38279fbb4c70124a56dde Mon Sep 17 00:00:00 2001 From: Matthieu Lienart Date: Sat, 19 Jul 2025 12:55:52 +0200 Subject: [PATCH 01/11] gh-136752: clarify ipaddress documentation of the is_reserved property --- Doc/library/ipaddress.rst | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/Doc/library/ipaddress.rst b/Doc/library/ipaddress.rst index e5bdfbb144b65a..4dec88a7d4d6f0 100644 --- a/Doc/library/ipaddress.rst +++ b/Doc/library/ipaddress.rst @@ -240,7 +240,10 @@ write code that handles both IP versions correctly. Address objects are .. attribute:: is_reserved - ``True`` if the address is otherwise IETF reserved. + ``True`` if the address is *labelled* as reserved by the IETF: + + * IPv4 address ``240.0.0.0/4`` named ``Reserved`` (see iana-ipv4-special-registry_) + * IPv6 addresses allocated as ``Reserved by IETF`` for future use (see iana-ipv6-address-space_) .. attribute:: is_loopback @@ -261,6 +264,7 @@ 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 +.. _iana-ipv6-address-space: https://www.iana.org/assignments/ipv6-address-space/ipv6-address-space.xhtml .. method:: IPv4Address.__format__(fmt) From 94fb99d9e17690c620b028e26013ea852b2fc316 Mon Sep 17 00:00:00 2001 From: Matthieu Lienart Date: Sat, 19 Jul 2025 14:11:33 +0200 Subject: [PATCH 02/11] add clarification to the ipaddress is_reserved property --- Doc/library/ipaddress.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Doc/library/ipaddress.rst b/Doc/library/ipaddress.rst index 4dec88a7d4d6f0..a427d430d268e1 100644 --- a/Doc/library/ipaddress.rst +++ b/Doc/library/ipaddress.rst @@ -242,7 +242,8 @@ write code that handles both IP versions correctly. Address objects are ``True`` if the address is *labelled* as reserved by the IETF: - * IPv4 address ``240.0.0.0/4`` named ``Reserved`` (see iana-ipv4-special-registry_) + * IPv4 address ``240.0.0.0/4`` named ``Reserved``. This attribute is not related to the + ``Reserved-by-Protocol`` value in iana-ipv4-special-registry_ * IPv6 addresses allocated as ``Reserved by IETF`` for future use (see iana-ipv6-address-space_) .. attribute:: is_loopback From 132dc9d3ee8234362c13f6e3054748822ed410a4 Mon Sep 17 00:00:00 2001 From: Matthieu Lienart Date: Sat, 19 Jul 2025 14:28:31 +0200 Subject: [PATCH 03/11] fix trailing space --- Doc/library/ipaddress.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/ipaddress.rst b/Doc/library/ipaddress.rst index a427d430d268e1..4483730bcf1774 100644 --- a/Doc/library/ipaddress.rst +++ b/Doc/library/ipaddress.rst @@ -242,7 +242,7 @@ write code that handles both IP versions correctly. Address objects are ``True`` if the address is *labelled* as reserved by the IETF: - * IPv4 address ``240.0.0.0/4`` named ``Reserved``. This attribute is not related to the + * IPv4 address ``240.0.0.0/4`` named ``Reserved``. This attribute is not related to the ``Reserved-by-Protocol`` value in iana-ipv4-special-registry_ * IPv6 addresses allocated as ``Reserved by IETF`` for future use (see iana-ipv6-address-space_) From 9f0e91ef96e8011fcafcf0262e11a09065aa8014 Mon Sep 17 00:00:00 2001 From: Matthieu Lienart Date: Sat, 19 Jul 2025 12:55:52 +0200 Subject: [PATCH 04/11] gh-136752: clarify ipaddress documentation of the is_reserved property --- Doc/library/ipaddress.rst | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/Doc/library/ipaddress.rst b/Doc/library/ipaddress.rst index e5bdfbb144b65a..4483730bcf1774 100644 --- a/Doc/library/ipaddress.rst +++ b/Doc/library/ipaddress.rst @@ -240,7 +240,11 @@ write code that handles both IP versions correctly. Address objects are .. attribute:: is_reserved - ``True`` if the address is otherwise IETF reserved. + ``True`` if the address is *labelled* as reserved by the IETF: + + * IPv4 address ``240.0.0.0/4`` named ``Reserved``. This attribute is not related to the + ``Reserved-by-Protocol`` value in iana-ipv4-special-registry_ + * IPv6 addresses allocated as ``Reserved by IETF`` for future use (see iana-ipv6-address-space_) .. attribute:: is_loopback @@ -261,6 +265,7 @@ 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 +.. _iana-ipv6-address-space: https://www.iana.org/assignments/ipv6-address-space/ipv6-address-space.xhtml .. method:: IPv4Address.__format__(fmt) From 40bf8d2507790e3431f02c1d6f800af17b5bd549 Mon Sep 17 00:00:00 2001 From: Matthieu Lienart Date: Sat, 19 Jul 2025 12:55:52 +0200 Subject: [PATCH 05/11] gh-136752: clarify ipaddress documentation of the is_reserved property fix trailing space --- Doc/library/ipaddress.rst | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/Doc/library/ipaddress.rst b/Doc/library/ipaddress.rst index e5bdfbb144b65a..4483730bcf1774 100644 --- a/Doc/library/ipaddress.rst +++ b/Doc/library/ipaddress.rst @@ -240,7 +240,11 @@ write code that handles both IP versions correctly. Address objects are .. attribute:: is_reserved - ``True`` if the address is otherwise IETF reserved. + ``True`` if the address is *labelled* as reserved by the IETF: + + * IPv4 address ``240.0.0.0/4`` named ``Reserved``. This attribute is not related to the + ``Reserved-by-Protocol`` value in iana-ipv4-special-registry_ + * IPv6 addresses allocated as ``Reserved by IETF`` for future use (see iana-ipv6-address-space_) .. attribute:: is_loopback @@ -261,6 +265,7 @@ 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 +.. _iana-ipv6-address-space: https://www.iana.org/assignments/ipv6-address-space/ipv6-address-space.xhtml .. method:: IPv4Address.__format__(fmt) From 0c23c092547f27399052a0ed3a34ff8383bdd157 Mon Sep 17 00:00:00 2001 From: Matthieu Lienart <50069805+mlnrt@users.noreply.github.com> Date: Sat, 19 Jul 2025 15:10:26 +0200 Subject: [PATCH 06/11] Update Doc/library/ipaddress.rst Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> --- Doc/library/ipaddress.rst | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/Doc/library/ipaddress.rst b/Doc/library/ipaddress.rst index 4483730bcf1774..9a5c03f15b68fa 100644 --- a/Doc/library/ipaddress.rst +++ b/Doc/library/ipaddress.rst @@ -240,11 +240,16 @@ write code that handles both IP versions correctly. Address objects are .. attribute:: is_reserved - ``True`` if the address is *labelled* as reserved by the IETF: + ``True`` if the address is noted as reserved by the IETF. + For IPv4, this is only ``240.0.0.0/4``, the "Reserved" address block. + For IPv6, this is all addresses `allocated `__ as + ``Reserved by IETF`` for future use. - * IPv4 address ``240.0.0.0/4`` named ``Reserved``. This attribute is not related to the - ``Reserved-by-Protocol`` value in iana-ipv4-special-registry_ - * IPv6 addresses allocated as ``Reserved by IETF`` for future use (see iana-ipv6-address-space_) + Note: ``is_reserved`` is not related to the "Reserved-by-Protocol" value. + + .. seealso:: + + iana-ipv4-special-registry_ .. attribute:: is_loopback From 6ad13b1366de1c6d7e1bb9194f919ea8ee7a5df8 Mon Sep 17 00:00:00 2001 From: Matthieu Lienart Date: Sat, 19 Jul 2025 15:28:25 +0200 Subject: [PATCH 07/11] homogenize references to address blocks tables --- Doc/library/ipaddress.rst | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/Doc/library/ipaddress.rst b/Doc/library/ipaddress.rst index 9a5c03f15b68fa..a19e2e17dc1617 100644 --- a/Doc/library/ipaddress.rst +++ b/Doc/library/ipaddress.rst @@ -241,15 +241,12 @@ write code that handles both IP versions correctly. Address objects are .. attribute:: is_reserved ``True`` if the address is noted as reserved by the IETF. - For IPv4, this is only ``240.0.0.0/4``, the "Reserved" address block. + For IPv4, this is only ``240.0.0.0/4``, the ``Reserved`` address block. For IPv6, this is all addresses `allocated `__ as ``Reserved by IETF`` for future use. - Note: ``is_reserved`` is not related to the "Reserved-by-Protocol" value. - - .. seealso:: - - iana-ipv4-special-registry_ + Note: ``is_reserved`` is not related to the IPv4 address block value of the + ``Reserved-by-Protocol`` column in iana-ipv4-special-registry_. .. attribute:: is_loopback From 9bae0298f66ea02577438e4b8c5017160be2dc81 Mon Sep 17 00:00:00 2001 From: Matthieu Lienart Date: Sat, 19 Jul 2025 15:57:04 +0200 Subject: [PATCH 08/11] add mention about IPv6 former site-local address block. --- Doc/library/ipaddress.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Doc/library/ipaddress.rst b/Doc/library/ipaddress.rst index a19e2e17dc1617..6df68993ebb207 100644 --- a/Doc/library/ipaddress.rst +++ b/Doc/library/ipaddress.rst @@ -243,7 +243,8 @@ write code that handles both IP versions correctly. Address objects are ``True`` if the address is noted as reserved by the IETF. For IPv4, this is only ``240.0.0.0/4``, the ``Reserved`` address block. For IPv6, this is all addresses `allocated `__ as - ``Reserved by IETF`` for future use. + ``Reserved by IETF`` for future use, except ``fec0::/10`` a former Site-Local scoped + address prefix (see :attr:`~IPv6Address.is_site_local`). Note: ``is_reserved`` is not related to the IPv4 address block value of the ``Reserved-by-Protocol`` column in iana-ipv4-special-registry_. From 5a0b8e14b058cdefc1282c9f07c91e9126f656db Mon Sep 17 00:00:00 2001 From: Matthieu Lienart Date: Sat, 19 Jul 2025 16:19:40 +0200 Subject: [PATCH 09/11] make use of note and caution markers --- Doc/library/ipaddress.rst | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/Doc/library/ipaddress.rst b/Doc/library/ipaddress.rst index 6df68993ebb207..401c120894b5fe 100644 --- a/Doc/library/ipaddress.rst +++ b/Doc/library/ipaddress.rst @@ -243,11 +243,13 @@ write code that handles both IP versions correctly. Address objects are ``True`` if the address is noted as reserved by the IETF. For IPv4, this is only ``240.0.0.0/4``, the ``Reserved`` address block. For IPv6, this is all addresses `allocated `__ as - ``Reserved by IETF`` for future use, except ``fec0::/10`` a former Site-Local scoped - address prefix (see :attr:`~IPv6Address.is_site_local`). + ``Reserved by IETF`` for future use. - Note: ``is_reserved`` is not related to the IPv4 address block value of the - ``Reserved-by-Protocol`` column in iana-ipv4-special-registry_. + .. note:: For IPv4, ``is_reserved`` is not related to the address block value of the + ``Reserved-by-Protocol`` column in iana-ipv4-special-registry_. + + .. caution:: For IPv6, ``fec0::/10`` a former Site-Local scoped address prefix is + currently excluded from that list (see :attr:`~IPv6Address.is_site_local`). .. attribute:: is_loopback From 34b8de3b7fab37794d8eb4969c42d7f99507f33a Mon Sep 17 00:00:00 2001 From: Matthieu Lienart Date: Sat, 19 Jul 2025 16:28:12 +0200 Subject: [PATCH 10/11] fix linting --- Doc/library/ipaddress.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/ipaddress.rst b/Doc/library/ipaddress.rst index 401c120894b5fe..405b55ee8b5b69 100644 --- a/Doc/library/ipaddress.rst +++ b/Doc/library/ipaddress.rst @@ -247,7 +247,7 @@ write code that handles both IP versions correctly. Address objects are .. note:: For IPv4, ``is_reserved`` is not related to the address block value of the ``Reserved-by-Protocol`` column in iana-ipv4-special-registry_. - + .. caution:: For IPv6, ``fec0::/10`` a former Site-Local scoped address prefix is currently excluded from that list (see :attr:`~IPv6Address.is_site_local`). From 350417d58bb9c9a32b39ddc05dde6d60f7cbc5c7 Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+AA-Turner@users.noreply.github.com> Date: Sat, 19 Jul 2025 15:38:15 +0100 Subject: [PATCH 11/11] RFC --- Doc/library/ipaddress.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/ipaddress.rst b/Doc/library/ipaddress.rst index 405b55ee8b5b69..9e887d8e65741b 100644 --- a/Doc/library/ipaddress.rst +++ b/Doc/library/ipaddress.rst @@ -249,7 +249,7 @@ write code that handles both IP versions correctly. Address objects are ``Reserved-by-Protocol`` column in iana-ipv4-special-registry_. .. caution:: For IPv6, ``fec0::/10`` a former Site-Local scoped address prefix is - currently excluded from that list (see :attr:`~IPv6Address.is_site_local`). + currently excluded from that list (see :attr:`~IPv6Address.is_site_local` & :rfc:`3879`). .. attribute:: is_loopback