Issue 20709: os.utime(path_to_directory): wrong documentation for Windows.

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.

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.

I'm not sure we support 2.7 supports any versions of Windows earlier than XP.  If so, we could drop the provision entirely.

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?

Fine by me

I have added patches for the documentation, where I removed the sentence in question and re-wrapped the paragraph.

Can these super-small doc patches get applied or should we change something? Thanks!

@jgehrcke, would you be able to convert your patch to a Github pull request on the master branch?

Hi @Cheryl

I just created a PR with the patch for 3.8.

Could you take a look?

Thank you

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

Closing this issue, it has been fixed a year ago, thanks Jan-Philip for reporting, Stéphane for fixing, and everybody! \o/ \o/

stage: patch review -> resolved

messages: + msg310533

stage: needs patch