classification
Title: Documentation for stat.S_IFMT inconsistent
Type: behavior Stage: resolved
Components: Documentation Versions: Python 3.3
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, lechten, python-dev
Priority: normal Keywords: patch

Created on 2013-01-11 15:31 by lechten, last changed 2013-01-11 19:26 by python-dev. This issue is now closed.

Files
File name Uploaded Description Edit
stat.rst.diff lechten, 2013-01-11 15:31 Diff for stat.rst
Messages (2)
msg179687 - (view) Author: Jens Lechtenboerger (lechten) Date: 2013-01-11 15:31
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.
msg179722 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2013-01-11 19:26
New changeset 0d7a8a4d6f30 by Georg Brandl in branch '2.7':
Closes #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 #16936: fix duplicate/ambiguous description of stat.S_IFMT in the docs.
http://hg.python.org/cpython/rev/3555391a9909
History
Date User Action Args
2013-01-11 19:26:01python-devsetstatus: open -> closed

nosy: + python-dev
messages: + msg179722

resolution: fixed
stage: resolved
2013-01-11 15:31:22lechtencreate