[issue37478] Docs: Method os.chdir() does not mention errors that can be raised

[Kyle Stanley]

Kyle Stanley  added the comment:

Exceptions for os.chdir() have been added to the docs.

--
resolution:  -> fixed
stage: patch review -> resolved
status: open -> closed

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue37478] Docs: Method os.chdir() does not mention errors that can be raised

[miss-islington]

miss-islington  added the comment:


New changeset e414aa9cb002427a39dfd157cdad156336f93ca9 by Miss Islington (bot) 
in branch '3.8':
bpo-37478: Add missing 'and'. (GH-14631)
https://github.com/python/cpython/commit/e414aa9cb002427a39dfd157cdad156336f93ca9


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue37478] Docs: Method os.chdir() does not mention errors that can be raised

[miss-islington]

miss-islington  added the comment:


New changeset e841a54206c65770aeb2b936cdc830dd4ed8bf9e by Miss Islington (bot) 
in branch '3.7':
bpo-37478: Add missing 'and'. (GH-14631)
https://github.com/python/cpython/commit/e841a54206c65770aeb2b936cdc830dd4ed8bf9e


--
nosy: +miss-islington

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue37478] Docs: Method os.chdir() does not mention errors that can be raised

[miss-islington]

Change by miss-islington :


--
pull_requests: +14447
pull_request: https://github.com/python/cpython/pull/14633

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue37478] Docs: Method os.chdir() does not mention errors that can be raised

[Terry J. Reedy]

Terry J. Reedy  added the comment:


New changeset a9b40e4546ca631e5ab41376b5b72e8f296f557d by Terry Jan Reedy in 
branch 'master':
bpo-37478: Add missing 'and'. (GH-14631)
https://github.com/python/cpython/commit/a9b40e4546ca631e5ab41376b5b72e8f296f557d


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue37478] Docs: Method os.chdir() does not mention errors that can be raised

[miss-islington]

Change by miss-islington :


--
pull_requests: +14446
pull_request: https://github.com/python/cpython/pull/14632

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue37478] Docs: Method os.chdir() does not mention errors that can be raised

[Terry J. Reedy]

Change by Terry J. Reedy :


--
pull_requests: +14445
pull_request: https://github.com/python/cpython/pull/14631

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue37478] Docs: Method os.chdir() does not mention errors that can be raised

[Terry J. Reedy]

Terry J. Reedy  added the comment:


New changeset 1dd65075955337183ba2f78cb11a1eec2466dc74 by Terry Jan Reedy (Miss 
Islington (bot)) in branch '3.7':
bpo-37478: Specify possible exceptions for os.chdir() (GH-14611) (GH-14630)
https://github.com/python/cpython/commit/1dd65075955337183ba2f78cb11a1eec2466dc74


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue37478] Docs: Method os.chdir() does not mention errors that can be raised

[Terry J. Reedy]

Terry J. Reedy  added the comment:


New changeset 4e6bfc4c605d92d2395fbcded9cf45cdd1ced810 by Terry Jan Reedy (Miss 
Islington (bot)) in branch '3.8':
bpo-37478: Specify possible exceptions for os.chdir() (GH-14611) (GH-14629)
https://github.com/python/cpython/commit/4e6bfc4c605d92d2395fbcded9cf45cdd1ced810


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue37478] Docs: Method os.chdir() does not mention errors that can be raised

[miss-islington]

Change by miss-islington :


--
pull_requests: +14443
stage: commit review -> patch review
pull_request: https://github.com/python/cpython/pull/14629

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue37478] Docs: Method os.chdir() does not mention errors that can be raised

[Terry J. Reedy]

Terry J. Reedy  added the comment:


New changeset 0717b4d9b3899c5c2ca13031e4ff619a15a4d368 by Terry Jan Reedy (Kyle 
Stanley) in branch 'master':
bpo-37478: Specify possible exceptions for os.chdir() (GH-14611)
https://github.com/python/cpython/commit/0717b4d9b3899c5c2ca13031e4ff619a15a4d368


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue37478] Docs: Method os.chdir() does not mention errors that can be raised

[miss-islington]

Change by miss-islington :


--
pull_requests: +1
pull_request: https://github.com/python/cpython/pull/14630

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue37478] Docs: Method os.chdir() does not mention errors that can be raised

[Terry J. Reedy]

Terry J. Reedy  added the comment:

Please ask your questions about doc conventions, both about exceptions and 
function/method.  Either someone will point to something in the devguide, or we 
might get a discussion about something that should be added.  I would not merge 
more extensive changes without some feedback.

--
assignee: docs@python -> terry.reedy
stage: patch review -> commit review
versions: +Python 3.7, Python 3.8

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue37478] Docs: Method os.chdir() does not mention errors that can be raised

[Kyle Stanley]

Kyle Stanley  added the comment:

Actually, I don't believe that I have the appropriate permissions to manually 
specify reviewers for PRs in the cpython repository. Do I have to be added a 
member of the Python organization on GitHub for this? I'm registered as a PSF 
contributing member, but I don't think that alone translates to any repository 
permissions. Could I be added as a member with low level permissions such as 
editing issue labels without being granted commit? This would also be helpful 
for adding "skip news" labels on any other issues, I've been doing a decent 
amount of PR reviews recently.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue37478] Docs: Method os.chdir() does not mention errors that can be raised

[Kyle Stanley]

Change by Kyle Stanley :


--
keywords: +patch
pull_requests: +14425
stage:  -> patch review
pull_request: https://github.com/python/cpython/pull/14611

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue37478] Docs: Method os.chdir() does not mention errors that can be raised

[Kyle Stanley]

Kyle Stanley  added the comment:

Thanks for the feedback terry. Do you think it would be helpful to work through 
some of the other commonly used functions in OS, adding condensed explanations 
of exceptions which can be raised? In general, it seems quite useful for users 
to be able to figure out the exceptions in which they may need to account for 
when using each of the functions. 

Also, should the naming convention be "method" or "function"? The two roughly 
refer to the same thing, but as far as I'm aware, the convention in Python is 
to refer to them as "functions". I'm  used to calling them "methods" from my 
prior experience with OOP, so that's why I did so in my initial condensed 
description. On the docs for OS, there seems to be a few instances where the 
term "method" is used. 

Personally, I don't mind the usage of either term, at the end of the day it's 
just semantics. But for the purposes of documentation, consistency seems 
preferable. Should I create a PR for replacing the mentions of "method" with 
"function"? Since it's quite minor and in the same OS.rst file, should I link 
it to this issue instead of creating a new one?

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue37478] Docs: Method os.chdir() does not mention errors that can be raised

[Terry J. Reedy]

Terry J. Reedy  added the comment:

> what exactly is the standard for mentioning errors
My impression is that there is none, or that it is inconsistent, but that the 
trend is to say more.  If you want to followup, check the documentation 
chapters of the devguide, and if there is nothing clear now, post to the pydev 
list.

https://docs.python.org/3/library/os.html#os-file-dir has

 os.chdir(path)
Change the current working directory to path.
This function can support specifying a file descriptor. The descriptor must 
refer to an opened directory, not an open file.

Most of the other entries in do not mention errors, but is_dir has the line 
mentioned.  I think the condensed line is enough to add, as the sub-exception 
names are self-explanatory; and when they occur, the full message certainly is. 
 (I verified both possibilities mentioned.)  Most users should just catch 
OSError, if anything.

Make a PR with the short message and request me as a reviewer.

--
nosy: +terry.reedy

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue37478] Docs: Method os.chdir() does not mention errors that can be raised

[Kyle Stanley]

Kyle Stanley  added the comment:

Minor clarifications:

This change is referring to the "Files and Directories" section of the "os.rst" 
page in "cpython/Doc/library/os.rst".

Also, I realized that I forgot to add the colon before "exc" in a couple 
locations. This was just a typo when writing the comment, it is correctly 
formatted in my local branch.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue37478] Docs: Method os.chdir() does not mention errors that can be raised

[Kyle Stanley]

New submission from Kyle Stanley :

In the section describing the functionality of os.chdir(), there is no mention 
of possible errors that can be raised. This differentiates significantly from 
the sections of other methods, such as os.is_dir():

"This method can raise :exc:`OSError`, such as :exc:`PermissionError`, but 
:exc:`FileNotFoundError` is caught and not raised."

For the purpose of consistency and providing additional useful information, I 
would suggest doing the same for os.chdir(). os.chdir() differs from 
os.is_dir() by directly raising the OSErrors FileNotFoundError and 
NotADirectoryError rather than handling them. I would suggest the addition of 
the following in os.chdir()'s section:

"This method can raise :exc:`OSError`, such as exc:`FileNotFoundError` if the 
*path* does not lead to a valid file or exc:`NotADirectoryError` if the file 
specified is not a valid directory."

or a less verbose alternative:

"This method can raise :exc:`OSError`, such as exc:`FileNotFoundError` and 
exc:`NotADirectoryError`."

If a user is reading the documentation, they might naturally assume that 
os.chdir() catches the FileNotFoundError, similar to the behavior in 
os.is_dir(). Also, the NotADirectoryError is not explicitly mentioned anywhere 
else on the "os.rst" page. If it were to be mentioned anywhere, os.chdir() 
would probably be the most relevant location to do so.

Also, as a general question, what exactly is the standard for mentioning errors 
in the method sections for the Python documentation? For the purposes of 
clarity, I think it would be quite useful to explicitly mention errors, and a 
brief description of situations which raise them. If the behavior of the errors 
is consistent across of a group of methods, it can instead be mentioned in the 
header section. 

However, if the behavior not consistent, such as in this case, I think it is 
useful to briefly mention how the method deviates. It also seems useful to 
mention the error at least once if it is not explicitly mentioned elsewhere on 
the page, even if the parent is mentioned, such as with NotADirectoryError and 
OSError. This seems to be particularly important to do for the docs in a 
language such as Python, as it does not require the raise-able/throw-able 
errors to be mentioned in the code. 

I have already created a branch in my local fork of the cpython repository 
which implements this change, but I'll await feedback before submitting the PR.

--
assignee: docs@python
components: Documentation
messages: 347080
nosy: aeros167, docs@python
priority: normal
severity: normal
status: open
title: Docs: Method os.chdir() does not mention errors that can be raised
type: enhancement
versions: Python 3.9

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com