[issue20582] socket.getnameinfo() does not document flags
New submission from Roy Smith: http://docs.python.org/2/library/socket.html The description for getnameinfo() says, "... Depending on the settings of flags, the result can contain a fully-qualified domain name or numeric address representation in host.", but does not say what to pass for flags to get those behaviors. ---------- assignee: docs@python components: Documentation messages: 210838 nosy: docs@python, roysmith priority: normal severity: normal status: open title: socket.getnameinfo() does not document flags versions: Python 2.7 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue20582> _______________________________________
R. David Murray added the comment: Like the other socket functions, you have to look it up in the man page. A number of the other functions that take a flag argument mention this in their description, so a similar mention should be added to the getnameinfo entry. ---------- nosy: +r.david.murray versions: +Python 3.3, Python 3.4 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue20582> _______________________________________
Roy Smith added the comment: What might make sense is for all of those, document the function call as taking "native_flags" (or something like that), with a single note at the top of the page saying, "native_flags means look up the specific values in the man page" and link to that note each time it's used. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue20582> _______________________________________
R. David Murray added the comment: I thought about that, but different functions refer to different man pages, and it isn't always obvious from the function name which one. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue20582> _______________________________________
Change by Cheryl Sabella <cheryl.sabella@gmail.com>: ---------- keywords: +easy stage: -> needs patch type: -> enhancement versions: +Python 3.8 -Python 2.7, Python 3.3, Python 3.4 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue20582> _______________________________________
Danish Prakash <grafitykoncept@gmail.com> added the comment: I would like to work on this if nobody else has. ---------- nosy: +danishprakash _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue20582> _______________________________________
Change by Demian Brecht <demianbrecht@gmail.com>: ---------- nosy: +demian.brecht _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue20582> _______________________________________
Demian Brecht <demianbrecht@gmail.com> added the comment: What if the docs for socket functions that took system-level flag parameters had links to relevant online man pages? I don't think a single entry at the top of the page would be optimal. I know that I tend to skip the preamble and just go directly to the function I'm interested in. I know that it's not a perfect solution because there's a good chance of those links going stale. I'm also relatively sure that we wouldn't want to have an exhaustive list. However, I think in this instance that /something/ would be better than nothing. Even if the link is stale or the target OS isn't included, it would give the reader a place to start, which is currently lacking. ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue20582> _______________________________________
Change by Emmanuel Arias <emmanuelarias30@gmail.com>: ---------- keywords: +patch pull_requests: +12001 stage: needs patch -> patch review _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue20582> _______________________________________
Serhiy Storchaka <storchaka+cpython@gmail.com> added the comment: You can use the special role :manpage: for referring man pages. ---------- nosy: +serhiy.storchaka _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue20582> _______________________________________
miss-islington <mariatta.wijaya+miss-islington@gmail.com> added the comment: New changeset 3993ccb6820d4239ce3d9e1c5d31f13b86e0000b by Miss Islington (bot) (Emmanuel Arias) in branch 'master': bpo-20582: add link for manpage for flags on getnameinfo() (GH-11977) https://github.com/python/cpython/commit/3993ccb6820d4239ce3d9e1c5d31f13b86e... ---------- nosy: +miss-islington _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue20582> _______________________________________
Irit Katriel <iritkatriel@yahoo.com> added the comment: This seems complete, can it be closed? ---------- nosy: +iritkatriel _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue20582> _______________________________________
Change by Irit Katriel <iritkatriel@yahoo.com>: ---------- resolution: -> fixed stage: patch review -> resolved status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue20582> _______________________________________
participants (9)
-
Cheryl Sabella -
Danish Prakash
-
Demian Brecht
-
Emmanuel Arias
-
Irit Katriel
-
miss-islington
-
R. David Murray
-
Roy Smith
-
Serhiy Storchaka