Description

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'

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']

Activity

1. krichter commented on Oct 11, 2015

   

   krichtermannequin

   on Oct 11, 2015

   MannequinAuthor

   More actions

   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
2. krichter

   assigned

   docspython

   on Oct 11, 2015
3. krichter

   added

   docsDocumentation in the Doc dirDocumentation in the Doc dir

   type-featureA feature request or enhancementA feature request or enhancement

   on Oct 11, 2015
4. bitdancer commented on Oct 11, 2015

   

   bitdancer

   on Oct 11, 2015

   Member

   More actions

   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 :).
5. birkenfeld commented on Oct 11, 2015

   

   birkenfeld

   on Oct 11, 2015

   Member

   More actions

   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.)
6. serhiy-storchaka

   added

   easy

   3.7 (EOL)end of lifeend of life

   3.8 (EOL)end of lifeend of life

   3.9 (EOL)end of lifeend of life

   3.10 (EOL)end of lifeend of life

   on May 31, 2020
7. amaajemyfren commented on Jun 4, 2020

   

   amaajemyfrenmannequin

   on Jun 4, 2020

   Mannequin

   More actions

   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
8. ezio-melotti

   transferred this issue fromon Apr 10, 2022
9. kumaraditya303

   added a commit that references this issue on Dec 21, 2022

   GH-69564: Clarify use of octal format of mode argument in help(os.chm…

   bbf4a66
10. kumaraditya303

    closed this as completedon Dec 21, 2022
11. iritkatriel

    added a commit that references this issue on Dec 28, 2022

    Merged main into regmachine branch (#50)

    fdc73cb

Issue actions