Use OSError subclasses in os documentation (GH-14262)

This commit is contained in:
Tim Hoffmann 2019-07-05 10:41:35 +02:00 committed by Andrew Svetlov
parent 2f19e82fbe
commit a55f75a6e3
1 changed files with 24 additions and 17 deletions

View File

@ -36,9 +36,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
@ -1898,8 +1898,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::
@ -2052,8 +2052,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>`.
@ -2090,13 +2090,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>`.
@ -2145,9 +2151,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>`.