os.utime() docs not clear on behavior on nonexistant files

[dewin]

BPO	15228
Nosy	@larryhastings
Files	issue15228-utime-touch-doc.patch

^{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 2013-10-06.16:57:21.793>
created_at = <Date 2012-06-30.19:55:23.278>
labels = ['type-feature', 'docs']
title = 'os.utime() docs not clear on behavior on nonexistant files'
updated_at = <Date 2013-10-06.16:57:21.792>
user = 'https://bugs.python.org/dewin'

bugs.python.org fields:

activity = <Date 2013-10-06.16:57:21.792>
actor = 'python-dev'
assignee = 'docs@python'
closed = True
closed_date = <Date 2013-10-06.16:57:21.793>
closer = 'python-dev'
components = ['Documentation']
creation = <Date 2012-06-30.19:55:23.278>
creator = 'dewin'
dependencies = []
files = ['26306']
hgrepos = []
issue_num = 15228
keywords = ['patch']
message_count = 4.0
messages = ['164422', '164904', '165457', '199101']
nosy_count = 5.0
nosy_names = ['larry', 'docs@python', 'bbrazil', 'python-dev', 'dewin']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue15228'
versions = []

[dewin]

The documentation for os.utime() at http://docs.python.org/py3k/library/os.html#os.utime states:

"Set the access and modified times of the file specified by path. [...] The effect is similar to running the Unix program touch on the path.)"

Unlike 'touch', os.utime() will not create an empty file if called on a file that does not exist. IMO the current behavior is correct, but the comparison of os.utime() to touch implies that it would create empty files.

I suggest clarifying the documentation to emphasize that os.utime() will not create new files and raises OSError in the event that the file does not exist.

[bbrazil]

Here's a patch that should clarify this.

[larryhastings]

I don't think this needs clarifying. If you think the reference to "touch" currently only muddles the issue, let's remove it entirely.

[python-dev]

New changeset 62321359c35b by Georg Brandl in branch '3.3':
Closes bpo-15228: remove reference to Unix "touch"; it is confusing since the path needs to exist for os.utime() to succeed
http://hg.python.org/cpython/rev/62321359c35b