[issue11233] clarifying Availability: Unix
New submission from Sandro Tosi <sandro.tosi@gmail.com>: Hi, following up http://mail.python.org/pipermail/docs/2011-February/003083.html we have a chat on #python-dev on the topic, the situation is - all started with os.lchmod() and as.lchflags() methods not available on a Debian system - that's because POSIX does not require those functions and then Linux systems don't provide them - so we then thought about clarifying, only for those 2 methods, that they might not be available with a format like "availability: some unix systems" - then we noticed that on top of os doc there's a notice "An “Availability: Unix” note means that this function is commonly found on Unix systems. It does not make any claims about its existence on a specific operating system." and so we thought about linking every 'Availability: Unix' to that note - or transform that not in a footnote and link every 'Availability: Unix' for functions that might not be present to that footnote. It's enough for the conversation dump: ideas/suggestions? :) ---------- assignee: docs@python components: Documentation messages: 128746 nosy: docs@python, sandro.tosi priority: normal severity: normal status: open title: clarifying Availability: Unix _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11233> _______________________________________
R. David Murray <rdmurray@bitdance.com> added the comment: I like the footnote idea. I wonder if it would also be worth marking which functions are Posix (Availability: posix) and therefore likely to be available on all unix systems. ---------- nosy: +r.david.murray _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11233> _______________________________________
Antoine Pitrou <pitrou@free.fr> added the comment:
I like the footnote idea.
Me too.
I wonder if it would also be worth marking which functions are Posix (Availability: posix) and therefore likely to be available on all unix systems.
POSIX has optional APIs, hasn't it? ---------- nosy: +pitrou _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11233> _______________________________________
R. David Murray <rdmurray@bitdance.com> added the comment: Good point :( ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11233> _______________________________________
Georg Brandl <georg@python.org> added the comment: The "Notes on availability" bullet list at the top of docs.python.org/library/os should already say everything that there is to say here... ---------- nosy: +georg.brandl resolution: -> works for me status: open -> pending _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11233> _______________________________________
R. David Murray <rdmurray@bitdance.com> added the comment: Yes, but when you jump directly to one of the functions, you don't see that bullet list. Whereas if it were a footnote on the 'avaiability: unix" statement, the natural thing would be to follow the footnote and thus learn the limitations on that statement. Thus I think the footnote would be better than the bullet list at the top. ---------- status: pending -> open _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11233> _______________________________________
Georg Brandl <georg@python.org> added the comment: That's a good point, indeed. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11233> _______________________________________
Changes by Ezio Melotti <ezio.melotti@gmail.com>: ---------- nosy: +ezio.melotti _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11233> _______________________________________
Roundup Robot <devnull@devnull> added the comment: New changeset f197dac00f43 by Antoine Pitrou in branch 'default': Merge commit for #11233 http://hg.python.org/cpython/rev/f197dac00f43 ---------- nosy: +python-dev _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11233> _______________________________________
Changes by Sandro Tosi <sandro.tosi@gmail.com>: ---------- Removed message: http://bugs.python.org/msg130754 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11233> _______________________________________
R. David Murray <rdmurray@bitdance.com> added the comment: In another issue Georg came up with the idea of creating an availability directive that would auto link to the appropriate text. This would then apply to all our different availability types. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11233> _______________________________________
Éric Araujo <merwok@netwok.org> added the comment: If no-one else has started on this, I’m interested in making a patch to introduce an availability directive. ---------- nosy: +eric.araujo resolution: works for me -> stage: -> needs patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11233> _______________________________________
Georg Brandl added the comment: A draft is attached. The directive currently just always links to the "availability" notes, which I have moved to the main "Operating system services" document. Please review! ---------- keywords: +patch Added file: http://bugs.python.org/file32065/availability-directive.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11233> _______________________________________
Antoine Pitrou added the comment: I can't comment on the Sphinx extension code but this is a good idea. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11233> _______________________________________
Changes by Berker Peksag <berker.peksag@gmail.com>: ---------- nosy: +berker.peksag stage: needs patch -> patch review type: -> enhancement versions: +Python 3.5, Python 3.6 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11233> _______________________________________
STINNER Victor added the comment: I like the idea of a single place where the Availability is described, and adding a link to this place. availability-directive.patch LGTM. ---------- nosy: +haypo _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11233> _______________________________________
Cheryl Sabella <cheryl.sabella@gmail.com> added the comment: Hello, It doesn't appear that this patch was ever merged. If there's still interest, would it be OK for me to convert it to a PR? Thanks! ---------- nosy: +cheryl.sabella _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue11233> _______________________________________
Fred L. Drake, Jr. <fdrake@gmail.com> added the comment: A PR for this would be good, and would certainly accelerate getting this accomplished. Thanks, Cheryl! ---------- nosy: +fdrake _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue11233> _______________________________________
Change by Cheryl Sabella <cheryl.sabella@gmail.com>: ---------- pull_requests: +9079 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue11233> _______________________________________
Cheryl Sabella <cheryl.sabella@gmail.com> added the comment: Thanks, Fred. I've submitted the PR. ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue11233> _______________________________________
Change by Cheryl Sabella <cheryl.sabella@gmail.com>: ---------- versions: +Python 3.8 -Python 3.5, Python 3.6 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue11233> _______________________________________
STINNER Victor <vstinner@redhat.com> added the comment: New changeset 2d6097d027e0dd3debbabc702aa9c98d94ba32a3 by Victor Stinner (Cheryl Sabella) in branch 'master': bpo-11233: Create availability directive for documentation (GH-9692) https://github.com/python/cpython/commit/2d6097d027e0dd3debbabc702aa9c98d94b... ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue11233> _______________________________________
Change by Cheryl Sabella <cheryl.sabella@gmail.com>: ---------- pull_requests: +9204 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue11233> _______________________________________
STINNER Victor <vstinner@redhat.com> added the comment: New changeset b248a8c9a5e7cf6b8e84a3efda493fccfc511316 by Victor Stinner (Cheryl Sabella) in branch '3.7': [3.7] bpo-11233: Create availability directive for documentation (GH-9692) (GH-9830) https://github.com/python/cpython/commit/b248a8c9a5e7cf6b8e84a3efda493fccfc5... ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue11233> _______________________________________
STINNER Victor <vstinner@redhat.com> added the comment: Thank you Sandro Tosi for the bug report, thanks Georg Brandl for initial patch, and thanks Cheryl Sabella for the final changes in 3.7 and master! According to Yury Selivanov, it's not need to backport this change to 2.7 and 3.6, so I close the issue. https://github.com/python/cpython/pull/9692#issuecomment-429364037 ---------- resolution: -> fixed stage: patch review -> resolved status: open -> closed versions: +Python 3.7 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue11233> _______________________________________
Cheryl Sabella <cheryl.sabella@gmail.com> added the comment: And thank you, Victor, for reviewing and merging! :-) ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue11233> _______________________________________
participants (11)
-
Antoine Pitrou
-
Berker Peksag
-
Cheryl Sabella
-
Ezio Melotti
-
Fred L. Drake, Jr.
-
Georg Brandl
-
R. David Murray
-
Roundup Robot
-
Sandro Tosi
-
STINNER Victor
-
Éric Araujo