Use OSError subclasses in os documentation (GH-14262)

(cherry picked from commit a55f75a)

Co-authored-by: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>

Doc/library/os.rst

@@ -35,9 +35,9 @@ Notes on the availability of these functions:
 
 .. note::
 
- All functions in this module raise :exc:`OSError` in the case of invalid or
- inaccessible file names and paths, or other arguments that have the correct
- type, but are not accepted by the operating system.
+ All functions in this module raise :exc:`OSError` (or subclasses thereof) in
+ the case of invalid or inaccessible file names and paths, or other arguments
+ that have the correct type, but are not accepted by the operating system.
 
 .. exception:: error
 
@@ -1858,8 +1858,8 @@ features:
  directories you can set the umask before invoking :func:`makedirs`. The
  file permission bits of existing parent directories are not changed.
 
- If *exist_ok* is ``False`` (the default), an :exc:`OSError` is raised if the
- target directory already exists.
+ If *exist_ok* is ``False`` (the default), an :exc:`FileExistsError` is
+ raised if the target directory already exists.
 
  .. note::
 
@@ -2010,8 +2010,8 @@ features:
 
 .. function:: remove(path, *, dir_fd=None)
 
- Remove (delete) the file *path*. If *path* is a directory, :exc:`OSError` is
- raised. Use :func:`rmdir` to remove directories.
+ Remove (delete) the file *path*. If *path* is a directory, an
+ :exc:`IsADirectoryError` is raised. Use :func:`rmdir` to remove directories.
 
  This function can support :ref:`paths relative to directory descriptors
  <dir_fd>`.
@@ -2048,13 +2048,19 @@ features:
 
 .. function:: rename(src, dst, *, src_dir_fd=None, dst_dir_fd=None)
 
- Rename the file or directory *src* to *dst*. If *dst* is a directory,
- :exc:`OSError` will be raised. On Unix, if *dst* exists and is a file, it will
- be replaced silently if the user has permission. The operation may fail on some
- Unix flavors if *src* and *dst* are on different filesystems. If successful,
- the renaming will be an atomic operation (this is a POSIX requirement). On
- Windows, if *dst* already exists, :exc:`OSError` will be raised even if it is a
- file.
+ Rename the file or directory *src* to *dst*. If *dst* exists, the operation
+ will fail with an :exc:`OSError` subclass in a number of cases:
+
+ On Windows, if *dst* exists a :exc:`FileExistsError` is always raised.
+
+ On Unix, if *src* is a file and *dst* is a directory or vice-versa, anq:q
+ :exc:`IsADirectoryError` or a :exc:`NotADirectoryError` will be raised
+ respectively. If both are directories and *dst* is empty, *dst* will be
+ silently replaced. If *dst* is a non-empty directory, an :exc:`OSError`
+ is raised. If both are files, *dst* it will be replaced silently if the user
+ has permission. The operation may fail on some Unix flavors if *src* and
+ *dst* are on different filesystems. If successful, the renaming will be an
+ atomic operation (this is a POSIX requirement).
 
  This function can support specifying *src_dir_fd* and/or *dst_dir_fd* to
  supply :ref:`paths relative to directory descriptors <dir_fd>`.
@@ -2103,9 +2109,10 @@ features:
 
 .. function:: rmdir(path, *, dir_fd=None)
 
- Remove (delete) the directory *path*. Only works when the directory is
- empty, otherwise, :exc:`OSError` is raised. In order to remove whole
- directory trees, :func:`shutil.rmtree` can be used.
+ Remove (delete) the directory *path*. If the directory does not exist or is
+ not empty, an :exc:`FileNotFoundError` or an :exc:`OSError` is raised
+ respectively. In order to remove whole directory trees,
+ :func:`shutil.rmtree` can be used.
 
  This function can support :ref:`paths relative to directory descriptors
  <dir_fd>`.