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

Mention octal format of mode argument of os.chmod #69564

Closed
krichter mannequin opened this issue Oct 11, 2015 · 4 comments
Closed

Mention octal format of mode argument of os.chmod #69564

krichter mannequin opened this issue Oct 11, 2015 · 4 comments
Labels
3.7 3.8 3.9 3.10 docs Documentation in the Doc dir easy type-feature A feature request or enhancement

Comments

@krichter
Copy link
Mannequin

krichter mannequin commented Oct 11, 2015

BPO 25377
Nosy @birkenfeld, @bitdancer, @amaajemyfren
PRs
  • bpo-25377: Clarify use of octal format of mode argument in help(os.chmod) #20621
    		•

    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 = None
created_at = <Date 2015-10-11.15:36:26.873>
labels = ['easy', '3.7', '3.8', '3.9', '3.10', 'type-feature', 'docs']
title = 'Mention octal format of mode argument of os.chmod'
updated_at = <Date 2020-06-04.16:08:41.908>
user = 'https://bugs.python.org/krichter'

    bugs.python.org fields:

    activity = <Date 2020-06-04.16:08:41.908>
actor = 'amaajemyfren'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2015-10-11.15:36:26.873>
creator = 'krichter'
dependencies = []
files = []
hgrepos = []
issue_num = 25377
keywords = ['patch', 'easy']
message_count = 4.0
messages = ['252817', '252818', '252819', '370715']
nosy_count = 5.0
nosy_names = ['georg.brandl', 'r.david.murray', 'docs@python', 'krichter', 'amaajemyfren']
pr_nums = ['20621']
priority = 'normal'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue25377'
versions = ['Python 3.6', 'Python 3.7', 'Python 3.8', 'Python 3.9', 'Python 3.10']
    @krichter
    Copy link
    Mannequin Author

    krichter mannequin commented Oct 11, 2015

    help(os.chmod) doesn't explain that it expects an octal number for its mode argument. This is very confusing for beginners and people who are not involved with filesystems and permissions every day. It doesn't need to be explained, just mentioned, maybe with a link to an extended explanation.

    Example for confusion: http://stackoverflow.com/questions/15607903/python-module-os-chmodfile-664-does-not-change-the-permission-to-rw-rw-r-bu

    @krichter krichter mannequin assigned docspython Oct 11, 2015
    @krichter krichter mannequin added docs Documentation in the Doc dir type-feature A feature request or enhancement labels Oct 11, 2015
    @bitdancer
    Copy link
    Member

    bitdancer commented Oct 11, 2015

    The main docs do not mention octal, but instead point to the constants in the stat module. The help text currently says "Operating-system mode bitfield", which is in fact accurate. A decimal number is *not* a bitfield (although it can be interpreted as one, giving the unexpected results).

    However, the help doc could be enhanced to say "Operating-system mode bitfield, see stat module for symbolic constants.".

    Basically, the fact that octal works is an historical accident due to it working that way on unix, but ideally should not be relied upon by python code (though of course it will be :).

    @birkenfeld
    Copy link
    Member

    birkenfeld commented Oct 11, 2015

    A short sentence like

    Be careful when using number literals for mode. The conventional UNIX notation for numeric modes uses an octal base, which needs to be indicated with a 0o prefix in Python.

    should be a good addition here. (I wonder why it isn't there, I seem to recall an earlier issue about this.)

    @amaajemyfren
    Copy link
    Mannequin

    amaajemyfren mannequin commented Jun 4, 2020

    I think I was finally able to do a PR for this on 3.10. Requesting a triager to please check because it does not appear as a Documentation change on Github.

    Thanks

    @ezio-melotti ezio-melotti transferred this issue from another repository Apr 10, 2022
    @bedevere-bot bedevere-bot mentioned this issue Dec 21, 2022
    Merged
    kumaraditya303 added a commit that referenced this issue Dec 21, 2022
    @amaajemyfren @kumaraditya303
    GH-69564: Clarify use of octal format of mode argument in help(os.chm…
    bbf4a66 
    …od) (#20621)

Co-authored-by: Kumar Aditya <59607654+kumaraditya303@users.noreply.github.com>
    Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
    Assignees
    No one assigned
    Labels
    3.7 3.8 3.9 3.10 docs Documentation in the Doc dir easy type-feature A feature request or enhancement
    Projects
    None yet
    Milestone
    No milestone
    Development

    No branches or pull requests
    4 participants
    @birkenfeld @bitdancer @serhiy-storchaka @kumaraditya303