It would be helpful to explicitly document that os.chmod accepts octal digit modes e.g. os.chmod(path, 0755). This is much more user friendly than saying you must OR bit constants kept in a completely different module. It could be argued that this change would be make the abstraction leaky, since the values of the stat.S_I* constants could change, but in practice, this seems unlikely.
I think you misunderstand what's happening. It's not that os.chmod accepts octal digits, but Python: py> 04732 2522 So the support for octal numbers isn't something that chmod deserves credit for.
If using octal digits instead of the stat.S_I constants is acceptable, I'd be +1 to add a note to the documentation (something like "mode could be a number (possibly expressed in octal form, such as 0755), one of the following values (as defined in the stat module), or a bitwise ORed combinations of them:").
(3.1.2) 15.1.5. Files and Directories os.chmode entry: I recommend changing the first sentence "Change the mode of path to the numeric mode." to "Change the mode of path to the integer mode (such as 0x755)." For 2.7, delete the 'x'. This should make it clear to Unix users that they can use the usual octal designations.
I guess you mean 0o755. I think it would be better to mention explicitly octal literals, since they are not so common and, especially in 2.x, 0755 might be confused with a "normal" decimal number.
