Mention octal format of mode argument of os.chmod

[krichter]

BPO	25377
Nosy	@birkenfeld, @bitdancer, @amaajemyfren
PRs	GH-69564: 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]

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

[bitdancer]

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]

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]

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