Skip to content

[3.12] GH-119054: Add "Querying file type and status" section to pathlib docs (GH-119055) #119952

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jun 2, 2024
+151 −145
Merged

[3.12] GH-119054: Add "Querying file type and status" section to pathlib docs (GH-119055) #119952

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7925f40
GH-119054: Add "Querying file type and status" section to pathlib doc…
barneygale May 24, 2024
878a8f1
[3.12] GH-119054: Add "Querying file type and status" section to path…
barneygale Jun 2, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
296 changes: 151 additions & 145 deletions Doc/library/pathlib.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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`.
Expand All @@ -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)

Expand All @@ -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()
Expand All @@ -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()
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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*.
Expand Down
Loading