[issue25377] Mention octal format of mode argument of os.chmod
New submission from Karl Richter: `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-d... ---------- assignee: docs@python components: Documentation messages: 252817 nosy: docs@python, krichter priority: normal severity: normal status: open title: Mention octal format of mode argument of os.chmod type: enhancement versions: Python 2.7 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25377> _______________________________________
R. David Murray added the comment: 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 :). ---------- nosy: +r.david.murray _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25377> _______________________________________
Georg Brandl added the comment: 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.) ---------- nosy: +georg.brandl _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25377> _______________________________________
Change by Serhiy Storchaka <storchaka+cpython@gmail.com>: ---------- keywords: +easy versions: +Python 3.10, Python 3.6, Python 3.7, Python 3.8, Python 3.9 -Python 2.7 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue25377> _______________________________________
Change by Ama Aje My Fren <amaajemyfren@gmail.com>: ---------- keywords: +patch nosy: +amaajemyfren nosy_count: 4.0 -> 5.0 pull_requests: +19846 stage: -> patch review pull_request: https://github.com/python/cpython/pull/20621 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue25377> _______________________________________
Ama Aje My Fren <amaajemyfren@gmail.com> added the comment: 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 ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue25377> _______________________________________
participants (5)
-
Ama Aje My Fren -
Georg Brandl
-
Karl Richter
-
R. David Murray
-
Serhiy Storchaka