Skip to content

GH-65056: Improve the IP address' is_global/is_private documentation #113186

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Mar 18, 2024
Merged

GH-65056: Improve the IP address' is_global/is_private documentation #113186

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
533b97f
GH-65056: Improve the IP address' is_global/is_private documentation
jstasiak Dec 15, 2023
497eaf9
Update Doc/library/ipaddress.rst
jstasiak Mar 13, 2024
deb8b19
Update Doc/library/ipaddress.rst
jstasiak Mar 13, 2024
d115f17
Update Doc/library/ipaddress.rst
jstasiak Mar 13, 2024
3c6775f
Update Lib/ipaddress.py
jstasiak Mar 13, 2024
c43f0da
Update Lib/ipaddress.py
jstasiak Mar 13, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 23 additions & 4 deletions Doc/library/ipaddress.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -188,15 +188,34 @@ write code that handles both IP versions correctly. Address objects are

.. attribute:: is_private

``True`` if the address is allocated for private networks. See
``True`` if the address is defined as not globally reachable by
iana-ipv4-special-registry_ (for IPv4) or iana-ipv6-special-registry_
(for IPv6).
(for IPv6) with the following exceptions:

* ``is_private`` is ``False`` for the shared address space (``100.64.0.0/10``)
* For IPv4-mapped IPv6-addresses the ``is_private`` value is determined by the
semantics of the underlying IPv4 addresses and the following condition holds
(see :attr:`IPv6Address.ipv4_mapped`)::

address.is_private == address.ipv4_mapped.is_private

``is_private`` has value opposite to :attr:`is_global`, except for the shared address space
(``100.64.0.0/10`` range) where they are both ``False``.

.. attribute:: is_global

``True`` if the address is allocated for public networks. See
``True`` if the address is defined as globally reachable by
iana-ipv4-special-registry_ (for IPv4) or iana-ipv6-special-registry_
(for IPv6).
(for IPv6) with the following exception:

For IPv4-mapped IPv6-addresses the ``is_private`` value is determined by the
semantics of the underlying IPv4 addresses and the following condition holds
(see :attr:`IPv6Address.ipv4_mapped`)::

address.is_global == address.ipv4_mapped.is_global

``is_global`` has value opposite to :attr:`is_private`, except for the shared address space
(``100.64.0.0/10`` range) where they are both ``False``.

.. versionadded:: 3.4

Expand Down
58 changes: 45 additions & 13 deletions Lib/ipaddress.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1333,18 +1333,38 @@ def is_reserved(self):
@property
@functools.lru_cache()
def is_private(self):
"""Test if this address is allocated for private networks.
"""``True`` if the address is defined as not globally reachable by
iana-ipv4-special-registry_ (for IPv4) or iana-ipv6-special-registry_
(for IPv6) with the following exceptions:

Returns:
A boolean, True if the address is reserved per
iana-ipv4-special-registry.
* ``is_private`` is ``False`` for ``100.64.0.0/10``
* For IPv4-mapped IPv6-addresses the ``is_private`` value is determined by the
semantics of the underlying IPv4 addresses and the following condition holds
(see :attr:`IPv6Address.ipv4_mapped`)::

address.is_private == address.ipv4_mapped.is_private

``is_private`` has value opposite to :attr:`is_global`, except for the ``100.64.0.0/10``
IPv4 range where they are both ``False``.
"""
return any(self in net for net in self._constants._private_networks)

@property
@functools.lru_cache()
def is_global(self):
"""``True`` if the address is defined as globally reachable by
iana-ipv4-special-registry_ (for IPv4) or iana-ipv6-special-registry_
(for IPv6) with the following exception:

For IPv4-mapped IPv6-addresses the ``is_private`` value is determined by the
semantics of the underlying IPv4 addresses and the following condition holds
(see :attr:`IPv6Address.ipv4_mapped`)::

address.is_global == address.ipv4_mapped.is_global

``is_global`` has value opposite to :attr:`is_private`, except for the ``100.64.0.0/10``
IPv4 range where they are both ``False``.
"""
return self not in self._constants._public_network and not self.is_private

@property
Expand Down Expand Up @@ -2049,13 +2069,19 @@ def is_site_local(self):
@property
@functools.lru_cache()
def is_private(self):
"""Test if this address is allocated for private networks.
"""``True`` if the address is defined as not globally reachable by
iana-ipv4-special-registry_ (for IPv4) or iana-ipv6-special-registry_
(for IPv6) with the following exceptions:

Returns:
A boolean, True if the address is reserved per
iana-ipv6-special-registry, or is ipv4_mapped and is
reserved in the iana-ipv4-special-registry.
* ``is_private`` is ``False`` for ``100.64.0.0/10``
* For IPv4-mapped IPv6-addresses the ``is_private`` value is determined by the
semantics of the underlying IPv4 addresses and the following condition holds
(see :attr:`IPv6Address.ipv4_mapped`)::

address.is_private == address.ipv4_mapped.is_private

``is_private`` has value opposite to :attr:`is_global`, except for the ``100.64.0.0/10``
IPv4 range where they are both ``False``.
"""
ipv4_mapped = self.ipv4_mapped
if ipv4_mapped is not None:
Expand All @@ -2064,12 +2090,18 @@ def is_private(self):

@property
def is_global(self):
"""Test if this address is allocated for public networks.
"""``True`` if the address is defined as globally reachable by
iana-ipv4-special-registry_ (for IPv4) or iana-ipv6-special-registry_
(for IPv6) with the following exception:

Returns:
A boolean, true if the address is not reserved per
iana-ipv6-special-registry.
For IPv4-mapped IPv6-addresses the ``is_private`` value is determined by the
semantics of the underlying IPv4 addresses and the following condition holds
(see :attr:`IPv6Address.ipv4_mapped`)::

address.is_global == address.ipv4_mapped.is_global

``is_global`` has value opposite to :attr:`is_private`, except for the ``100.64.0.0/10``
IPv4 range where they are both ``False``.
"""
return not self.is_private

Expand Down