ipaddress documentation errors

[jongfoster]

BPO	18802
Nosy	@ncoghlan, @bitdancer, @berkerpeksag, @zhangyangyu, @csabella, @miss-islington
PRs	bpo-18802: ipaddress documentation changes  #6083 [3.7] bpo-18802: Add more details to ipaddress documentation (GH-6083) #6166 [3.6] bpo-18802: Add more details to ipaddress documentation (GH-6083) #6167
Files	ipaddress_docs_v1.patch issue18802_v2.diff

^{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 = <Date 2018-03-21.01:57:16.232>
created_at = <Date 2013-08-21.21:00:57.835>
labels = ['3.8', 'type-feature', '3.7', 'docs']
title = 'ipaddress documentation errors'
updated_at = <Date 2018-03-21.01:57:16.231>
user = 'https://bugs.python.org/jongfoster'

bugs.python.org fields:

activity = <Date 2018-03-21.01:57:16.231>
actor = 'xiang.zhang'
assignee = 'docs@python'
closed = True
closed_date = <Date 2018-03-21.01:57:16.232>
closer = 'xiang.zhang'
components = ['Documentation']
creation = <Date 2013-08-21.21:00:57.835>
creator = 'jongfoster'
dependencies = []
files = ['31410', '43330']
hgrepos = []
issue_num = 18802
keywords = ['patch']
message_count = 11.0
messages = ['195822', '195845', '195847', '268095', '268112', '312144', '313418', '313626', '314174', '314176', '314177']
nosy_count = 9.0
nosy_names = ['ncoghlan', 'jongfoster', 'pmoody', 'r.david.murray', 'docs@python', 'berker.peksag', 'xiang.zhang', 'cheryl.sabella', 'miss-islington']
pr_nums = ['6083', '6166', '6167']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue18802'
versions = ['Python 3.6', 'Python 3.7', 'Python 3.8']

[jongfoster]

I recently looked at using the ipaddress module in a project, and noticed some discrepencies between the code and the documentation, and some things that weren't documented. A patch to fix these is attached.

• The IPv4Network.__init__ documentation wrongly claims that "/0.0.0.0"
  would be interpreted as a host mask i.e. "/32". It's actually
  interpreted as a net mask, i.e. "/0".

• The IPv[46]Network.netmask property is not documented

• The IPv[46]Network.hostmask property is wrongly called "host mask"
  (with a space!) in the docs

• The IPv[46]Network.hostmask property is wrongly documented as a
  string but it's actually an IPv[46]Address

• The IPv6Network.__init__ documentation wrongly claims that a netmask
  can be specified, but this is not supported by the code. The code
  only supports prefix lengths.

• The documentation should explain how network objects are ordered,
  since it's not obvious.

• The documentation should explain how interface objects are compared,
  both with other interface objects and with address objects, as it's
  not obvious.

• It's probably a good idea to document that you can't always pass a
  IPv4Interface object to a function that expects a IPv4Address.

• It would be nice to mention that address, network and interface objects
  are all hashable.

Kind regards,

Jon

[jongfoster]

(If this is accepted, please consider it for backport to 3.3 too. It is just a documentation improvement).

[bitdancer]

Documentation fixes are always backported.

[berkerpeksag]

• The IPv[46]Network.hostmask property is wrongly called "host mask"
  (with a space!) in the docs

This one has already been fixed in 4f8ad9a4193f.

[berkerpeksag]

Thank you for the great patch Jon! :)

I rebased Jon's patch to current default with additional changes like fixing typos and markup tweaks. I also removed the following item since it doesn't seem to be crucial:

* It's probably a good idea to document that you can't always pass a
  IPv4Interface object to a function that expects a IPv4Address.

[csabella]

Jon/Berker,

Are you interested in making a Github pull request for this? Thanks!

[zhangyangyu]

Ahh, I also find some errors here in ipaddress doc and opened #6021 to fix them.

[csabella]

I've made a PR for Berker's patch.

[zhangyangyu]

New changeset 5609b78 by Xiang Zhang (Cheryl Sabella) in branch 'master':
bpo-18802: Add more details to ipaddress documentation (GH-6083)
5609b78

[miss-islington]

New changeset a323eee by Miss Islington (bot) in branch '3.7':
bpo-18802: Add more details to ipaddress documentation (GH-6083)
a323eee

[miss-islington]

New changeset 481cbe8 by Miss Islington (bot) in branch '3.6':
bpo-18802: Add more details to ipaddress documentation (GH-6083)
481cbe8