From 6fa7aada9bd3616e0beeb266e818497b2ec1c859 Mon Sep 17 00:00:00 2001 From: Brett Cannon Date: Tue, 6 Sep 2016 15:55:02 -0700 Subject: [PATCH] Issue #26027, #27524: Document the support for path-like objects in os and os.path. This completes PEP 519. --- Doc/library/functions.rst | 10 +-- Doc/library/os.path.rst | 87 ++++++++++++++++++++- Doc/library/os.rst | 158 ++++++++++++++++++++++++++++++++++---- 3 files changed, 233 insertions(+), 22 deletions(-) diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index d621e87c054..3e2fb72841a 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -878,11 +878,11 @@ are always available. They are listed here in alphabetical order. Open *file* and return a corresponding :term:`file object`. If the file cannot be opened, an :exc:`OSError` is raised. - *file* is either a string, bytes, or :class:`os.PathLike` object giving the - pathname (absolute or relative to the current working directory) of the file - to be opened or an integer file descriptor of the file to be wrapped. (If a - file descriptor is given, it is closed when the returned I/O object is - closed, unless *closefd* is set to ``False``.) + *file* is a :term:`path-like object` giving the pathname (absolute or + relative to the current working directory) of the file to be opened or an + integer file descriptor of the file to be wrapped. (If a file descriptor is + given, it is closed when the returned I/O object is closed, unless *closefd* + is set to ``False``.) *mode* is an optional string that specifies the mode in which the file is opened. It defaults to ``'r'`` which means open for reading in text mode. diff --git a/Doc/library/os.path.rst b/Doc/library/os.path.rst index bf0dface7e9..406054e5d7a 100644 --- a/Doc/library/os.path.rst +++ b/Doc/library/os.path.rst @@ -61,6 +61,9 @@ the :mod:`glob` module.) platforms, this is equivalent to calling the function :func:`normpath` as follows: ``normpath(join(os.getcwd(), path))``. + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + .. function:: basename(path) @@ -71,6 +74,9 @@ the :mod:`glob` module.) ``'/foo/bar/'`` returns ``'bar'``, the :func:`basename` function returns an empty string (``''``). + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + .. function:: commonpath(paths) @@ -83,6 +89,9 @@ the :mod:`glob` module.) .. versionadded:: 3.5 + .. versionchanged:: 3.6 + Accepts a sequence of :term:`path-like objects `. + .. function:: commonprefix(list) @@ -104,12 +113,18 @@ the :mod:`glob` module.) >>> os.path.commonpath(['/usr/lib', '/usr/local/lib']) '/usr' + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + .. function:: dirname(path) Return the directory name of pathname *path*. This is the first element of the pair returned by passing *path* to the function :func:`split`. + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + .. function:: exists(path) @@ -123,6 +138,9 @@ the :mod:`glob` module.) *path* can now be an integer: ``True`` is returned if it is an open file descriptor, ``False`` otherwise. + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + .. function:: lexists(path) @@ -130,6 +148,9 @@ the :mod:`glob` module.) broken symbolic links. Equivalent to :func:`exists` on platforms lacking :func:`os.lstat`. + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + .. function:: expanduser(path) @@ -151,6 +172,9 @@ the :mod:`glob` module.) If the expansion fails or if the path does not begin with a tilde, the path is returned unchanged. + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + .. function:: expandvars(path) @@ -162,6 +186,9 @@ the :mod:`glob` module.) On Windows, ``%name%`` expansions are supported in addition to ``$name`` and ``${name}``. + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + .. function:: getatime(path) @@ -182,6 +209,9 @@ the :mod:`glob` module.) If :func:`os.stat_float_times` returns ``True``, the result is a floating point number. + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + .. function:: getctime(path) @@ -191,12 +221,18 @@ the :mod:`glob` module.) the :mod:`time` module). Raise :exc:`OSError` if the file does not exist or is inaccessible. + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + .. function:: getsize(path) Return the size, in bytes, of *path*. Raise :exc:`OSError` if the file does not exist or is inaccessible. + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + .. function:: isabs(path) @@ -204,24 +240,36 @@ the :mod:`glob` module.) begins with a slash, on Windows that it begins with a (back)slash after chopping off a potential drive letter. + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + .. function:: isfile(path) Return ``True`` if *path* is an existing regular file. This follows symbolic links, so both :func:`islink` and :func:`isfile` can be true for the same path. + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + .. function:: isdir(path) Return ``True`` if *path* is an existing directory. This follows symbolic links, so both :func:`islink` and :func:`isdir` can be true for the same path. + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + .. function:: islink(path) Return ``True`` if *path* refers to a directory entry that is a symbolic link. Always ``False`` if symbolic links are not supported by the Python runtime. + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + .. function:: ismount(path) @@ -237,6 +285,9 @@ the :mod:`glob` module.) .. versionadded:: 3.4 Support for detecting non-root mount points on Windows. + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + .. function:: join(path, *paths) @@ -255,13 +306,20 @@ the :mod:`glob` module.) ``os.path.join("c:", "foo")`` represents a path relative to the current directory on drive :file:`C:` (:file:`c:foo`), not :file:`c:\\foo`. + .. versionchanged:: 3.6 + Accepts a :term:`path-like object` for *path* and *paths*. + .. function:: normcase(path) Normalize the case of a pathname. On Unix and Mac OS X, this returns the path unchanged; on case-insensitive filesystems, it converts the path to lowercase. On Windows, it also converts forward slashes to backward slashes. - Raise a TypeError if the type of *path* is not ``str`` or ``bytes``. + Raise a TypeError if the type of *path* is not ``str`` or ``bytes`` (directly + or indirectly through the :class:`os.PathLike` interface). + + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. .. function:: normpath(path) @@ -272,12 +330,18 @@ the :mod:`glob` module.) that contains symbolic links. On Windows, it converts forward slashes to backward slashes. To normalize case, use :func:`normcase`. + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + .. function:: realpath(path) Return the canonical path of the specified filename, eliminating any symbolic links encountered in the path (if they are supported by the operating system). + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + .. function:: relpath(path, start=os.curdir) @@ -290,6 +354,9 @@ the :mod:`glob` module.) Availability: Unix, Windows. + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + .. function:: samefile(path1, path2) @@ -305,6 +372,9 @@ the :mod:`glob` module.) .. versionchanged:: 3.4 Windows now uses the same implementation as all other platforms. + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + .. function:: sameopenfile(fp1, fp2) @@ -315,6 +385,9 @@ the :mod:`glob` module.) .. versionchanged:: 3.2 Added Windows support. + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + .. function:: samestat(stat1, stat2) @@ -328,6 +401,9 @@ the :mod:`glob` module.) .. versionchanged:: 3.4 Added Windows support. + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + .. function:: split(path) @@ -341,6 +417,9 @@ the :mod:`glob` module.) (but the strings may differ). Also see the functions :func:`dirname` and :func:`basename`. + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + .. function:: splitdrive(path) @@ -359,6 +438,9 @@ the :mod:`glob` module.) and share, up to but not including the fourth separator. e.g. ``splitdrive("//host/computer/dir")`` returns ``("//host/computer", "/dir")`` + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + .. function:: splitext(path) @@ -367,6 +449,9 @@ the :mod:`glob` module.) period. Leading periods on the basename are ignored; ``splitext('.cshrc')`` returns ``('.cshrc', '')``. + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + .. function:: splitunc(path) diff --git a/Doc/library/os.rst b/Doc/library/os.rst index 5cc5c0a75fe..b73cb250b1b 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -930,6 +930,9 @@ as internal buffering of data. exception, the function now retries the system call instead of raising an :exc:`InterruptedError` exception (see :pep:`475` for the rationale). + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + The following constants are options for the *flags* parameter to the :func:`~os.open` function. They can be combined using the bitwise OR operator ``|``. Some of them are not available on all platforms. For descriptions of @@ -1426,6 +1429,9 @@ features: .. versionchanged:: 3.3 Added the *dir_fd*, *effective_ids*, and *follow_symlinks* parameters. + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + .. data:: F_OK R_OK @@ -1450,6 +1456,9 @@ features: Added support for specifying *path* as a file descriptor on some platforms. + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + .. function:: chflags(path, flags, *, follow_symlinks=True) @@ -1476,6 +1485,9 @@ features: .. versionadded:: 3.3 The *follow_symlinks* argument. + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + .. function:: chmod(path, mode, *, dir_fd=None, follow_symlinks=True) @@ -1517,6 +1529,9 @@ features: Added support for specifying *path* as an open file descriptor, and the *dir_fd* and *follow_symlinks* arguments. + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + .. function:: chown(path, uid, gid, *, dir_fd=None, follow_symlinks=True) @@ -1536,6 +1551,9 @@ features: Added support for specifying an open file descriptor for *path*, and the *dir_fd* and *follow_symlinks* arguments. + .. versionchanged:: 3.6 + Supports a :term:`path-like object`. + .. function:: chroot(path) @@ -1543,6 +1561,9 @@ features: Availability: Unix. + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + .. function:: fchdir(fd) @@ -1571,6 +1592,9 @@ features: Availability: Unix. + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + .. function:: lchmod(path, mode) @@ -1581,6 +1605,8 @@ features: Availability: Unix. + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. .. function:: lchown(path, uid, gid) @@ -1590,6 +1616,9 @@ features: Availability: Unix. + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + .. function:: link(src, dst, *, src_dir_fd=None, dst_dir_fd=None, follow_symlinks=True) @@ -1607,6 +1636,9 @@ features: .. versionadded:: 3.3 Added the *src_dir_fd*, *dst_dir_fd*, and *follow_symlinks* arguments. + .. versionchanged:: 3.6 + Accepts a :term:`path-like object` for *src* and *dst*. + .. function:: listdir(path='.') @@ -1614,8 +1646,9 @@ features: *path*. The list is in arbitrary order, and does not include the special entries ``'.'`` and ``'..'`` even if they are present in the directory. - *path* may be either of type ``str`` or of type ``bytes``. If *path* - is of type ``bytes``, the filenames returned will also be of type ``bytes``; + *path* may be a :term:`path-like object`. If *path* is of type ``bytes`` + (directly or indirectly through the :class:`PathLike` interface), + the filenames returned will also be of type ``bytes``; in all other circumstances, they will be of type ``str``. This function can also support :ref:`specifying a file descriptor @@ -1636,6 +1669,9 @@ features: .. versionadded:: 3.3 Added support for specifying an open file descriptor for *path*. + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + .. function:: lstat(path, \*, dir_fd=None) @@ -1662,6 +1698,9 @@ features: .. versionchanged:: 3.3 Added the *dir_fd* parameter. + .. versionchanged:: 3.6 + Accepts a :term:`path-like object` for *src* and *dst*. + .. function:: mkdir(path, mode=0o777, *, dir_fd=None) @@ -1686,6 +1725,9 @@ features: .. versionadded:: 3.3 The *dir_fd* argument. + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + .. function:: makedirs(name, mode=0o777, exist_ok=False) @@ -1719,6 +1761,9 @@ features: mode of the existing directory. Since this behavior was impossible to implement safely, it was removed in Python 3.4.1. See :issue:`21082`. + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + .. function:: mkfifo(path, mode=0o666, *, dir_fd=None) @@ -1739,6 +1784,9 @@ features: .. versionadded:: 3.3 The *dir_fd* argument. + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + .. function:: mknod(path, mode=0o600, device=0, *, dir_fd=None) @@ -1756,6 +1804,9 @@ features: .. versionadded:: 3.3 The *dir_fd* argument. + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + .. function:: major(device) @@ -1794,6 +1845,9 @@ features: Availability: Unix. + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + .. data:: pathconf_names @@ -1811,9 +1865,10 @@ features: may be converted to an absolute pathname using ``os.path.join(os.path.dirname(path), result)``. - If the *path* is a string object, the result will also be a string object, + If the *path* is a string object (directly or indirectly through a + :class:`PathLike` interface), the result will also be a string object, and the call may raise a UnicodeDecodeError. If the *path* is a bytes - object, the result will be a bytes object. + object (direct or indirectly), the result will be a bytes object. This function can also support :ref:`paths relative to directory descriptors `. @@ -1826,6 +1881,9 @@ features: .. versionadded:: 3.3 The *dir_fd* argument. + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + .. function:: remove(path, *, dir_fd=None) @@ -1844,6 +1902,9 @@ features: .. versionadded:: 3.3 The *dir_fd* argument. + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + .. function:: removedirs(name) @@ -1858,6 +1919,9 @@ features: they are empty. Raises :exc:`OSError` if the leaf directory could not be successfully removed. + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + .. function:: rename(src, dst, *, src_dir_fd=None, dst_dir_fd=None) @@ -1877,6 +1941,9 @@ features: .. versionadded:: 3.3 The *src_dir_fd* and *dst_dir_fd* arguments. + .. versionchanged:: 3.6 + Accepts a :term:`path-like object` for *src* and *dst*. + .. function:: renames(old, new) @@ -1890,6 +1957,9 @@ features: This function can fail with the new directory structure made if you lack permissions needed to remove the leaf directory or file. + .. versionchanged:: 3.6 + Accepts a :term:`path-like object` for *old* and *new*. + .. function:: replace(src, dst, *, src_dir_fd=None, dst_dir_fd=None) @@ -1904,6 +1974,9 @@ features: .. versionadded:: 3.3 + .. versionchanged:: 3.6 + Accepts a :term:`path-like object` for *src* and *dst*. + .. function:: rmdir(path, *, dir_fd=None) @@ -1917,6 +1990,9 @@ features: .. versionadded:: 3.3 The *dir_fd* parameter. + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + .. function:: scandir(path='.') @@ -1935,7 +2011,8 @@ features: always requires a system call on Unix but only requires one for symbolic links on Windows. - On Unix, *path* can be of type :class:`str` or :class:`bytes` (use + On Unix, *path* can be of type :class:`str` or :class:`bytes` (either + directly or indirectly through the :class:`PathLike` interface; use :func:`~os.fsencode` and :func:`~os.fsdecode` to encode and decode :class:`bytes` paths). On Windows, *path* must be of type :class:`str`. On both systems, the type of the :attr:`~os.DirEntry.name` and @@ -1986,6 +2063,8 @@ features: exhausted nor explicitly closed a :exc:`ResourceWarning` will be emitted in its destructor. + The function accepts a :term:`path-like object`. + .. class:: DirEntry @@ -2007,7 +2086,7 @@ features: ``os.DirEntry`` methods and handle as appropriate. To be directly usable as a :term:`path-like object`, ``os.DirEntry`` - implements the :class:`os.PathLike` interface. + implements the :class:`PathLike` interface. Attributes and methods on a ``os.DirEntry`` instance are as follows: @@ -2123,14 +2202,15 @@ features: .. versionadded:: 3.5 .. versionchanged:: 3.6 - Added support for the :class:`os.PathLike` interface. + Added support for the :class:`~os.PathLike` interface. .. function:: stat(path, \*, dir_fd=None, follow_symlinks=True) Get the status of a file or a file descriptor. Perform the equivalent of a :c:func:`stat` system call on the given path. *path* may be specified as - either a string or as an open file descriptor. Return a :class:`stat_result` + either a string -- directly or indirectly through the :class:`PathLike` + interface -- or as an open file descriptor. Return a :class:`stat_result` object. This function normally follows symlinks; to stat a symlink add the argument @@ -2160,6 +2240,9 @@ features: Added the *dir_fd* and *follow_symlinks* arguments, specifying a file descriptor instead of a path. + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + .. class:: stat_result @@ -2381,19 +2464,22 @@ features: This function can support :ref:`specifying a file descriptor `. + Availability: Unix. + .. versionchanged:: 3.2 The :const:`ST_RDONLY` and :const:`ST_NOSUID` constants were added. + .. versionadded:: 3.3 + Added support for specifying an open file descriptor for *path*. + .. versionchanged:: 3.4 The :const:`ST_NODEV`, :const:`ST_NOEXEC`, :const:`ST_SYNCHRONOUS`, :const:`ST_MANDLOCK`, :const:`ST_WRITE`, :const:`ST_APPEND`, :const:`ST_IMMUTABLE`, :const:`ST_NOATIME`, :const:`ST_NODIRATIME`, and :const:`ST_RELATIME` constants were added. - Availability: Unix. - - .. versionadded:: 3.3 - Added support for specifying an open file descriptor for *path*. + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. .. data:: supports_dir_fd @@ -2514,6 +2600,9 @@ features: Added the *dir_fd* argument, and now allow *target_is_directory* on non-Windows platforms. + .. versionchanged:: 3.6 + Accepts a :term:`path-like object` for *src* and *dst*. + .. function:: sync() @@ -2538,6 +2627,10 @@ features: .. versionchanged:: 3.5 Added support for Windows + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + + .. function:: unlink(path, *, dir_fd=None) Remove (delete) the file *path*. This function is semantically @@ -2548,6 +2641,9 @@ features: .. versionadded:: 3.3 The *dir_fd* parameter. + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + .. function:: utime(path, times=None, *[, ns], dir_fd=None, follow_symlinks=True) @@ -2585,6 +2681,9 @@ features: Added support for specifying an open file descriptor for *path*, and the *dir_fd*, *follow_symlinks*, and *ns* parameters. + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + .. function:: walk(top, topdown=True, onerror=None, followlinks=False) @@ -2675,6 +2774,9 @@ features: This function now calls :func:`os.scandir` instead of :func:`os.listdir`, making it faster by reducing the number of calls to :func:`os.stat`. + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + .. function:: fwalk(top='.', topdown=True, onerror=None, *, follow_symlinks=False, dir_fd=None) @@ -2731,6 +2833,9 @@ features: .. versionadded:: 3.3 + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + Linux extended attributes ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -2742,12 +2847,16 @@ These functions are all available on Linux only. .. function:: getxattr(path, attribute, *, follow_symlinks=True) Return the value of the extended filesystem attribute *attribute* for - *path*. *attribute* can be bytes or str. If it is str, it is encoded - with the filesystem encoding. + *path*. *attribute* can be bytes or str (directly or indirectly through the + :class:`PathLike` interface). If it is str, it is encoded with the filesystem + encoding. This function can support :ref:`specifying a file descriptor ` and :ref:`not following symlinks `. + .. versionchanged:: 3.6 + Accepts a :term:`path-like object` fpr *path* and *attribute*. + .. function:: listxattr(path=None, *, follow_symlinks=True) @@ -2759,21 +2868,29 @@ These functions are all available on Linux only. This function can support :ref:`specifying a file descriptor ` and :ref:`not following symlinks `. + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + .. function:: removexattr(path, attribute, *, follow_symlinks=True) Removes the extended filesystem attribute *attribute* from *path*. - *attribute* should be bytes or str. If it is a string, it is encoded + *attribute* should be bytes or str (directly or indirectly through the + :class:`PathLike` interface). If it is a string, it is encoded with the filesystem encoding. This function can support :ref:`specifying a file descriptor ` and :ref:`not following symlinks `. + .. versionchanged:: 3.6 + Accepts a :term:`path-like object` for *path* and *attribute*. + .. function:: setxattr(path, attribute, value, flags=0, *, follow_symlinks=True) Set the extended filesystem attribute *attribute* on *path* to *value*. - *attribute* must be a bytes or str with no embedded NULs. If it is a str, + *attribute* must be a bytes or str with no embedded NULs (directly or + indirectly through the :class:`PathLike` interface). If it is a str, it is encoded with the filesystem encoding. *flags* may be :data:`XATTR_REPLACE` or :data:`XATTR_CREATE`. If :data:`XATTR_REPLACE` is given and the attribute does not exist, ``EEXISTS`` will be raised. @@ -2788,6 +2905,9 @@ These functions are all available on Linux only. A bug in Linux kernel versions less than 2.6.39 caused the flags argument to be ignored on some filesystems. + .. versionchanged:: 3.6 + Accepts a :term:`path-like object` for *path* and *attribute*. + .. data:: XATTR_SIZE_MAX @@ -2889,6 +3009,9 @@ to be ignored. Added support for specifying an open file descriptor for *path* for :func:`execve`. + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + .. function:: _exit(n) Exit the process with status *n*, without calling cleanup handlers, flushing @@ -3199,6 +3322,9 @@ written in Python, such as a mail server's external command delivery program. :func:`spawnve` are not thread-safe on Windows; we advise you to use the :mod:`subprocess` module instead. + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + .. data:: P_NOWAIT P_NOWAITO