Title: os.makedirs()'s [mode] not correct
Type: behavior Stage: resolved
Components: Documentation Versions: Python 3.6, Python 3.5, Python 2.7
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: John Jones, berker.peksag, docs@python, eryksun, martin.panter, python-dev, serhiy.storchaka, tbeadle
Priority: normal Keywords: patch

Created on 2015-07-12 17:13 by John Jones, last changed 2016-06-10 09:47 by martin.panter. This issue is now closed.

File name Uploaded Description Edit
0001-Issue-24617-Add-comment-for-os.makedirs-about-certai.patch tbeadle, 2016-06-02 19:43 patch to add to documentation for os.makedirs
0001-Issue-24617-Add-comment-for-os.makedirs-about-certai.patch tbeadle, 2016-06-04 00:44 updated patch
0001-Issue-24617-Add-comment-for-os.makedirs-about-certai.patch tbeadle, 2016-06-08 13:01 Updated patch based on review comments
Messages (11)
msg246655 - (view) Author: John Jones (John Jones) Date: 2015-07-12 17:13
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:

drwx-----x     2 Carolin  staff      68 12 Jul 18:53 demo

drwx----wt     2 Carolin  staff      68 12 Jul 18:53 demo
msg246659 - (view) Author: Eryk Sun (eryksun) * (Python triager) Date: 2015-07-12 18:24
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".

msg267193 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2016-06-04 00:16
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.
msg267207 - (view) Author: Tommy Beadle (tbeadle) * Date: 2016-06-04 00:44
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.
msg267240 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2016-06-04 07:06
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.
msg267849 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2016-06-08 13:41
See also issue19930.
msg267852 - (view) Author: Tommy Beadle (tbeadle) * Date: 2016-06-08 13:49
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.
msg268084 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2016-06-10 04:36
This version of the patch looks good to me
msg268108 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2016-06-10 08:49
New changeset 4fc7753efc89 by Tommy Beadle in branch '2.7':
Issue #24617: Add comment for os.mkdir about mode quirks

New changeset e6093676e93b by Tommy Beadle in branch '3.5':
Issue #24617: Add comment for os.mkdir about mode quirks

New changeset bfd77c6fc04f by Martin Panter in branch 'default':
Issue #24617: Merge os.mkdir() doc from 3.5
msg268109 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2016-06-10 09:14
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.
msg268111 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2016-06-10 09:47
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.
Date User Action Args
2016-06-10 09:47:33martin.pantersetstatus: open -> closed
resolution: fixed
stage: commit review -> resolved
2016-06-10 09:47:11martin.pantersetmessages: + msg268111
2016-06-10 09:14:21berker.peksagsetnosy: + berker.peksag
messages: + msg268109
2016-06-10 08:49:42python-devsetnosy: + python-dev
messages: + msg268108
2016-06-10 04:36:01martin.pantersetmessages: + msg268084
stage: patch review -> commit review
2016-06-08 13:49:55tbeadlesetmessages: + msg267852
2016-06-08 13:41:52serhiy.storchakasetnosy: + serhiy.storchaka
messages: + msg267849
2016-06-08 13:01:43tbeadlesetfiles: + 0001-Issue-24617-Add-comment-for-os.makedirs-about-certai.patch
2016-06-04 07:06:23martin.pantersetnosy: + docs@python
messages: + msg267240

assignee: docs@python
components: + Documentation
2016-06-04 00:44:45tbeadlesetfiles: + 0001-Issue-24617-Add-comment-for-os.makedirs-about-certai.patch

messages: + msg267207
2016-06-04 00:16:13martin.pantersetversions: + Python 3.5, Python 3.6
nosy: + martin.panter

messages: + msg267193

stage: patch review
2016-06-03 17:09:46tbeadlesetnosy: + tbeadle
2016-06-02 19:43:16tbeadlesetfiles: + 0001-Issue-24617-Add-comment-for-os.makedirs-about-certai.patch
keywords: + patch
2015-07-12 18:24:06eryksunsetnosy: + eryksun
messages: + msg246659
2015-07-12 17:13:43John Jonescreate