clarifying Availability: Unix #55442

sandrotosi · 2011-02-17T19:03:18Z

BPO	11233
Nosy	@freddrake, @birkenfeld, @pitrou, @vstinner, @ezio-melotti, @merwok, @bitdancer, @sandrotosi, @berkerpeksag, @csabella
PRs	bpo-11233: Create availability directive for documentation #9692 [3.7] bpo-11233: Create availability directive for documentation (GH-… #9830
Files	availability-directive.patch

^{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-10-15.21:14:27.927>
created_at = <Date 2011-02-17.19:03:18.252>
labels = ['3.8', 'type-feature', '3.7', 'docs']
title = 'clarifying Availability: Unix'
updated_at = <Date 2018-10-15.23:02:03.269>
user = 'https://github.com/sandrotosi'

bugs.python.org fields:

activity = <Date 2018-10-15.23:02:03.269>
actor = 'cheryl.sabella'
assignee = 'docs@python'
closed = True
closed_date = <Date 2018-10-15.21:14:27.927>
closer = 'vstinner'
components = ['Documentation']
creation = <Date 2011-02-17.19:03:18.252>
creator = 'sandro.tosi'
dependencies = []
files = ['32065']
hgrepos = []
issue_num = 11233
keywords = ['patch']
message_count = 19.0
messages = ['128746', '128750', '128751', '128752', '128833', '128854', '128864', '139140', '141970', '199610', '199623', '263744', '327017', '327020', '327025', '327591', '327784', '327787', '327801']
nosy_count = 12.0
nosy_names = ['fdrake', 'georg.brandl', 'pitrou', 'vstinner', 'ezio.melotti', 'eric.araujo', 'r.david.murray', 'sandro.tosi', 'docs@python', 'python-dev', 'berker.peksag', 'cheryl.sabella']
pr_nums = ['9692', '9830']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue11233'
versions = ['Python 3.7', 'Python 3.8']

sandrotosi · 2011-02-17T19:03:18Z

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? :)

bitdancer · 2011-02-17T20:05:08Z

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.

pitrou · 2011-02-17T20:09:50Z

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?

bitdancer · 2011-02-17T20:19:57Z

Good point :(

birkenfeld · 2011-02-19T08:40:27Z

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...

bitdancer · 2011-02-19T15:59:20Z

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.

birkenfeld · 2011-02-19T17:27:02Z

That's a good point, indeed.

bitdancer · 2011-06-26T03:42:30Z

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.

merwok · 2011-08-12T16:25:45Z

If no-one else has started on this, I’m interested in making a patch to introduce an availability directive.

birkenfeld · 2013-10-12T18:31:50Z

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!

pitrou · 2013-10-12T21:24:42Z

I can't comment on the Sphinx extension code but this is a good idea.

vstinner · 2016-04-19T14:53:33Z

I like the idea of a single place where the Availability is described, and adding a link to this place. availability-directive.patch LGTM.

csabella · 2018-10-03T23:47:24Z

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!

freddrake · 2018-10-04T00:01:08Z

A PR for this would be good, and would certainly accelerate getting this accomplished. Thanks, Cheryl!

csabella · 2018-10-04T00:42:46Z

Thanks, Fred. I've submitted the PR.

vstinner · 2018-10-12T14:55:25Z

New changeset 2d6097d by Victor Stinner (Cheryl Sabella) in branch 'master':
bpo-11233: Create availability directive for documentation (GH-9692)
2d6097d

vstinner · 2018-10-15T20:52:39Z

New changeset b248a8c by Victor Stinner (Cheryl Sabella) in branch '3.7':
[3.7] bpo-11233: Create availability directive for documentation (GH-9692) (GH-9830)
b248a8c

vstinner · 2018-10-15T21:14:28Z

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.
#9692 (comment)

csabella · 2018-10-15T23:02:03Z

And thank you, Victor, for reviewing and merging! :-)

calestyo · 2023-08-14T23:45:47Z

Just wondered... was that really ever fixed? Current documentation still seems to contain no indication that e.g. lchmod is not available on linux.

merwok · 2023-08-15T00:36:44Z

Not sure what you’re asking. We can see in the timeline on this page that a change was merged, which makes docs such as https://docs.python.org/3/library/os.html#os.lchmod contain a link to https://docs.python.org/3/library/intro.html#availability that clarifies what «availability» means – the goal of this ticket!

calestyo · 2023-08-15T02:01:12Z

Well, yes... but that's a pretty abstract information, isn't it? It's even a bit unusual, the first point says "Unix doesn't claim that a function exists on a specific OS"... while the second point says "Unix means it is available on MacOS, because that's a Unix".

Anyway... many functions do seem to have specific notes about Linux availability (e.g. when a minimum kernel version is required).

Wouldn't it make sense to notice if a function is specifically not available on Linux?

merwok · 2023-08-15T02:21:57Z

How could that be said? Doesn’t each feature depend on specifc kernel version and build options?

Edit: I guess there are many that are introduced by freebsd or aix or macos and don’t exist at all on linux. Do you have a list of such functions? If so, please open a new ticket so that this can be corrected!

calestyo · 2023-08-15T02:28:54Z

I'd have naively guessed that lchmod is simply generally not available in Linux... probably because Linux (and IIRC most other Unixes) ignores any file permission bits on symlinks (thus lchmod doesn't really make sense for it).

It's also not documented in the "Linux manpages"... so I'd say it's a general thing.

calestyo · 2023-08-15T02:32:09Z

Just found https://unix.stackexchange.com/questions/224979/why-do-linux-posix-have-lchown-but-not-lchmod ... so seems to be as I've suspected before.

calestyo · 2023-08-15T02:50:59Z

Opened a new issue #107959 and filed an MR.

sandrotosi assigned docspython Feb 17, 2011

sandrotosi added the docs Documentation in the Doc dir label Feb 17, 2011

berkerpeksag added the type-feature A feature request or enhancement label Apr 19, 2016

csabella added the 3.8 only security fixes label Oct 4, 2018

vstinner added the 3.7 (EOL) end of life label Oct 15, 2018

vstinner closed this as completed Oct 15, 2018

ezio-melotti transferred this issue from another repository Apr 10, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

clarifying Availability: Unix #55442

clarifying Availability: Unix #55442

sandrotosi commented Feb 17, 2011

sandrotosi commented Feb 17, 2011

bitdancer commented Feb 17, 2011

pitrou commented Feb 17, 2011

bitdancer commented Feb 17, 2011

birkenfeld commented Feb 19, 2011

bitdancer commented Feb 19, 2011

birkenfeld commented Feb 19, 2011

bitdancer commented Jun 26, 2011

merwok commented Aug 12, 2011

birkenfeld commented Oct 12, 2013

pitrou commented Oct 12, 2013

vstinner commented Apr 19, 2016

csabella commented Oct 3, 2018

freddrake commented Oct 4, 2018

csabella commented Oct 4, 2018

vstinner commented Oct 12, 2018

vstinner commented Oct 15, 2018

vstinner commented Oct 15, 2018

csabella commented Oct 15, 2018

calestyo commented Aug 14, 2023

merwok commented Aug 15, 2023

calestyo commented Aug 15, 2023

merwok commented Aug 15, 2023 •

edited

calestyo commented Aug 15, 2023

calestyo commented Aug 15, 2023

calestyo commented Aug 15, 2023

clarifying Availability: Unix #55442

clarifying Availability: Unix #55442

Comments

sandrotosi commented Feb 17, 2011

sandrotosi commented Feb 17, 2011

bitdancer commented Feb 17, 2011

pitrou commented Feb 17, 2011

bitdancer commented Feb 17, 2011

birkenfeld commented Feb 19, 2011

bitdancer commented Feb 19, 2011

birkenfeld commented Feb 19, 2011

bitdancer commented Jun 26, 2011

merwok commented Aug 12, 2011

birkenfeld commented Oct 12, 2013

pitrou commented Oct 12, 2013

vstinner commented Apr 19, 2016

csabella commented Oct 3, 2018

freddrake commented Oct 4, 2018

csabella commented Oct 4, 2018

vstinner commented Oct 12, 2018

vstinner commented Oct 15, 2018

vstinner commented Oct 15, 2018

csabella commented Oct 15, 2018

calestyo commented Aug 14, 2023

merwok commented Aug 15, 2023

calestyo commented Aug 15, 2023

merwok commented Aug 15, 2023 • edited

calestyo commented Aug 15, 2023

calestyo commented Aug 15, 2023

calestyo commented Aug 15, 2023

merwok commented Aug 15, 2023 •

edited