ipaddress "is_private" and "is_global" are insufficiently documented and is_global probably has a bug

[bitdancer]

BPO	20857
Nosy	@loewis, @ncoghlan, @bitdancer

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2014-03-06.16:20:35.832>
labels = ['type-bug']
title = 'ipaddress "is_private" and "is_global" are insufficiently documented and is_global probably has a bug'
updated_at = <Date 2014-03-06.21:50:40.486>
user = 'https://github.com/bitdancer'

bugs.python.org fields:

activity = <Date 2014-03-06.21:50:40.486>
actor = 'loewis'
assignee = 'none'
closed = False
closed_date = None
closer = None
components = []
creation = <Date 2014-03-06.16:20:35.832>
creator = 'r.david.murray'
dependencies = []
files = []
hgrepos = []
issue_num = 20857
keywords = []
message_count = 3.0
messages = ['212812', '212813', '212843']
nosy_count = 4.0
nosy_names = ['loewis', 'ncoghlan', 'pmoody', 'r.david.murray']
pr_nums = []
priority = 'normal'
resolution = None
stage = None
status = 'open'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue20857'
versions = ['Python 3.4', 'Python 3.5']

Linked PRs

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

[bitdancer]

The 'is_private' and 'is_global' properties refer to the iana registries, but the terms 'private network' and 'public network' do no appear in the registry documentation. There is no way to know what these methods are going to return other than examining the source code.

In particular, without looking at the source code a best-guess interpretation of the documentation would lead one to expect that is_private would return true only for RFC1918 addresses, since that is the one place the term 'private' appears. Similarly, the naive interpretation of is_global would be that it would return False for all addresses listed in the ipv4 registry *except* 192.88.99.0/24, which is the only one whose global routing flag is True in the table.

I would submit that the fact that the latter is not true is a bug.

It is really not at all clear what 'is_private' means (see also bpo-17400, which introduced is_global), so I am completely unclear how to rewrite the documentation to fully specify it, other than to list out the address ranges that it considers private.

[bitdancer]

Oh, and just to make things more complicated, there are footnotes that some protocols allow global routing for protocol-allocated addresses that are otherwise not globally routable. It would be reasonable to for is_global to ignore this, but it should be documented that it does so.

[loewis]

I'm always in favour of using official terminology (and adjust if that changes over time). So in this case, I agree with David's analysis, and suggest the following specification:

• is_global returns False for all addresses where "Global" is "False" in the IPv4 or IPv6 Special-Purpose Address Registry
• a new method is_private_use is introduced, giving True only for the RFC1918 addresses
• a new method is_unique_local is introduced, giving True only for the RFC 4193 addresses.
• is_private is deprecated. Alternatively, it could be preserved and documented to being the union of is_privte_use and is_unique_local.

I don't think it it necessary to discuss footnote 1 in the IPv6 registry ("not global unless a specific allocations says otherwise"). The specific allocations that might override this come right below, so if we implement the table, we would cover all those more specific case.

I'm puzzled why Teredo is listed as "not global"; my understanding is that the Teredo prefixes even get announced in BGP, and are fully global.

[jstasiak]

I second @loewis' conclusions, the current semantics is pretty confusing. In the meantime we can document it better, I'll take a stab at it.

[jstasiak]

See the attached PR. The documentation preview: https://cpython-previews--113186.org.readthedocs.build/en/113186/library/ipaddress.html#ipaddress.IPv4Address.is_private

[encukou]

Docs are now updated; thank you!
The bug is tracked in #113171.