Documentation for stat.S_IFMT inconsistent

[lechten]

BPO	16936
Files	stat.rst.diff: Diff for stat.rst

^{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 2013-01-11.19:26:01.125>
created_at = <Date 2013-01-11.15:31:22.455>
labels = ['type-bug', 'docs']
title = 'Documentation for stat.S_IFMT inconsistent'
updated_at = <Date 2013-01-11.19:26:01.123>
user = 'https://bugs.python.org/lechten'

bugs.python.org fields:

activity = <Date 2013-01-11.19:26:01.123>
actor = 'python-dev'
assignee = 'docs@python'
closed = True
closed_date = <Date 2013-01-11.19:26:01.125>
closer = 'python-dev'
components = ['Documentation']
creation = <Date 2013-01-11.15:31:22.455>
creator = 'lechten'
dependencies = []
files = ['28697']
hgrepos = []
issue_num = 16936
keywords = ['patch']
message_count = 2.0
messages = ['179687', '179722']
nosy_count = 3.0
nosy_names = ['docs@python', 'python-dev', 'lechten']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue16936'
versions = ['Python 3.3']

[lechten]

The documentation for the stat module is inconsistent
(Doc/library/stat.rst, at least for Python 2.7.2 and 3.3.0):
It talks about a function stat.S_IFMT() and a bit mask stat.S_IFMT.
Only the former does exist.

Besides, it states: "For complete details about the stat(), fstat()
and lstat() calls, consult the documentation for your system."
I suggest to add some pointers on what systems one might consult
what documentation: "(e.g., on GNU/Linux invoke 'man 2 stat')"
I don't know about other systems, though.

So, doing "man 2 stat", which refers to the POSIX standard and which
seems to have served as blueprint for stat's interface, I expected
to find the bit mask S_IFMT.
However, that does not exist. In contrast, in stat.py that bit mask
is hard-coded as 0o170000 in the definition of S_IFMT().

As long-term, backwards-incompatible fix, I suggest to export
S_IFMT = 0o170000
and to rename the function S_IFMT(). That way, stat would in fact
be aligned with the documentation for my system.

As short-term fix, I suggest to correct stat.rst.

Replace

Use of the functions above is more portable than use of the first
set of flags:

stat.S_IFMT
Bit mask for the file type bit fields.

with

Use of the functions above may be more portable than use of the
first set of flags.

Warning: Note that the stat module does not export a bit mask
S_IFMT. (As stated incorrectly in previous versions of the
documentation.)

Here, I replaced "is more portable" with "may be more portable" as
the constant 0o170000 is hard-coded into S_IFMT() in stat.py. Maybe
somebody could add a hint in what sense portability is improved?
Alternatively that sentence could be deleted.

A diff for stat.rst (Python 3.3.0) is attached.

[python-dev]

New changeset 0d7a8a4d6f30 by Georg Brandl in branch '2.7':
Closes bpo-16936: fix duplicate/ambiguous description of stat.S_IFMT in the docs.
http://hg.python.org/cpython/rev/0d7a8a4d6f30

New changeset 3555391a9909 by Georg Brandl in branch '3.3':
Closes bpo-16936: fix duplicate/ambiguous description of stat.S_IFMT in the docs.
http://hg.python.org/cpython/rev/3555391a9909