New submission from Jens Lechtenboerger: 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. ---------- assignee: docs@python components: Documentation files: stat.rst.diff keywords: patch messages: 179687 nosy: docs@python, lechten priority: normal severity: normal status: open title: Documentation for stat.S_IFMT inconsistent type: behavior versions: Python 3.3 Added file: http://bugs.python.org/file28697/stat.rst.diff _______________________________________ Python tracker <rep...@bugs.python.org> <http://bugs.python.org/issue16936> _______________________________________ _______________________________________________ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com