[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