This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

Title: Mention octal format of mode argument of os.chmod
Type: enhancement Stage: patch review
Components: Documentation Versions: Python 3.10, Python 3.9, Python 3.8, Python 3.7, Python 3.6
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: amaajemyfren, docs@python, georg.brandl, krichter, r.david.murray
Priority: normal Keywords: easy, patch

Created on 2015-10-11 15:36 by krichter, last changed 2022-04-11 14:58 by admin.

Pull Requests
URL Status Linked Edit
PR 20621 open amaajemyfren, 2020-06-03 20:25
Messages (4)
msg252817 - (view) Author: Karl Richter (krichter) Date: 2015-10-11 15:36
`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:
msg252818 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2015-10-11 15:46
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 :).
msg252819 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2015-10-11 16:34
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.)
msg370715 - (view) Author: Ama Aje My Fren (amaajemyfren) * Date: 2020-06-04 16:08
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.

Date User Action Args
2022-04-11 14:58:22adminsetgithub: 69564
2020-06-04 16:08:41amaajemyfrensetmessages: + msg370715
2020-06-03 20:25:15amaajemyfrensetkeywords: + patch
nosy: + amaajemyfren

pull_requests: + pull_request19846
stage: patch review
2020-05-31 13:19:57serhiy.storchakasetkeywords: + easy
versions: + Python 3.6, Python 3.7, Python 3.8, Python 3.9, Python 3.10, - Python 2.7
2015-10-11 16:34:26georg.brandlsetnosy: + georg.brandl
messages: + msg252819
2015-10-11 15:46:55r.david.murraysetnosy: + r.david.murray
messages: + msg252818
2015-10-11 15:36:26krichtercreate