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

[Kyle Stanley]

New submission from Kyle Stanley <aeros167 at gmail.com>:

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 at python
components: Documentation
messages: 347080
nosy: aeros167, docs at 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 <report at bugs.python.org>
<https://bugs.python.org/issue37478>
_______________________________________