[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 <report@bugs.python.org> <http://bugs.python.org/issue20709> _______________________________________
Changes by STINNER Victor <victor.stinner@gmail.com>: ---------- nosy: +larry _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue20709> _______________________________________
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 <report@bugs.python.org> <http://bugs.python.org/issue20709> _______________________________________
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 <report@bugs.python.org> <http://bugs.python.org/issue20709> _______________________________________
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 <report@bugs.python.org> <http://bugs.python.org/issue20709> _______________________________________
Tim Golden added the comment: Fine by me ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue20709> _______________________________________
Changes by Jan-Philip Gehrcke <jgehrcke@gmail.com>: ---------- keywords: +patch Added file: http://bugs.python.org/file37979/issue20709_py27.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue20709> _______________________________________
Changes by Jan-Philip Gehrcke <jgehrcke@gmail.com>: Added file: http://bugs.python.org/file37980/issue20709_tip.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue20709> _______________________________________
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 <report@bugs.python.org> <http://bugs.python.org/issue20709> _______________________________________
Jan-Philip Gehrcke added the comment: Can these super-small doc patches get applied or should we change something? Thanks! ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue20709> _______________________________________
Cheryl Sabella <chekat2@gmail.com> added the comment: @jgehrcke, would you be able to convert your patch to a Github pull request on the master branch? ---------- nosy: +csabella stage: -> needs patch versions: +Python 3.7 -Python 2.7, Python 3.1, Python 3.2, Python 3.3, Python 3.4, Python 3.5 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue20709> _______________________________________
Change by Stéphane Wirtel <stephane@wirtel.be>: ---------- pull_requests: +5295 stage: needs patch -> patch review _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue20709> _______________________________________
Stéphane Wirtel <stephane@wirtel.be> added the comment: Hi @Cheryl I just created a PR with the patch for 3.8. Could you take a look? Thank you ---------- nosy: +matrixise _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue20709> _______________________________________
Julien Palard <julien+python@palard.fr> added the comment: New changeset 7508a54c77e85235e07e344cf9440e5b4695e9cc by Julien Palard (Stéphane Wirtel) in branch 'master': bpo-20709: os.utime(path_to_directory): wrong documentation for Windows. (GH-5469) https://github.com/python/cpython/commit/7508a54c77e85235e07e344cf9440e5b469... ---------- nosy: +mdk _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue20709> _______________________________________
Julien Palard <julien+python@palard.fr> added the comment: Closing this issue, it has been fixed a year ago, thanks Jan-Philip for reporting, Stéphane for fixing, and everybody! \o/ \o/ ---------- resolution: -> fixed stage: patch review -> resolved status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue20709> _______________________________________
participants (7)
-
Cheryl Sabella -
Jan-Philip Gehrcke
-
Julien Palard
-
Larry Hastings
-
STINNER Victor
-
Stéphane Wirtel
-
Tim Golden