Skip to content
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.

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

Jump to bottom

ipaddress documentation errors #63002

Closed
jongfoster mannequin opened this issue Aug 21, 2013 · 11 comments
Closed

ipaddress documentation errors #63002

jongfoster mannequin opened this issue Aug 21, 2013 · 11 comments
Labels
3.7 (EOL) end of life 3.8 only security fixes docs Documentation in the Doc dir type-feature A feature request or enhancement

Comments

@jongfoster
Copy link
Mannequin

jongfoster mannequin commented Aug 21, 2013

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
    Copy link
    Mannequin Author

    jongfoster mannequin commented Aug 21, 2013

    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 jongfoster mannequin added the stdlib Python modules in the Lib dir label Aug 21, 2013
    @jongfoster
    Copy link
    Mannequin Author

    jongfoster mannequin commented Aug 22, 2013

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

    @jongfoster jongfoster mannequin added the type-feature A feature request or enhancement label Aug 22, 2013
    @bitdancer
    Copy link
    Member

    Documentation fixes are always backported.

    @berkerpeksag
    Copy link
    Member

    • 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
    Copy link
    Member

    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
    Copy link
    Contributor

    Jon/Berker,

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

    @zhangyangyu
    Copy link
    Member

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

    @zhangyangyu zhangyangyu added docs Documentation in the Doc dir 3.7 (EOL) end of life 3.8 only security fixes and removed stdlib Python modules in the Lib dir labels Mar 8, 2018
    @csabella
    Copy link
    Contributor

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

    @zhangyangyu
    Copy link
    Member

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

    @miss-islington
    Copy link
    Contributor

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

    @miss-islington
    Copy link
    Contributor

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

    @ezio-melotti ezio-melotti transferred this issue from another repository Apr 10, 2022
    Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
    Assignees
    No one assigned
    Labels
    3.7 (EOL) end of life 3.8 only security fixes docs Documentation in the Doc dir type-feature A feature request or enhancement
    Projects
    None yet
    Milestone
    No milestone
    Development

    No branches or pull requests
    5 participants
    @berkerpeksag @bitdancer @zhangyangyu @csabella @miss-islington