classification
Title: ipaddress documentation errors
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.8, Python 3.7, Python 3.6
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: berker.peksag, cheryl.sabella, docs@python, jongfoster, miss-islington, ncoghlan, pmoody, r.david.murray, xiang.zhang
Priority: normal Keywords: patch

Created on 2013-08-21 21:00 by jongfoster, last changed 2018-03-21 01:57 by xiang.zhang. This issue is now closed.

Files
File name Uploaded Description Edit
ipaddress_docs_v1.patch jongfoster, 2013-08-21 21:00 review
issue18802_v2.diff berker.peksag, 2016-06-10 10:29 review
Pull Requests
URL Status Linked Edit
PR 6083 merged cheryl.sabella, 2018-03-11 22:55
PR 6166 merged miss-islington, 2018-03-21 00:10
PR 6167 merged miss-islington, 2018-03-21 00:11
Messages (11)
msg195822 - (view) Author: Jon Foster (jongfoster) * Date: 2013-08-21 21:00
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
msg195845 - (view) Author: Jon Foster (jongfoster) * Date: 2013-08-22 00:36
(If this is accepted, please consider it for backport to 3.3 too.  It is just a documentation improvement).
msg195847 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2013-08-22 00:39
Documentation fixes are always backported.
msg268095 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2016-06-10 06:29
> * 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.
msg268112 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2016-06-10 10:29
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.
msg312144 - (view) Author: Cheryl Sabella (cheryl.sabella) * (Python committer) Date: 2018-02-13 23:38
Jon/Berker,

Are you interested in making a Github pull request for this?  Thanks!
msg313418 - (view) Author: Xiang Zhang (xiang.zhang) * (Python committer) Date: 2018-03-08 02:56
Ahh, I also find some errors here in ipaddress doc and opened https://github.com/python/cpython/pull/6021 to fix them.
msg313626 - (view) Author: Cheryl Sabella (cheryl.sabella) * (Python committer) Date: 2018-03-11 22:56
I've made a PR for Berker's patch.
msg314174 - (view) Author: Xiang Zhang (xiang.zhang) * (Python committer) Date: 2018-03-21 00:09
New changeset 5609b78392d59c7362ef8aa5c4a4529325f01f27 by Xiang Zhang (Cheryl Sabella) in branch 'master':
 bpo-18802: Add more details to ipaddress documentation (GH-6083)
https://github.com/python/cpython/commit/5609b78392d59c7362ef8aa5c4a4529325f01f27
msg314176 - (view) Author: miss-islington (miss-islington) Date: 2018-03-21 00:30
New changeset a323eee4c481c88f2b4030bbb224d9bc6bc14c9c by Miss Islington (bot) in branch '3.7':
bpo-18802: Add more details to ipaddress documentation (GH-6083)
https://github.com/python/cpython/commit/a323eee4c481c88f2b4030bbb224d9bc6bc14c9c
msg314177 - (view) Author: miss-islington (miss-islington) Date: 2018-03-21 00:59
New changeset 481cbe8d6202658a7908d97f19f7e9e6061e3df3 by Miss Islington (bot) in branch '3.6':
bpo-18802: Add more details to ipaddress documentation (GH-6083)
https://github.com/python/cpython/commit/481cbe8d6202658a7908d97f19f7e9e6061e3df3
History
Date User Action Args
2018-03-21 01:57:16xiang.zhangsetstatus: open -> closed
resolution: fixed
stage: patch review -> resolved
2018-03-21 00:59:03miss-islingtonsetmessages: + msg314177
2018-03-21 00:30:45miss-islingtonsetnosy: + miss-islington
messages: + msg314176
2018-03-21 00:11:26miss-islingtonsetpull_requests: + pull_request5922
2018-03-21 00:10:42miss-islingtonsetpull_requests: + pull_request5921
2018-03-21 00:09:18xiang.zhangsetmessages: + msg314174
2018-03-11 22:56:14cheryl.sabellasetmessages: + msg313626
2018-03-11 22:55:17cheryl.sabellasetpull_requests: + pull_request5844
2018-03-08 02:56:24xiang.zhangsetversions: + Python 3.7, Python 3.8, - Python 3.5
nosy: + docs@python, xiang.zhang

messages: + msg313418

assignee: docs@python
components: + Documentation, - Library (Lib)
2018-03-08 02:54:21xiang.zhanglinkissue22822 superseder
2018-02-13 23:38:26cheryl.sabellasetnosy: + cheryl.sabella
messages: + msg312144
2016-06-10 10:29:10berker.peksagsetfiles: + issue18802_v2.diff

messages: + msg268112
2016-06-10 06:29:44berker.peksagsetnosy: + berker.peksag

messages: + msg268095
versions: + Python 3.5, Python 3.6, - Python 3.3, Python 3.4
2013-11-10 01:42:46ezio.melottisetstage: patch review
2013-08-22 00:39:53r.david.murraysetnosy: + r.david.murray
messages: + msg195847
2013-08-22 00:36:50jongfostersettype: enhancement
messages: + msg195845
versions: + Python 3.3
2013-08-21 21:13:17r.david.murraysetnosy: + ncoghlan, pmoody
2013-08-21 21:00:57jongfostercreate