This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

classification
Title: os.utime(path_to_directory): wrong documentation for Windows.
Type: Stage: resolved
Components: Documentation Versions: Python 3.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: cheryl.sabella, docs@python, jgehrcke, larry, matrixise, mdk, tim.golden
Priority: normal Keywords: patch

Created on 2014-02-20 22:57 by jgehrcke, last changed 2022-04-11 14:57 by admin. This issue is now closed.

Files
File name Uploaded Description Edit
issue20709_py27.patch jgehrcke, 2015-02-02 15:19 Docs patch for head in 2.7 branch.
issue20709_tip.patch jgehrcke, 2015-02-02 15:20 Docs patch for tip.
Pull Requests
URL Status Linked Edit
PR 5469 merged matrixise, 2018-02-01 10:00
Messages (11)
msg211760 - (view) Author: Dr. Jan-Philip Gehrcke (jgehrcke) * Date: 2014-02-20 22:57
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%29.aspx): "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.
msg235235 - (view) Author: Tim Golden (tim.golden) * (Python committer) Date: 2015-02-02 08:41
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.
msg235240 - (view) Author: Larry Hastings (larry) * (Python committer) Date: 2015-02-02 11:17
I'm not sure we support 2.7 supports any versions of Windows earlier than XP.  If so, we could drop the provision entirely.
msg235259 - (view) Author: Dr. Jan-Philip Gehrcke (jgehrcke) * Date: 2015-02-02 13:53
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?
msg235262 - (view) Author: Tim Golden (tim.golden) * (Python committer) Date: 2015-02-02 15:07
Fine by me
msg235264 - (view) Author: Dr. Jan-Philip Gehrcke (jgehrcke) * Date: 2015-02-02 15:25
I have added patches for the documentation, where I removed the sentence in question and re-wrapped the paragraph.
msg235636 - (view) Author: Dr. Jan-Philip Gehrcke (jgehrcke) * Date: 2015-02-09 21:23
Can these super-small doc patches get applied or should we change something? Thanks!
msg310533 - (view) Author: Cheryl Sabella (cheryl.sabella) * (Python committer) Date: 2018-01-23 22:22
@jgehrcke, would you be able to convert your patch to a Github pull request on the master branch?
msg311413 - (view) Author: Stéphane Wirtel (matrixise) * (Python committer) Date: 2018-02-01 10:02
Hi @Cheryl

I just created a PR with the patch for 3.8.

Could you take a look?

Thank you
msg315993 - (view) Author: Julien Palard (mdk) * (Python committer) Date: 2018-05-01 10:02
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/7508a54c77e85235e07e344cf9440e5b4695e9cc
msg341818 - (view) Author: Julien Palard (mdk) * (Python committer) Date: 2019-05-07 20:42
Closing this issue, it has been fixed a year ago, thanks Jan-Philip for reporting, Stéphane for fixing, and everybody! \o/ \o/
History
Date User Action Args
2022-04-11 14:57:58adminsetgithub: 64908
2019-05-07 20:42:36mdksetstatus: open -> closed
resolution: fixed
messages: + msg341818

stage: patch review -> resolved
2018-05-01 10:02:28mdksetnosy: + mdk
messages: + msg315993
2018-02-01 10:02:04matrixisesetnosy: + matrixise
messages: + msg311413
2018-02-01 10:00:38matrixisesetstage: needs patch -> patch review
pull_requests: + pull_request5295
2018-01-23 22:22:06cheryl.sabellasetversions: + Python 3.7, - Python 3.1, Python 2.7, Python 3.2, Python 3.3, Python 3.4, Python 3.5
nosy: + cheryl.sabella

messages: + msg310533

stage: needs patch
2015-02-09 21:23:14jgehrckesetmessages: + msg235636
2015-02-02 15:25:57jgehrckesetmessages: + msg235264
2015-02-02 15:20:15jgehrckesetfiles: + issue20709_tip.patch
2015-02-02 15:19:03jgehrckesetfiles: + issue20709_py27.patch
keywords: + patch
2015-02-02 15:07:46tim.goldensetmessages: + msg235262
2015-02-02 13:53:30jgehrckesetmessages: + msg235259
2015-02-02 11:17:24larrysetmessages: + msg235240
2015-02-02 08:41:03tim.goldensetnosy: + tim.golden
messages: + msg235235
2014-02-20 22:58:58vstinnersetnosy: + larry
2014-02-20 22:57:36jgehrckecreate