[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