os.makedirs() gives the optional variable mode to set the permissions on the directories it creates.

While it seems to work for all triplet octal values (777,755,etc) it doesn't seem to work on values with the sticky bit (1777,1755,etc)

I know that to set the value as octal, you need, for some reason, to prepend a '0' to the number, such that the final value is '01755' - but even if you do int('1755',8) the error is there. Below I make a directory and then chmod it to the right value:

os.makedirs('/Users/Carolin/Desktop/demo',01703)
drwx-----x     2 Carolin  staff      68 12 Jul 18:53 demo

os.chmod('/Users/Carolin/Desktop/demo',01703)
drwx----wt     2 Carolin  staff      68 12 Jul 18:53 demo

This is not a bug, but perhaps the documentation could further clarify that the set of valid values for the mode parameter is platform dependent. The [POSIX specification][1] for mkdir() states that "[w]hen bits in mode other than the file permission bits are set, the meaning of these additional bits is implementation-defined". On Linux, mkdir honors the sticky bit (S_ISVTX). On OS X, on the other hand, the [man page][2] states that "the behavior of mkdir() is undefined when mode bits other than the low 9 bits are used. Use chmod(2) after mkdir() to explicitly set the other bits".

1. http://pubs.opengroup.org/onlinepubs/9699919799/functions/mkdir.html
2. https://developer.apple.com/library/mac/documentation/Darwin/Reference/ManPages/man2/mkdir.2.html

Thanks for the patch Tommy. One minor quirk that bugs me: *mode*'s gets marked up with an opening quote rather than an apostrophe. Perhaps we can change it to a Unicode apostrophe (*mode*’s). Another alternative would be: the octal representation of *mode*.

But looking at the code, makedirs() just passes “mode” through to mkdir(). Maybe the mkdir() documentation needs updating too. Maybe it is better to just refer from makedirs() to mkdir(), rather than duplicating everything; I’m not sure.

I've fixed the apostrophe issue by avoiding it's use.  I've moved the text about the mode to mkdir and added a link to it from makedirs.

I think it would be good to move the sentence about FileExistsError away from your new paragraph about *mode*. Also, I would try to make the hyperlink a bit more explicit and descriptive, maybe

The *mode* parameter is passed to :func:`mkdir`; see :ref:`the mkdir() description <mkdir_modebits>` for how it is interpreted.

See also issue19930.

I think that the documentation should be updated to reflect issue19930's change when that is actually committed, not as a part of this change.

This version of the patch looks good to me

New changeset 4fc7753efc89 by Tommy Beadle in branch '2.7':
Issue #24617: Add comment for os.mkdir about mode quirks
https://hg.python.org/cpython/rev/4fc7753efc89

New changeset e6093676e93b by Tommy Beadle in branch '3.5':
Issue #24617: Add comment for os.mkdir about mode quirks
https://hg.python.org/cpython/rev/e6093676e93b

New changeset bfd77c6fc04f by Martin Panter in branch 'default':
Issue #24617: Merge os.mkdir() doc from 3.5
https://hg.python.org/cpython/rev/bfd77c6fc04f

Please use "hg import --no-commit" in the future. Since Mercurial doesn't keep committer's information it's hard to see who actually committed the patch in case of a problem.

Okay I will avoid this problem in the future. I often use the mq extension, but I can reset the user and date with that.