Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Documentation for stat.S_IFMT inconsistent #61140

Closed
lechten mannequin opened this issue Jan 11, 2013 · 2 comments
Closed

Documentation for stat.S_IFMT inconsistent #61140

lechten mannequin opened this issue Jan 11, 2013 · 2 comments
Labels
docs Documentation in the Doc dir type-bug An unexpected behavior, bug, or error

Comments

@lechten
Copy link
Mannequin

lechten mannequin commented Jan 11, 2013

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
    Copy link
    Mannequin Author

    lechten mannequin commented Jan 11, 2013

    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.

    @lechten lechten mannequin assigned docspython Jan 11, 2013
    @lechten lechten mannequin added docs Documentation in the Doc dir type-bug An unexpected behavior, bug, or error labels Jan 11, 2013
    @python-dev
    Copy link
    Mannequin

    python-dev mannequin commented Jan 11, 2013

    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

    @python-dev python-dev mannequin closed this as completed Jan 11, 2013
    @ezio-melotti ezio-melotti transferred this issue from another repository Apr 10, 2022
    Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
    Assignees
    No one assigned
    Labels
    docs Documentation in the Doc dir type-bug An unexpected behavior, bug, or error
    Projects
    None yet
    Milestone
    No milestone
    Development

    No branches or pull requests
    0 participants