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()`.
  • Loading branch information
@barneygale @estyxx
barneygale authored and estyxx committed Jul 17, 2024
1 parent df7a921 commit 3c12835
Showing 1 changed file with 171 additions and 167 deletions.
338 changes: 171 additions & 167 deletions Doc/library/pathlib.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -808,8 +808,8 @@ bugs or failures in your application)::
UnsupportedOperation: cannot instantiate 'WindowsPath' on your system


File URIs
^^^^^^^^^
Parsing and generating URIs
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Concrete path objects can be created from, and represented as, 'file' URIs
conforming to :rfc:`8089`.
Expand Down Expand Up @@ -869,12 +869,8 @@ conforming to :rfc:`8089`.
it strictly impure.


Methods
^^^^^^^

Concrete paths provide the following methods in addition to pure paths
methods. Some 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 @@ -895,29 +891,6 @@ call fails (for example because the path doesn't exist).
status without suppressing exceptions.


.. 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 @@ -937,25 +910,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 @@ -980,6 +940,170 @@ call fails (for example because the path doesn't exist).
.. versionchanged:: 3.12
The *follow_symlinks* parameter was added.


.. method:: Path.is_file(*, follow_symlinks=True)

Return ``True`` if the path points to a regular file. ``False`` will be
returned if the path is invalid, inaccessible or missing, or if it points
to something other than a regular file. Use :meth:`Path.stat` to
distinguish between these cases.

This method normally follows symlinks; to exclude symlinks, add the
argument ``follow_symlinks=False``.

.. versionchanged:: 3.13
The *follow_symlinks* parameter was added.


.. method:: Path.is_dir(*, follow_symlinks=True)

Return ``True`` if the path points to a directory. ``False`` will be
returned if the path is invalid, inaccessible or missing, or if it points
to something other than a directory. Use :meth:`Path.stat` to distinguish
between these cases.

This method normally follows symlinks; to exclude symlinks to directories,
add the argument ``follow_symlinks=False``.

.. versionchanged:: 3.13
The *follow_symlinks* parameter was added.


.. method:: Path.is_symlink()

Return ``True`` if the path points to a symbolic link, even if that symlink
is broken. ``False`` will be returned if the path is invalid, inaccessible
or missing, or if it points to something other than a symbolic link. Use
:meth:`Path.stat` to distinguish between these cases.


.. method:: Path.is_junction()

Return ``True`` if the path points to a junction, and ``False`` for any other
type of file. Currently only Windows supports junctions.

.. versionadded:: 3.12


.. method:: Path.is_mount()

Return ``True`` if the path is a :dfn:`mount point`: a point in a
file system where a different file system has been mounted. On POSIX, the
function checks whether *path*'s parent, :file:`path/..`, is on a different
device than *path*, or whether :file:`path/..` and *path* point to the same
i-node on the same device --- this should detect mount points for all Unix
and POSIX variants. On Windows, a mount point is considered to be a drive
letter root (e.g. ``c:\``), a UNC share (e.g. ``\\server\share``), or a
mounted filesystem directory.

.. versionadded:: 3.7

.. versionchanged:: 3.12
Windows support was added.

.. method:: Path.is_socket()

Return ``True`` if the path points to a Unix socket. ``False`` will be
returned if the path is invalid, inaccessible or missing, or if it points
to something other than a Unix socket. Use :meth:`Path.stat` to
distinguish between these cases.


.. method:: Path.is_fifo()

Return ``True`` if the path points to a FIFO. ``False`` will be returned if
the path is invalid, inaccessible or missing, or if it points to something
other than a FIFO. Use :meth:`Path.stat` to distinguish between these
cases.


.. method:: Path.is_block_device()

Return ``True`` if the path points to a block device. ``False`` will be
returned if the path is invalid, inaccessible or missing, or if it points
to something other than a block device. Use :meth:`Path.stat` to
distinguish between these cases.


.. method:: Path.is_char_device()

Return ``True`` if the path points to a character device. ``False`` will be
returned if the path is invalid, inaccessible or missing, or if it points
to something other than a character device. Use :meth:`Path.stat` to
distinguish between these cases.


.. 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
^^^^^^^^^^^^^

Some 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,
Expand Down Expand Up @@ -1076,99 +1200,6 @@ call fails (for example because the path doesn't exist).
The *follow_symlinks* parameter was added.


.. method:: Path.is_dir(*, follow_symlinks=True)

Return ``True`` if the path points to a directory. ``False`` will be
returned if the path is invalid, inaccessible or missing, or if it points
to something other than a directory. Use :meth:`Path.stat` to distinguish
between these cases.

This method normally follows symlinks; to exclude symlinks to directories,
add the argument ``follow_symlinks=False``.

.. versionchanged:: 3.13
The *follow_symlinks* parameter was added.


.. method:: Path.is_file(*, follow_symlinks=True)

Return ``True`` if the path points to a regular file. ``False`` will be
returned if the path is invalid, inaccessible or missing, or if it points
to something other than a regular file. Use :meth:`Path.stat` to
distinguish between these cases.

This method normally follows symlinks; to exclude symlinks, add the
argument ``follow_symlinks=False``.

.. versionchanged:: 3.13
The *follow_symlinks* parameter was added.


.. method:: Path.is_junction()

Return ``True`` if the path points to a junction, and ``False`` for any other
type of file. Currently only Windows supports junctions.

.. versionadded:: 3.12


.. method:: Path.is_mount()

Return ``True`` if the path is a :dfn:`mount point`: a point in a
file system where a different file system has been mounted. On POSIX, the
function checks whether *path*'s parent, :file:`path/..`, is on a different
device than *path*, or whether :file:`path/..` and *path* point to the same
i-node on the same device --- this should detect mount points for all Unix
and POSIX variants. On Windows, a mount point is considered to be a drive
letter root (e.g. ``c:\``), a UNC share (e.g. ``\\server\share``), or a
mounted filesystem directory.

.. versionadded:: 3.7

.. versionchanged:: 3.12
Windows support was added.


.. method:: Path.is_symlink()

Return ``True`` if the path points to a symbolic link, even if that symlink
is broken. ``False`` will be returned if the path is invalid, inaccessible
or missing, or if it points to something other than a symbolic link. Use
:meth:`Path.stat` to distinguish between these cases.


.. method:: Path.is_socket()

Return ``True`` if the path points to a Unix socket. ``False`` will be
returned if the path is invalid, inaccessible or missing, or if it points
to something other than a Unix socket. Use :meth:`Path.stat` to
distinguish between these cases.


.. method:: Path.is_fifo()

Return ``True`` if the path points to a FIFO. ``False`` will be returned if
the path is invalid, inaccessible or missing, or if it points to something
other than a FIFO. Use :meth:`Path.stat` to distinguish between these
cases.


.. method:: Path.is_block_device()

Return ``True`` if the path points to a block device. ``False`` will be
returned if the path is invalid, inaccessible or missing, or if it points
to something other than a block device. Use :meth:`Path.stat` to
distinguish between these cases.


.. method:: Path.is_char_device()

Return ``True`` if the path points to a character device. ``False`` will be
returned if the path is invalid, inaccessible or missing, or if it points
to something other than a character device. Use :meth:`Path.stat` to
distinguish between these cases.


.. method:: Path.iterdir()

When the path points to a directory, yield path objects of the directory
Expand Down Expand Up @@ -1291,12 +1322,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 @@ -1486,27 +1511,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 3c12835

Please sign in to comment.