[issue20709] os.utime(path_to_directory): wrong documentation for Windows.
New submission from Jan-Philip Gehrcke: The os.utime() docs for Python 2 (http://docs.python.org/2/library/os.html#os.utime) and 3 (http://docs.python.org/3/library/os.html#os.utime) both contain the sentence "Whether a directory can be given for path depends on whether the operating system implements directories as files (for example, *Windows does not*)" "Windoes does not" is wrong. CPython 2.7 on Windows 7:
os.utime(".", (100, 100)) os.stat(".").st_mtime 100.0
We should
- either name a specific system for which this does not work
- or remove this example.
Windows XP and newer support this operation via SetFileTime (http://msdn.microsoft.com/en-us/library/windows/desktop/ms724933%28v=vs.85%2...): "Sets the date and time that the specified file or directory was created, last accessed, or last modified."
I have grepped myself through a couple of CPython source trees and found
posixmodule.c: if (!SetFileTime(hFile, NULL, &atime, &mtime)
in 2.5, 2.6, 2.7. I guess the statement comes from 2.4 times, where `SetFileTime` only appears in `PC/bdist_wininst/extract.c`.
So, do we just remove the hint or does someone have an example at hand for which combination of Python and platform this does not work for directories? Once we have a decision, I will be happy to provide the mini patch.
----------
assignee: docs@python
components: Documentation
messages: 211760
nosy: docs@python, jgehrcke
priority: normal
severity: normal
status: open
title: os.utime(path_to_directory): wrong documentation for Windows.
versions: Python 2.7, Python 3.1, Python 3.2, Python 3.3, Python 3.4, Python 3.5
_______________________________________
Python tracker
Changes by STINNER Victor
Tim Golden added the comment:
I think we should simply take out the example, ie the part in brackets. The statement remains true but I don't think we need to cast around for whichever OS / filesystem happens to implement this particular setup.
----------
nosy: +tim.golden
_______________________________________
Python tracker
Larry Hastings added the comment:
I'm not sure we support 2.7 supports any versions of Windows earlier than XP. If so, we could drop the provision entirely.
----------
_______________________________________
Python tracker
Jan-Philip Gehrcke added the comment:
Windows is the only Python-supported platform where utime did not work for directories, ages ago, right?
If that is the case, I support Larry Hastings' approach of removing the entire sentence:
"Whether a directory can be given for path depends on whether the operating system implements directories as files (for example, *Windows does not*)"
Agreed?
----------
_______________________________________
Python tracker
Tim Golden added the comment:
Fine by me
----------
_______________________________________
Python tracker
Changes by Jan-Philip Gehrcke
Changes by Jan-Philip Gehrcke
Jan-Philip Gehrcke added the comment:
I have added patches for the documentation, where I removed the sentence in question and re-wrapped the paragraph.
----------
_______________________________________
Python tracker
Jan-Philip Gehrcke added the comment:
Can these super-small doc patches get applied or should we change something? Thanks!
----------
_______________________________________
Python tracker
Cheryl Sabella
Change by Stéphane Wirtel
Stéphane Wirtel
Julien Palard
Julien Palard
participants (7)
-
Cheryl Sabella -
Jan-Philip Gehrcke
-
Julien Palard
-
Larry Hastings
-
STINNER Victor
-
Stéphane Wirtel
-
Tim Golden