From c9171633f02d686f3a2145cf3bddfbfa46048cd7 Mon Sep 17 00:00:00 2001 From: Joseph Martinot-Lagarde Date: Sun, 3 Nov 2024 02:28:45 +0100 Subject: [PATCH 1/3] Doc: Summary table for pathlib --- Doc/library/pathlib.rst | 122 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 122 insertions(+) diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst index b6fb36554f7cec..b5881fd5f23afe 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:`Path.name` changed +:meth:`PurePath.with_stem(stem) ` New path with the :attr:`Path.stem` changed +:meth:`PurePath.with_suffix(suffix) ` New path with the :attr:`Path.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 ---------- From 6399a9c9e3bdfa410836d5638870360c76770bc5 Mon Sep 17 00:00:00 2001 From: Joseph Martinot-Lagarde Date: Sun, 3 Nov 2024 02:50:17 +0100 Subject: [PATCH 2/3] Fix wrong attribute links --- Doc/library/pathlib.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst index b5881fd5f23afe..806b7a3b842808 100644 --- a/Doc/library/pathlib.rst +++ b/Doc/library/pathlib.rst @@ -131,9 +131,9 @@ Summary :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:`Path.name` changed -:meth:`PurePath.with_stem(stem) ` New path with the :attr:`Path.stem` changed -:meth:`PurePath.with_suffix(suffix) ` New path with the :attr:`Path.suffix` changed +: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** From ab7fc3a22f741ad6ab38e94cf202e942d7a7008b Mon Sep 17 00:00:00 2001 From: Ned Batchelder Date: Fri, 13 Dec 2024 07:09:04 -0500 Subject: [PATCH 3/3] Doc: a more compact pathlib summary table - Removed class names and parameters from the summary - Used parentheses uniformly to indicate methods - Shortened some of the summary descriptions - Move "exceptions" to the end --- Doc/library/pathlib.rst | 172 ++++++++++++++++++++-------------------- 1 file changed, 86 insertions(+), 86 deletions(-) diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst index 806b7a3b842808..25a8b13aa6c7cd 100644 --- a/Doc/library/pathlib.rst +++ b/Doc/library/pathlib.rst @@ -97,121 +97,121 @@ Summary ------- ====================================================================================================== ================== -**Exceptions** --------------------------------------------------------------------------------------------------------------------------- -:exc:`UnsupportedOperation` Raised when an unsupported operation is called on a path object - -**Pure paths** +**Pure path classes** -------------------------------------------------------------------------------------------------------------------------- -:class:`PurePath(*pathsegments) ` Represents the system's path flavour -:class:`PurePosixPath(*pathsegments) ` Represents non-Windows filesystem paths -:class:`PureWindowsPath(*pathsegments) ` Represents Windows filesystem paths +:class:`PurePath() ` Represents the system's path flavour +:class:`PurePosixPath() ` Represents non-Windows filesystem paths +:class:`PureWindowsPath() ` Represents Windows filesystem paths -**Pure path attributes** +**PurePath 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** +: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:`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** +: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(*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 +: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:`Path.from_uri(uri) ` New path from parsing a 'file' URI -:meth:`Path.as_uri` Represent the path as a 'file' URI +: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:`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 +: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:`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* +: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:`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 +: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:`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)`` +: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:`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* +: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:`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 +: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:`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 +: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 ====================================================================================================== ==================