https://github.com/python/cpython/commit/85020647c2a8c53dbdea2f6b31c5d5af85ca317d
commit: 85020647c2a8c53dbdea2f6b31c5d5af85ca317d
branch: 3.12
author: Barney Gale <barney.g...@gmail.com>
committer: barneygale <barney.g...@gmail.com>
date: 2024-06-02T20:38:00+01:00
summary:
[3.12] GH-119054: Add "Querying file type and status" section to pathlib docs
(GH-119055) (#119952)
Add a dedicated subsection for `Path.stat()`-related methods, specifically
`stat()`, `lstat()`, `exists()`, `is_*()`, and `samefile()`.
(cherry picked from commit 81d63362302187e5cb838c9a7cd857181142e530)
files:
M Doc/library/pathlib.rst
diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst
index a44c52db5663d4..0115ea8b3eb878 100644
--- a/Doc/library/pathlib.rst
+++ b/Doc/library/pathlib.rst
@@ -790,12 +790,8 @@ bugs or failures in your application)::
NotImplementedError: cannot instantiate 'WindowsPath' on your system
-Methods
-^^^^^^^
-
-Concrete paths provide the following methods in addition to pure paths
-methods. Many of these methods can raise an :exc:`OSError` if a system
-call fails (for example because the path doesn't exist).
+Querying file type and status
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. versionchanged:: 3.8
@@ -807,29 +803,6 @@ call fails (for example because the path doesn't exist).
unrepresentable at the OS level.
-.. classmethod:: Path.cwd()
-
- Return a new path object representing the current directory (as returned
- by :func:`os.getcwd`)::
-
- >>> Path.cwd()
- PosixPath('/home/antoine/pathlib')
-
-
-.. classmethod:: Path.home()
-
- Return a new path object representing the user's home directory (as
- returned by :func:`os.path.expanduser` with ``~`` construct). If the home
- directory can't be resolved, :exc:`RuntimeError` is raised.
-
- ::
-
- >>> Path.home()
- PosixPath('/home/antoine')
-
- .. versionadded:: 3.5
-
-
.. method:: Path.stat(*, follow_symlinks=True)
Return a :class:`os.stat_result` object containing information about this
path, like :func:`os.stat`.
@@ -849,25 +822,12 @@ call fails (for example because the path doesn't exist).
.. versionchanged:: 3.10
The *follow_symlinks* parameter was added.
-.. method:: Path.chmod(mode, *, follow_symlinks=True)
-
- Change the file mode and permissions, like :func:`os.chmod`.
-
- This method normally follows symlinks. Some Unix flavours support changing
- permissions on the symlink itself; on these platforms you may add the
- argument ``follow_symlinks=False``, or use :meth:`~Path.lchmod`.
- ::
+.. method:: Path.lstat()
- >>> p = Path('setup.py')
- >>> p.stat().st_mode
- 33277
- >>> p.chmod(0o444)
- >>> p.stat().st_mode
- 33060
+ Like :meth:`Path.stat` but, if the path points to a symbolic link, return
+ the symbolic link's information rather than its target's.
- .. versionchanged:: 3.10
- The *follow_symlinks* parameter was added.
.. method:: Path.exists(*, follow_symlinks=True)
@@ -890,69 +850,14 @@ call fails (for example because the path doesn't exist).
.. versionchanged:: 3.12
The *follow_symlinks* parameter was added.
-.. method:: Path.expanduser()
-
- Return a new path with expanded ``~`` and ``~user`` constructs,
- as returned by :meth:`os.path.expanduser`. If a home directory can't be
- resolved, :exc:`RuntimeError` is raised.
-
- ::
-
- >>> p = PosixPath('~/films/Monty Python')
- >>> p.expanduser()
- PosixPath('/home/eric/films/Monty Python')
-
- .. versionadded:: 3.5
-
-
-.. method:: Path.glob(pattern, *, case_sensitive=None)
-
- Glob the given relative *pattern* in the directory represented by this path,
- yielding all matching files (of any kind)::
-
- >>> sorted(Path('.').glob('*.py'))
- [PosixPath('pathlib.py'), PosixPath('setup.py'),
PosixPath('test_pathlib.py')]
- >>> sorted(Path('.').glob('*/*.py'))
- [PosixPath('docs/conf.py')]
-
- Patterns are the same as for :mod:`fnmatch`, with the addition of "``**``"
- which means "this directory and all subdirectories, recursively". In other
- words, it enables recursive globbing::
-
- >>> sorted(Path('.').glob('**/*.py'))
- [PosixPath('build/lib/pathlib.py'),
- PosixPath('docs/conf.py'),
- PosixPath('pathlib.py'),
- PosixPath('setup.py'),
- PosixPath('test_pathlib.py')]
-
- This method calls :meth:`Path.is_dir` on the top-level directory and
- propagates any :exc:`OSError` exception that is raised. Subsequent
- :exc:`OSError` exceptions from scanning directories are suppressed.
-
- By default, or when the *case_sensitive* keyword-only argument is set to
- ``None``, this method matches paths using platform-specific casing rules:
- typically, case-sensitive on POSIX, and case-insensitive on Windows.
- Set *case_sensitive* to ``True`` or ``False`` to override this behaviour.
-
- .. note::
- Using the "``**``" pattern in large directory trees may consume
- an inordinate amount of time.
-
- .. audit-event:: pathlib.Path.glob self,pattern pathlib.Path.glob
-
- .. versionchanged:: 3.11
- Return only directories if *pattern* ends with a pathname components
- separator (:data:`~os.sep` or :data:`~os.altsep`).
-
- .. versionchanged:: 3.12
- The *case_sensitive* parameter was added.
+.. method:: Path.is_file()
-.. method:: Path.group()
+ Return ``True`` if the path points to a regular file (or a symbolic link
+ pointing to a regular file), ``False`` if it points to another kind of file.
- Return the name of the group owning the file. :exc:`KeyError` is raised
- if the file's gid isn't found in the system database.
+ ``False`` is also returned if the path doesn't exist or is a broken symlink;
+ other errors (such as permission errors) are propagated.
.. method:: Path.is_dir()
@@ -964,13 +869,12 @@ call fails (for example because the path doesn't exist).
other errors (such as permission errors) are propagated.
-.. method:: Path.is_file()
+.. method:: Path.is_symlink()
- Return ``True`` if the path points to a regular file (or a symbolic link
- pointing to a regular file), ``False`` if it points to another kind of file.
+ Return ``True`` if the path points to a symbolic link, ``False`` otherwise.
- ``False`` is also returned if the path doesn't exist or is a broken symlink;
- other errors (such as permission errors) are propagated.
+ ``False`` is also returned if the path doesn't exist; other errors (such
+ as permission errors) are propagated.
.. method:: Path.is_junction()
@@ -998,14 +902,6 @@ call fails (for example because the path doesn't exist).
Windows support was added.
-.. method:: Path.is_symlink()
-
- Return ``True`` if the path points to a symbolic link, ``False`` otherwise.
-
- ``False`` is also returned if the path doesn't exist; other errors (such
- as permission errors) are propagated.
-
-
.. method:: Path.is_socket()
Return ``True`` if the path points to a Unix socket (or a symbolic link
@@ -1042,6 +938,143 @@ call fails (for example because the path doesn't exist).
other errors (such as permission errors) are propagated.
+.. method:: Path.samefile(other_path)
+
+ Return whether this path points to the same file as *other_path*, which
+ can be either a Path object, or a string. The semantics are similar
+ to :func:`os.path.samefile` and :func:`os.path.samestat`.
+
+ An :exc:`OSError` can be raised if either file cannot be accessed for some
+ reason.
+
+ ::
+
+ >>> p = Path('spam')
+ >>> q = Path('eggs')
+ >>> p.samefile(q)
+ False
+ >>> p.samefile('spam')
+ True
+
+ .. versionadded:: 3.5
+
+
+Other methods
+^^^^^^^^^^^^^
+
+Many of these methods can raise an :exc:`OSError` if a system call fails (for
+example because the path doesn't exist).
+
+
+.. classmethod:: Path.cwd()
+
+ Return a new path object representing the current directory (as returned
+ by :func:`os.getcwd`)::
+
+ >>> Path.cwd()
+ PosixPath('/home/antoine/pathlib')
+
+
+.. classmethod:: Path.home()
+
+ Return a new path object representing the user's home directory (as
+ returned by :func:`os.path.expanduser` with ``~`` construct). If the home
+ directory can't be resolved, :exc:`RuntimeError` is raised.
+
+ ::
+
+ >>> Path.home()
+ PosixPath('/home/antoine')
+
+ .. versionadded:: 3.5
+
+
+.. method:: Path.chmod(mode, *, follow_symlinks=True)
+
+ Change the file mode and permissions, like :func:`os.chmod`.
+
+ This method normally follows symlinks. Some Unix flavours support changing
+ permissions on the symlink itself; on these platforms you may add the
+ argument ``follow_symlinks=False``, or use :meth:`~Path.lchmod`.
+
+ ::
+
+ >>> p = Path('setup.py')
+ >>> p.stat().st_mode
+ 33277
+ >>> p.chmod(0o444)
+ >>> p.stat().st_mode
+ 33060
+
+ .. versionchanged:: 3.10
+ The *follow_symlinks* parameter was added.
+
+
+.. method:: Path.expanduser()
+
+ Return a new path with expanded ``~`` and ``~user`` constructs,
+ as returned by :meth:`os.path.expanduser`. If a home directory can't be
+ resolved, :exc:`RuntimeError` is raised.
+
+ ::
+
+ >>> p = PosixPath('~/films/Monty Python')
+ >>> p.expanduser()
+ PosixPath('/home/eric/films/Monty Python')
+
+ .. versionadded:: 3.5
+
+
+.. method:: Path.glob(pattern, *, case_sensitive=None)
+
+ Glob the given relative *pattern* in the directory represented by this path,
+ yielding all matching files (of any kind)::
+
+ >>> sorted(Path('.').glob('*.py'))
+ [PosixPath('pathlib.py'), PosixPath('setup.py'),
PosixPath('test_pathlib.py')]
+ >>> sorted(Path('.').glob('*/*.py'))
+ [PosixPath('docs/conf.py')]
+
+ Patterns are the same as for :mod:`fnmatch`, with the addition of "``**``"
+ which means "this directory and all subdirectories, recursively". In other
+ words, it enables recursive globbing::
+
+ >>> sorted(Path('.').glob('**/*.py'))
+ [PosixPath('build/lib/pathlib.py'),
+ PosixPath('docs/conf.py'),
+ PosixPath('pathlib.py'),
+ PosixPath('setup.py'),
+ PosixPath('test_pathlib.py')]
+
+ This method calls :meth:`Path.is_dir` on the top-level directory and
+ propagates any :exc:`OSError` exception that is raised. Subsequent
+ :exc:`OSError` exceptions from scanning directories are suppressed.
+
+ By default, or when the *case_sensitive* keyword-only argument is set to
+ ``None``, this method matches paths using platform-specific casing rules:
+ typically, case-sensitive on POSIX, and case-insensitive on Windows.
+ Set *case_sensitive* to ``True`` or ``False`` to override this behaviour.
+
+ .. note::
+ Using the "``**``" pattern in large directory trees may consume
+ an inordinate amount of time.
+
+ .. audit-event:: pathlib.Path.glob self,pattern pathlib.Path.glob
+
+ .. versionchanged:: 3.11
+ Return only directories if *pattern* ends with a pathname components
+ separator (:data:`~os.sep` or :data:`~os.altsep`).
+
+ .. versionchanged:: 3.12
+ The *case_sensitive* parameter was added.
+
+
+.. method:: Path.group()
+
+ Return the name of the group owning the file. :exc:`KeyError` is raised
+ if the file's gid isn't found in the system database.
+
+
.. method:: Path.iterdir()
When the path points to a directory, yield path objects of the directory
@@ -1164,12 +1197,6 @@ call fails (for example because the path doesn't exist).
symbolic link's mode is changed rather than its target's.
-.. method:: Path.lstat()
-
- Like :meth:`Path.stat` but, if the path points to a symbolic link, return
- the symbolic link's information rather than its target's.
-
-
.. method:: Path.mkdir(mode=0o777, parents=False, exist_ok=False)
Create a new directory at this given path. If *mode* is given, it is
@@ -1367,27 +1394,6 @@ call fails (for example because the path doesn't exist).
Remove this directory. The directory must be empty.
-.. method:: Path.samefile(other_path)
-
- Return whether this path points to the same file as *other_path*, which
- can be either a Path object, or a string. The semantics are similar
- to :func:`os.path.samefile` and :func:`os.path.samestat`.
-
- An :exc:`OSError` can be raised if either file cannot be accessed for some
- reason.
-
- ::
-
- >>> p = Path('spam')
- >>> q = Path('eggs')
- >>> p.samefile(q)
- False
- >>> p.samefile('spam')
- True
-
- .. versionadded:: 3.5
-
-
.. method:: Path.symlink_to(target, target_is_directory=False)
Make this path a symbolic link pointing to *target*.
_______________________________________________
Python-checkins mailing list -- python-checkins@python.org
To unsubscribe send an email to python-checkins-le...@python.org
https://mail.python.org/mailman3/lists/python-checkins.python.org/
Member address: arch...@mail-archive.com
