classification
Title: clarifying Availability: Unix
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.8, Python 3.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: berker.peksag, cheryl.sabella, docs@python, eric.araujo, ezio.melotti, fdrake, georg.brandl, pitrou, python-dev, r.david.murray, sandro.tosi, vstinner
Priority: normal Keywords: patch

Created on 2011-02-17 19:03 by sandro.tosi, last changed 2018-10-15 23:02 by cheryl.sabella. This issue is now closed.

Files
File name Uploaded Description Edit
availability-directive.patch georg.brandl, 2013-10-12 18:31 review
Pull Requests
URL Status Linked Edit
PR 9692 merged cheryl.sabella, 2018-10-04 00:42
PR 9830 merged cheryl.sabella, 2018-10-12 22:56
Messages (19)
msg128746 - (view) Author: Sandro Tosi (sandro.tosi) * (Python committer) Date: 2011-02-17 19:03
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? :)
msg128750 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2011-02-17 20:05
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.
msg128751 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2011-02-17 20:09
> 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?
msg128752 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2011-02-17 20:19
Good point :(
msg128833 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2011-02-19 08:40
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...
msg128854 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2011-02-19 15:59
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.
msg128864 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2011-02-19 17:27
That's a good point, indeed.
msg139140 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2011-06-26 03:42
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.
msg141970 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-08-12 16:25
If no-one else has started on this, I’m interested in making a patch to introduce an availability directive.
msg199610 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2013-10-12 18:31
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!
msg199623 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2013-10-12 21:24
I can't comment on the Sphinx extension code but this is a good idea.
msg263744 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2016-04-19 14:53
I like the idea of a single place where the Availability is described, and adding a link to this place.  availability-directive.patch LGTM.
msg327017 - (view) Author: Cheryl Sabella (cheryl.sabella) * (Python committer) Date: 2018-10-03 23:47
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!
msg327020 - (view) Author: Fred Drake (fdrake) (Python committer) Date: 2018-10-04 00:01
A PR for this would be good, and would certainly accelerate getting this accomplished.  Thanks, Cheryl!
msg327025 - (view) Author: Cheryl Sabella (cheryl.sabella) * (Python committer) Date: 2018-10-04 00:42
Thanks, Fred.  I've submitted the PR.
msg327591 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2018-10-12 14:55
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/2d6097d027e0dd3debbabc702aa9c98d94ba32a3
msg327784 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2018-10-15 20:52
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/b248a8c9a5e7cf6b8e84a3efda493fccfc511316
msg327787 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2018-10-15 21:14
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
msg327801 - (view) Author: Cheryl Sabella (cheryl.sabella) * (Python committer) Date: 2018-10-15 23:02
And thank you, Victor, for reviewing and merging!  :-)
History
Date User Action Args
2018-10-15 23:02:03cheryl.sabellasetmessages: + msg327801
2018-10-15 21:14:27vstinnersetstatus: open -> closed
versions: + Python 3.7
messages: + msg327787

resolution: fixed
stage: patch review -> resolved
2018-10-15 20:52:38vstinnersetmessages: + msg327784
2018-10-12 22:56:16cheryl.sabellasetpull_requests: + pull_request9204
2018-10-12 14:55:25vstinnersetmessages: + msg327591
2018-10-04 00:42:56cheryl.sabellasetversions: + Python 3.8, - Python 3.5, Python 3.6
2018-10-04 00:42:46cheryl.sabellasetmessages: + msg327025
2018-10-04 00:42:02cheryl.sabellasetpull_requests: + pull_request9079
2018-10-04 00:01:08fdrakesetnosy: + fdrake
messages: + msg327020
2018-10-03 23:47:24cheryl.sabellasetnosy: + cheryl.sabella
messages: + msg327017
2016-04-19 14:53:32vstinnersetnosy: + vstinner
messages: + msg263744
2016-04-19 13:13:16berker.peksagsetnosy: + berker.peksag
stage: needs patch -> patch review
type: enhancement

versions: + Python 3.5, Python 3.6
2013-10-12 21:24:42pitrousetmessages: + msg199623
2013-10-12 18:31:50georg.brandlsetfiles: + availability-directive.patch
keywords: + patch
messages: + msg199610
2011-08-12 16:25:45eric.araujosetnosy: + eric.araujo
messages: + msg141970

resolution: works for me -> (no value)
stage: needs patch
2011-06-26 03:42:30r.david.murraysetmessages: + msg139140
2011-06-25 15:15:10sandro.tosisetmessages: - msg130754
2011-03-13 18:16:11python-devsetnosy: + python-dev
messages: + msg130754
2011-02-19 17:39:33ezio.melottisetnosy: + ezio.melotti
2011-02-19 17:27:01georg.brandlsetnosy: georg.brandl, pitrou, r.david.murray, sandro.tosi, docs@python
messages: + msg128864
2011-02-19 15:59:20r.david.murraysetstatus: pending -> open
nosy: georg.brandl, pitrou, r.david.murray, sandro.tosi, docs@python
messages: + msg128854
2011-02-19 08:40:27georg.brandlsetstatus: open -> pending

nosy: + georg.brandl
messages: + msg128833

resolution: works for me
2011-02-17 20:19:57r.david.murraysetnosy: pitrou, r.david.murray, sandro.tosi, docs@python
messages: + msg128752
2011-02-17 20:09:50pitrousetnosy: + pitrou
messages: + msg128751
2011-02-17 20:05:08r.david.murraysetnosy: + r.david.murray
messages: + msg128750
2011-02-17 19:03:18sandro.tosicreate