mirror of
https://github.com/python/cpython
synced 2024-10-15 00:44:42 +00:00
[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 81d6336230)
This commit is contained in:
Barney Gale
GitHub
parent
c8de0ec7b9
commit
85020647c2
|
|
@ -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,6 +803,169 @@ call fails (for example because the path doesn't exist).
|
|||
unrepresentable at the OS level.
|
||||
|
||||
|
||||
.. method:: Path.stat(*, follow_symlinks=True)
|
||||
|
||||
Return a :class:`os.stat_result` object containing information about this path, like :func:`os.stat`.
|
||||
The result is looked up at each call to this method.
|
||||
|
||||
This method normally follows symlinks; to stat a symlink add the argument
|
||||
``follow_symlinks=False``, or use :meth:`~Path.lstat`.
|
||||
|
||||
::
|
||||
|
||||
>>> p = Path('setup.py')
|
||||
>>> p.stat().st_size
|
||||
956
|
||||
>>> p.stat().st_mtime
|
||||
1327883547.852554
|
||||
|
||||
.. versionchanged:: 3.10
|
||||
The *follow_symlinks* parameter was added.
|
||||
|
||||
|
||||
.. 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.exists(*, follow_symlinks=True)
|
||||
|
||||
Return ``True`` if the path points to an existing file or directory.
|
||||
|
||||
This method normally follows symlinks; to check if a symlink exists, add
|
||||
the argument ``follow_symlinks=False``.
|
||||
|
||||
::
|
||||
|
||||
>>> Path('.').exists()
|
||||
True
|
||||
>>> Path('setup.py').exists()
|
||||
True
|
||||
>>> Path('/etc').exists()
|
||||
True
|
||||
>>> Path('nonexistentfile').exists()
|
||||
False
|
||||
|
||||
.. versionchanged:: 3.12
|
||||
The *follow_symlinks* parameter was added.
|
||||
|
||||
|
||||
.. method:: Path.is_file()
|
||||
|
||||
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.
|
||||
|
||||
``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()
|
||||
|
||||
Return ``True`` if the path points to a directory (or a symbolic link
|
||||
pointing to a directory), ``False`` if it points to another kind of file.
|
||||
|
||||
``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_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_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 (or a symbolic link
|
||||
pointing to a Unix socket), ``False`` if it points to another kind of file.
|
||||
|
||||
``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_fifo()
|
||||
|
||||
Return ``True`` if the path points to a FIFO (or a symbolic link
|
||||
pointing to a FIFO), ``False`` if it points to another kind of file.
|
||||
|
||||
``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_block_device()
|
||||
|
||||
Return ``True`` if the path points to a block device (or a symbolic link
|
||||
pointing to a block device), ``False`` if it points to another kind of file.
|
||||
|
||||
``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_char_device()
|
||||
|
||||
Return ``True`` if the path points to a character device (or a symbolic link
|
||||
pointing to a character device), ``False`` if it points to another kind of file.
|
||||
|
||||
``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.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
|
||||
|
|
@ -830,25 +989,6 @@ call fails (for example because the path doesn't exist).
|
|||
.. 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`.
|
||||
The result is looked up at each call to this method.
|
||||
|
||||
This method normally follows symlinks; to stat a symlink add the argument
|
||||
``follow_symlinks=False``, or use :meth:`~Path.lstat`.
|
||||
|
||||
::
|
||||
|
||||
>>> p = Path('setup.py')
|
||||
>>> p.stat().st_size
|
||||
956
|
||||
>>> p.stat().st_mtime
|
||||
1327883547.852554
|
||||
|
||||
.. 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`.
|
||||
|
|
@ -869,26 +1009,6 @@ call fails (for example because the path doesn't exist).
|
|||
.. versionchanged:: 3.10
|
||||
The *follow_symlinks* parameter was added.
|
||||
|
||||
.. method:: Path.exists(*, follow_symlinks=True)
|
||||
|
||||
Return ``True`` if the path points to an existing file or directory.
|
||||
|
||||
This method normally follows symlinks; to check if a symlink exists, add
|
||||
the argument ``follow_symlinks=False``.
|
||||
|
||||
::
|
||||
|
||||
>>> Path('.').exists()
|
||||
True
|
||||
>>> Path('setup.py').exists()
|
||||
True
|
||||
>>> Path('/etc').exists()
|
||||
True
|
||||
>>> Path('nonexistentfile').exists()
|
||||
False
|
||||
|
||||
.. versionchanged:: 3.12
|
||||
The *follow_symlinks* parameter was added.
|
||||
|
||||
.. method:: Path.expanduser()
|
||||
|
||||
|
|
@ -955,93 +1075,6 @@ call fails (for example because the path doesn't exist).
|
|||
if the file's gid isn't found in the system database.
|
||||
|
||||
|
||||
.. method:: Path.is_dir()
|
||||
|
||||
Return ``True`` if the path points to a directory (or a symbolic link
|
||||
pointing to a directory), ``False`` if it points to another kind of file.
|
||||
|
||||
``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_file()
|
||||
|
||||
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.
|
||||
|
||||
``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_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, ``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
|
||||
pointing to a Unix socket), ``False`` if it points to another kind of file.
|
||||
|
||||
``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_fifo()
|
||||
|
||||
Return ``True`` if the path points to a FIFO (or a symbolic link
|
||||
pointing to a FIFO), ``False`` if it points to another kind of file.
|
||||
|
||||
``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_block_device()
|
||||
|
||||
Return ``True`` if the path points to a block device (or a symbolic link
|
||||
pointing to a block device), ``False`` if it points to another kind of file.
|
||||
|
||||
``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_char_device()
|
||||
|
||||
Return ``True`` if the path points to a character device (or a symbolic link
|
||||
pointing to a character device), ``False`` if it points to another kind of file.
|
||||
|
||||
``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.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*.
|
||||
|
|
|
|||
Loading…
Reference in a new issue