Skip to content
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

GH-119054: Add "Querying file type and status" section to pathlib docs #119055

Merged
merged 3 commits into from
May 24, 2024
Merged

GH-119054: Add "Querying file type and status" section to pathlib docs #119055

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
e3f4a0c
GH-119054: Add "Querying file type and status" section to pathlib docs
barneygale May 14, 2024
e8fd4cf
Swap is_file() and is_dir()
barneygale May 24, 2024
40bd888
Merge branch 'main' into gh-119054-stat
barneygale May 24, 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
338 changes: 171 additions & 167 deletions Doc/library/pathlib.rst
View file
Open in desktop
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
Loading