Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

os.utime(path_to_directory): wrong documentation for Windows. #64908

Closed
jgehrcke mannequin opened this issue Feb 20, 2014 · 11 comments
Closed

os.utime(path_to_directory): wrong documentation for Windows. #64908

jgehrcke mannequin opened this issue Feb 20, 2014 · 11 comments
Labels
3.7 (EOL) end of life docs Documentation in the Doc dir

Comments

@jgehrcke
Copy link
Mannequin

jgehrcke mannequin commented Feb 20, 2014

BPO 20709
Nosy @larryhastings, @tjguk, @jgehrcke, @matrixise, @JulienPalard, @csabella
PRs
  • bpo-20709: os.utime(path_to_directory): wrong documentation for Windows. #5469
    		•
    Files
  • issue20709_py27.patch: Docs patch for head in 2.7 branch.
  • issue20709_tip.patch: Docs patch for tip.
    		•

    Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.

    Show more details

    GitHub fields:

    assignee = None
closed_at = <Date 2019-05-07.20:42:36.269>
created_at = <Date 2014-02-20.22:57:35.975>
labels = ['3.7', 'docs']
title = 'os.utime(path_to_directory): wrong documentation for Windows.'
updated_at = <Date 2019-05-07.20:42:36.267>
user = 'https://github.com/jgehrcke'

    bugs.python.org fields:

    activity = <Date 2019-05-07.20:42:36.267>
actor = 'mdk'
assignee = 'docs@python'
closed = True
closed_date = <Date 2019-05-07.20:42:36.269>
closer = 'mdk'
components = ['Documentation']
creation = <Date 2014-02-20.22:57:35.975>
creator = 'jgehrcke'
dependencies = []
files = ['37979', '37980']
hgrepos = []
issue_num = 20709
keywords = ['patch']
message_count = 11.0
messages = ['211760', '235235', '235240', '235259', '235262', '235264', '235636', '310533', '311413', '315993', '341818']
nosy_count = 7.0
nosy_names = ['larry', 'tim.golden', 'jgehrcke', 'docs@python', 'matrixise', 'mdk', 'cheryl.sabella']
pr_nums = ['5469']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue20709'
versions = ['Python 3.7']
    @jgehrcke
    Copy link
    Mannequin Author

    jgehrcke mannequin commented Feb 20, 2014

    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](https://github.com/python/cpython/blob/main/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.

    @jgehrcke jgehrcke mannequin assigned docspython Feb 20, 2014
    @jgehrcke jgehrcke mannequin added the docs Documentation in the Doc dir label Feb 20, 2014
    @tjguk
    Copy link
    Member

    tjguk commented Feb 2, 2015

    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.

    @larryhastings
    Copy link
    Contributor

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

    @jgehrcke
    Copy link
    Mannequin Author

    jgehrcke mannequin commented Feb 2, 2015

    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?

    @tjguk
    Copy link
    Member

    tjguk commented Feb 2, 2015

    Fine by me

    @jgehrcke
    Copy link
    Mannequin Author

    jgehrcke mannequin commented Feb 2, 2015

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

    @jgehrcke
    Copy link
    Mannequin Author

    jgehrcke mannequin commented Feb 9, 2015

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

    @csabella
    Copy link
    Contributor

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

    @csabella csabella added the 3.7 (EOL) end of life label Jan 23, 2018
    @matrixise
    Copy link
    Member

    Hi @cheryl

    I just created a PR with the patch for 3.8.

    Could you take a look?

    Thank you

    @JulienPalard
    Copy link
    Member

    New changeset 7508a54 by Julien Palard (Stéphane Wirtel) in branch 'master':
    bpo-20709: os.utime(path_to_directory): wrong documentation for Windows. (GH-5469)
    7508a54

    @JulienPalard
    Copy link
    Member

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

    @ezio-melotti ezio-melotti transferred this issue from another repository Apr 10, 2022
    Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
    Assignees
    No one assigned
    Labels
    3.7 (EOL) end of life docs Documentation in the Doc dir
    Projects
    None yet
    Milestone
    No milestone
    Development

    No branches or pull requests
    5 participants
    @matrixise @JulienPalard @tjguk @larryhastings @csabella