Skip to content

Commit

Permalink
pythonGH-119054: Add "Querying file type and status" section to pathl…
Browse files Browse the repository at this point in the history 
…ib docs (python#119055)

Add a dedicated subsection for `Path.stat()`-related methods, specifically
`stat()`, `lstat()`, `exists()`, `is_*()`, and `samefile()`.

(cherry picked from commit 81d6336)
  • Loading branch information
@barneygale
barneygale committed Jun 2, 2024
1 parent c8de0ec commit 7925f40
Showing 1 changed file with 151 additions and 145 deletions.
296 changes: 151 additions & 145 deletions Doc/library/pathlib.rst
View file
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

0 comments on commit 7925f40

Please sign in to comment.