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)
``'/foo/bar/'`` returns ``'bar'``, the :func:`basename` function returns an
empty string (``''``).
+ .. versionchanged:: 3.6
+ Accepts a :term:`path-like object`.
+
.. function:: commonpath(paths)
.. versionadded:: 3.5
+ .. versionchanged:: 3.6
+ Accepts a sequence of :term:`path-like objects <path-like object>`.
+
.. function:: commonprefix(list)
>>> 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)
*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)
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)
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)
On Windows, ``%name%`` expansions are supported in addition to ``$name`` and
``${name}``.
+ .. versionchanged:: 3.6
+ Accepts a :term:`path-like object`.
+
.. function:: getatime(path)
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)
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)
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)
.. 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)
``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)
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)
Availability: Unix, Windows.
+ .. versionchanged:: 3.6
+ Accepts a :term:`path-like object`.
+
.. function:: samefile(path1, path2)
.. 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)
.. versionchanged:: 3.2
Added Windows support.
+ .. versionchanged:: 3.6
+ Accepts a :term:`path-like object`.
+
.. function:: samestat(stat1, stat2)
.. versionchanged:: 3.4
Added Windows support.
+ .. versionchanged:: 3.6
+ Accepts a :term:`path-like object`.
+
.. function:: split(path)
(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)
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)
period. Leading periods on the basename are ignored; ``splitext('.cshrc')``
returns ``('.cshrc', '')``.
+ .. versionchanged:: 3.6
+ Accepts a :term:`path-like object`.
+
.. function:: splitunc(path)
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
.. 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
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)
.. 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)
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)
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)
Availability: Unix.
+ .. versionchanged:: 3.6
+ Accepts a :term:`path-like object`.
+
.. function:: fchdir(fd)
Availability: Unix.
+ .. versionchanged:: 3.6
+ Accepts a :term:`path-like object`.
+
.. function:: lchmod(path, mode)
Availability: Unix.
+ .. versionchanged:: 3.6
+ Accepts a :term:`path-like object`.
.. function:: lchown(path, uid, gid)
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)
.. 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='.')
*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
.. 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)
.. 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)
.. versionadded:: 3.3
The *dir_fd* argument.
+ .. versionchanged:: 3.6
+ Accepts a :term:`path-like object`.
+
.. function:: makedirs(name, mode=0o777, exist_ok=False)
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)
.. 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)
.. versionadded:: 3.3
The *dir_fd* argument.
+ .. versionchanged:: 3.6
+ Accepts a :term:`path-like object`.
+
.. function:: major(device)
Availability: Unix.
+ .. versionchanged:: 3.6
+ Accepts a :term:`path-like object`.
+
.. data:: pathconf_names
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
<dir_fd>`.
.. versionadded:: 3.3
The *dir_fd* argument.
+ .. versionchanged:: 3.6
+ Accepts a :term:`path-like object`.
+
.. function:: remove(path, *, dir_fd=None)
.. versionadded:: 3.3
The *dir_fd* argument.
+ .. versionchanged:: 3.6
+ Accepts a :term:`path-like object`.
+
.. function:: removedirs(name)
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)
.. 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)
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)
.. versionadded:: 3.3
+ .. versionchanged:: 3.6
+ Accepts a :term:`path-like object` for *src* and *dst*.
+
.. function:: rmdir(path, *, dir_fd=None)
.. versionadded:: 3.3
The *dir_fd* parameter.
+ .. versionchanged:: 3.6
+ Accepts a :term:`path-like object`.
+
.. function:: scandir(path='.')
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
exhausted nor explicitly closed a :exc:`ResourceWarning` will be emitted
in its destructor.
+ The function accepts a :term:`path-like object`.
+
.. class:: DirEntry
``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:
.. 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
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
This function can support :ref:`specifying a file descriptor <path_fd>`.
+ 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
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()
.. 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
.. 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)
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)
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)
.. versionadded:: 3.3
+ .. versionchanged:: 3.6
+ Accepts a :term:`path-like object`.
+
Linux extended attributes
~~~~~~~~~~~~~~~~~~~~~~~~~
.. 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 <path_fd>` and
:ref:`not following symlinks <follow_symlinks>`.
+ .. versionchanged:: 3.6
+ Accepts a :term:`path-like object` fpr *path* and *attribute*.
+
.. function:: listxattr(path=None, *, follow_symlinks=True)
This function can support :ref:`specifying a file descriptor <path_fd>` and
:ref:`not following symlinks <follow_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 <path_fd>` and
:ref:`not following symlinks <follow_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.
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
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
: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
projects / python / commitdiff