classification
Title: Documentation of EnvironmentError (OSError) arguments disappeared
Type: Stage: resolved
Components: Documentation Versions: Python 3.6, Python 3.4, Python 3.5
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: martin.panter Nosy List: docs@python, martin.panter, pitrou, python-dev, r.david.murray, serhiy.storchaka
Priority: normal Keywords: needs review, patch

Created on 2015-02-04 05:06 by martin.panter, last changed 2015-10-27 09:03 by serhiy.storchaka. This issue is now closed.

Files
File name Uploaded Description Edit
os-error-args.patch martin.panter, 2015-02-08 02:45 review
os-error-args.v2.patch martin.panter, 2015-06-11 04:40 review
os-error-args.v3.patch martin.panter, 2015-06-12 01:48 review
Messages (11)
msg235372 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2015-02-04 05:06
Seems to have been removed in revision 097f4fda61a4, for PEP 3151. The older EnvironmentError documentation talks about creating the exception with two and three constructor arguments, however I don’t see this in the new documentation. Is this usage meant to be deprecated, or still allowed? Either way, I think the documentation should mention it.
msg235542 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2015-02-08 02:45
Here is a patch to redocument the constructor arguments. I am assuming that they were only removed by accident. The constructor arguments are already tested in ExceptionTests.testAttributes() at Lib/test/test_exceptions.py:248.

I did not restore the bit about more than three arguments being reflected in the “args” attribute, since this is not the current behaviour, and does not seem very important:

>>> OSError(1, 2, 3, 4).args
(1, 2)
msg238781 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2015-03-21 09:37
Current behavior is more complicated.

>>> OSError(1, 2, 3, 4).args
(1, 2)
>>> OSError(1, 2, 3, 4, 5).args
(1, 2)
>>> OSError(1, 2, 3, 4, 5, 6).args
(1, 2, 3, 4, 5, 6)

If I remember correctly:

1 -- errno
2 -- strerror
3 -- filename
4 -- winerror (?)
5 -- filename2

Isn't it documented anywhere?
msg245154 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2015-06-11 04:40
New patch with the following changes. Let me know what you think.

* Added extra markup for OSError attributes and constructor signature
* Explained how “winerror” works with and without Windows
* Added “filename2” argument
* Update tests for filename2 defaulting to None

For reference, the argument handling seems to be in oserror_parse_args(), at Objects/exceptions.c:724, and related functions.
msg245157 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2015-06-11 07:36
It should be documented (if still not) that OSError() constructor can return an instance of OSError subclass, depending on errno value.

>>> OSError(errno.ENOENT, 'no such file')
FileNotFoundError(2, 'no such file')
msg245158 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2015-06-11 08:08
Good point Serhiy about returning subclasses. I’ll see about making that more explicit if I can’t find it already documented somewhere.

Regarding the number of arguments, I resisted documenting what happens to extra arguments since the behaviour has changed over time, and it doesn’t seem that it would be very useful. IMO it would be better to say passing extra arguments is not supported. But if others disagree, I can have a go at documenting the existing and/or past behaviour.

Python 3.3.3 under Wine:
>>> OSError(None, "Not found", "file", 3).args 
(2, 'Not found', 'file', 3)
>>> OSError(ENOENT, "Not found", "file", None).args
(2, 'Not found', 'file', None)

Python 3.6.0a0 under Linux:
>>> OSError(ENOENT, "Not found", "file", None).args
(2, 'Not found')
msg245203 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2015-06-12 01:48
New patch, clarifying that the constructor can raise a subclass.

If you still think I need to add something about extra arguments, or how the “args” attribute is set, let me know.
msg253171 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2015-10-19 05:43
The patch LGTM. We should handle the problem with extra arguments in separate issue.
msg253507 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2015-10-27 00:00
New changeset cb554248ce54 by Martin Panter in branch '3.4':
Issue #23391: Restore OSError constructor argument documentation
https://hg.python.org/cpython/rev/cb554248ce54

New changeset 7b1a9a12eb77 by Martin Panter in branch '3.5':
Issue #23391: Merge OSError doc from 3.4 into 3.5
https://hg.python.org/cpython/rev/7b1a9a12eb77

New changeset e5df201c0846 by Martin Panter in branch 'default':
Issue #23391: Merge OSError doc from 3.5
https://hg.python.org/cpython/rev/e5df201c0846
msg253510 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2015-10-27 00:51
I will leave opening a bug for the args issue for someone else. But if you come up with a sensible solution or find out all the details, I am happy to help write up or review the documentation changes.
msg253524 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2015-10-27 09:03
There is an outdated comment in Objects/exceptions.c that explains args hacking. It refers to no longer supported syntax:

    except OSError, (errno, strerror):
History
Date User Action Args
2015-10-27 09:03:26serhiy.storchakasetmessages: + msg253524
2015-10-27 00:51:15martin.pantersetstatus: open -> closed
resolution: fixed
messages: + msg253510

stage: commit review -> resolved
2015-10-27 00:00:58python-devsetnosy: + python-dev
messages: + msg253507
2015-10-19 05:43:41serhiy.storchakasetassignee: docs@python -> martin.panter
stage: patch review -> commit review
2015-10-19 05:43:09serhiy.storchakasetmessages: + msg253171
2015-10-19 05:42:04serhiy.storchakasetmessages: - msg253170
2015-10-19 05:40:18serhiy.storchakasetmessages: + msg253170
2015-10-19 04:09:06martin.panterlinkissue16785 dependencies
2015-06-12 01:48:53martin.pantersetfiles: + os-error-args.v3.patch

messages: + msg245203
2015-06-11 08:08:06martin.pantersetmessages: + msg245158
2015-06-11 07:36:50serhiy.storchakasetmessages: + msg245157
2015-06-11 07:06:34serhiy.storchakasetnosy: + r.david.murray
2015-06-11 04:40:54martin.pantersetfiles: + os-error-args.v2.patch

messages: + msg245154
versions: + Python 3.6
2015-03-21 09:37:04serhiy.storchakasetnosy: + serhiy.storchaka
messages: + msg238781
2015-02-28 13:43:59serhiy.storchakasetkeywords: + needs review
nosy: + pitrou
stage: patch review

versions: + Python 3.5, - Python 3.3
2015-02-08 02:45:29martin.pantersetfiles: + os-error-args.patch
keywords: + patch
messages: + msg235542
2015-02-04 05:06:50martin.pantercreate