Visitar URL original
GH-65056: Improve the IP address' is_global/is_private documentation by jstasiak 路 Pull Request #113186 路 python/cpython 路 GitHub
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鈥檒l occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
encukou 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 1 commit
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
Next Next commit
GH-65056: Improve the IP address' is_global/is_private documentation 
It wasn't clear what the semantics of is_global/is_private are and, when
one gets to the bottom of it, it's not quite so simple (hence the
exceptions listed).

I opted to fully replace the docstrings with the content from the
documentation to save myself some work.
  • Loading branch information
@jstasiak
jstasiak committed Dec 15, 2023
commit 533b97f99bfa53467533af95dddbc8e6f08208e3
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 ``100.64.0.0/10``
Comment thread
jstasiak marked this conversation as resolved.
Outdated
* 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``.
Comment thread
jstasiak marked this conversation as resolved.
Outdated

.. 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 ``100.64.0.0/10``
IPv4 range where they are both ``False``.
Comment thread
jstasiak marked this conversation as resolved.
Outdated

.. 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 the ``100.64.0.0/10``
Comment thread
jstasiak marked this conversation as resolved.
Outdated
* 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 the ``100.64.0.0/10``
Comment thread
jstasiak marked this conversation as resolved.
Outdated
* 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