diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst index b6fb36554f7cec..806b7a3b842808 100644 --- a/Doc/library/pathlib.rst +++ b/Doc/library/pathlib.rst @@ -93,6 +93,128 @@ Opening a file:: '#!/bin/bash\n' +Summary +------- + +====================================================================================================== ================== +**Exceptions** +-------------------------------------------------------------------------------------------------------------------------- +:exc:`UnsupportedOperation` Raised when an unsupported operation is called on a path object + +**Pure paths** +-------------------------------------------------------------------------------------------------------------------------- +:class:`PurePath(*pathsegments) ` Represents the system's path flavour +:class:`PurePosixPath(*pathsegments) ` Represents non-Windows filesystem paths +:class:`PureWindowsPath(*pathsegments) ` Represents Windows filesystem paths + +**Pure path attributes** +-------------------------------------------------------------------------------------------------------------------------- +:attr:`PurePath.parts` Tuple of the path's various components +:attr:`PurePath.parser` Implementation of the :mod:`os.path` module used for low-level path operations +:attr:`PurePath.drive` Drive letter or name +:attr:`PurePath.root` Root part +:attr:`PurePath.anchor` Concatenation of the drive and root +:attr:`PurePath.parents` Logical ancestors of the path +:attr:`PurePath.parent` Logical parent of the path +:attr:`PurePath.name` Final path component +:attr:`PurePath.suffix` Last dot-separated portion of the final component +:attr:`PurePath.suffixes` List of the path's suffixes +:attr:`PurePath.stem` Final path component without its suffix + +**Pure path methods** +-------------------------------------------------------------------------------------------------------------------------- +:meth:`PurePath.as_posix` String representation of the path with forward slashes (``/``) +:meth:`PurePath.is_absolute` Whether the path is absolute or not +:meth:`PurePath.is_relative_to(other) ` Whether the path is relative to the *other* path +:meth:`PurePath.is_reserved` Whether the path is considered reserved under Windows (deprecated) +:meth:`PurePath.joinpath(*pathsegments) ` Combine the path with each of the given *pathsegments* +:meth:`PurePath.full_match(pattern, case_sensitive) ` Match against the provided glob-style pattern +:meth:`PurePath.match(pattern, case_sensitive) ` Match against the provided non-recursive glob-style pattern +:meth:`PurePath.relative_to(other, walk_up) ` Version of this path relative to the *other* path +:meth:`PurePath.with_name(name) ` New path with the :attr:`PurePath.name` changed +:meth:`PurePath.with_stem(stem) ` New path with the :attr:`PurePath.stem` changed +:meth:`PurePath.with_suffix(suffix) ` New path with the :attr:`PurePath.suffix` changed +:meth:`PurePath.with_segments(*pathsegments) ` New path by combining the given *pathsegments* + +**Concrete paths** +-------------------------------------------------------------------------------------------------------------------------- +:class:`Path(*pathsegments) ` Represents concrete paths of the system's path flavour +:class:`PosixPath(*pathsegments) ` Represents concrete non-Windows filesystem paths +:class:`WindowsPath(*pathsegments) ` Represents concrete Windows filesystem paths + +**Parsing and generating URIs** +-------------------------------------------------------------------------------------------------------------------------- +:meth:`Path.from_uri(uri) ` New path from parsing a 'file' URI +:meth:`Path.as_uri` Represent the path as a 'file' URI + +**Expanding and resolving paths** +-------------------------------------------------------------------------------------------------------------------------- +:meth:`Path.home` New path representing the user's home directory +:meth:`Path.expanduser` New path with expanded ``~`` and ``~user`` constructs +:meth:`Path.cwd` New path representing the current directory +:meth:`Path.absolute` Make the path absolute, without normalization or resolving symlinks +:meth:`Path.resolve(strict) ` Make the path absolute, resolving any symlinks +:meth:`Path.readlink` Path to which the symbolic link points + +**Querying file type and status** +-------------------------------------------------------------------------------------------------------------------------- +:meth:`Path.stat(follow_symlinks) ` :class:`os.stat_result` object containing information about this path +:meth:`Path.lstat` Like :meth:`Path.stat`, but return the symbolic link's information rather than its target's +:meth:`Path.exists(follow_symlinks) ` Whether the path points to an existing file or directory +:meth:`Path.is_file(follow_symlinks) ` Whether the path points to a regular file +:meth:`Path.is_dir(follow_symlinks) ` Whether the path points to a directory +:meth:`Path.is_symlink` Whether the path points to a symbolic link +:meth:`Path.is_junction` Whether the path points to a junction +:meth:`Path.is_mount` Whether the path is a mount point +:meth:`Path.is_socket` Whether the path points to a Unix socket +:meth:`Path.is_fifo` Whether the path points to a FIFO +:meth:`Path.is_block_device` Whether the path points to a block device +:meth:`Path.is_char_device` Whether the path points to a character device +:meth:`Path.samefile(other_path) ` Whether this path points to the same file as *other_path* + +**Reading and writing files** +-------------------------------------------------------------------------------------------------------------------------- +:meth:`Path.open(mode, buffering, encoding, errors, newline) ` Open the file pointed to by the path +:meth:`Path.read_text(encoding, errors, newline) ` Decoded contents of the file as a string +:meth:`Path.read_bytes` Binary contents of the file as a bytes object +:meth:`Path.write_text(data, encoding, errors, newline) ` Write *data* to the file pointed to in text mode +:meth:`Path.write_bytes(data) ` Write *data* to the file pointed to in bytes mode + +**Reading directories** +-------------------------------------------------------------------------------------------------------------------------- +:meth:`Path.iterdir` Yield path objects of the directory contents +:meth:`Path.scandir` Iterator of :class:`os.DirEntry` objects corresponding to entries in the directory +:meth:`Path.glob(pattern, case_sensitive, recurse_symlinks) ` Glob the given relative *pattern* in the directory represented by this path, yielding all matching files +:meth:`Path.rglob(pattern, case_sensitive, recurse_symlinks) ` Glob the given relative *pattern* recursively +:meth:`Path.walk(top_down, on_error, follow_symlinks) ` Generate the file names by walking the directory tree, yielding 3-tuples of ``(dirpath, dirnames, filenames)`` + +**Creating files and directories** +-------------------------------------------------------------------------------------------------------------------------- +:meth:`Path.touch(mode, exist_ok) ` Create a file at this given path +:meth:`Path.mkdir(mode, parents, exist_ok) ` Create a new directory at this given path +:meth:`Path.symlink_to(target, target_is_directory) ` Make this path a symbolic link pointing to *target* +:meth:`Path.hardlink_to(target) ` Make this path a hard link to the same file as *target* + +**Copying, moving and deleting** +-------------------------------------------------------------------------------------------------------------------------- +:meth:`Path.copy(target, follow_symlinks, dirs_exist_ok, preserve_metadata) ` Copy this file or directory tree to the given *target* +:meth:`Path.copy_into(target_dir, follow_symlinks, dirs_exist_ok, preserve_metadata) ` Copy this file or directory tree into the given *target_dir* +:meth:`Path.rename(target) ` Rename this file or directory to the given *target* +:meth:`Path.replace(target) ` Rename this file or directory to the given *target*, unconditionally replacing an existing file or empty directory +:meth:`Path.move(target) ` Move this file or directory tree to the given *target* +:meth:`Path.move_into(target_dir) ` Move this file or directory tree into the given *target_dir* +:meth:`Path.unlink(missing_ok) ` Remove this file or symbolic link +:meth:`Path.rmdir` Remove this empty directory + +**Permissions and ownership** +-------------------------------------------------------------------------------------------------------------------------- +:meth:`Path.owner(follow_symlinks) ` Return the name of the user owning the file +:meth:`Path.group(follow_symlinks) ` Return the name of the group owning the file +:meth:`Path.chmod(mode, follow_symlinks) ` Change the file mode and permissions +:meth:`Path.lchmod(mode) ` Change the file mode and permissions, but the symbolic link's mode is changed rather than its target's + +====================================================================================================== ================== + Exceptions ----------