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