Skip to content

Commit

Permalink
[3.12] GH-119054: Add "Reading directories" section to pathlib docs (G…
Browse files Browse the repository at this point in the history 
…H-119956) (#120184)

Add a dedicated subsection for `Path.iterdir()`-related methods,
specifically `iterdir()`, `glob()`, `rglob()` and `walk()`.

(cherry picked from commit 14e1506)

Co-authored-by: Jelle Zijlstra <[email protected]>
  • Loading branch information
@barneygale @JelleZijlstra
barneygale and JelleZijlstra authored Jun 7, 2024
1 parent 0e7b4d2 commit 59224b8
Showing 1 changed file with 114 additions and 107 deletions.
221 changes: 114 additions & 107 deletions Doc/library/pathlib.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -789,6 +789,9 @@ bugs or failures in your application)::
% (cls.__name__,))
NotImplementedError: cannot instantiate 'WindowsPath' on your system

Some concrete path methods can raise an :exc:`OSError` if a system call fails
(for example because the path doesn't exist).


Querying file type and status
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Expand Down Expand Up @@ -1040,71 +1043,32 @@ Reading and writing files
.. 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
Reading directories
^^^^^^^^^^^^^^^^^^^

.. method:: Path.iterdir()

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

::
When the path points to a directory, yield path objects of the directory
contents::

>>> p = PosixPath('~/films/Monty Python')
>>> p.expanduser()
PosixPath('/home/eric/films/Monty Python')
>>> p = Path('docs')
>>> for child in p.iterdir(): child
...
PosixPath('docs/conf.py')
PosixPath('docs/_templates')
PosixPath('docs/make.bat')
PosixPath('docs/index.rst')
PosixPath('docs/_build')
PosixPath('docs/_static')
PosixPath('docs/Makefile')

.. versionadded:: 3.5
The children are yielded in arbitrary order, and the special entries
``'.'`` and ``'..'`` are not included. If a file is removed from or added
to the directory after creating the iterator, it is unspecified whether
a path object for that file is included.

If the path is not a directory or otherwise inaccessible, :exc:`OSError` is
raised.

.. method:: Path.glob(pattern, *, case_sensitive=None)

Expand Down Expand Up @@ -1150,32 +1114,33 @@ example because the path doesn't exist).
The *case_sensitive* parameter was added.


.. method:: Path.group()
.. method:: Path.rglob(pattern, *, case_sensitive=None)

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.
Glob the given relative *pattern* recursively. This is like calling
:func:`Path.glob` with "``**/``" added in front of the *pattern*, where
*patterns* are the same as for :mod:`fnmatch`::

>>> sorted(Path().rglob("*.py"))
[PosixPath('build/lib/pathlib.py'),
PosixPath('docs/conf.py'),
PosixPath('pathlib.py'),
PosixPath('setup.py'),
PosixPath('test_pathlib.py')]

.. method:: Path.iterdir()
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.

When the path points to a directory, yield path objects of the directory
contents::
.. audit-event:: pathlib.Path.rglob self,pattern pathlib.Path.rglob

>>> p = Path('docs')
>>> for child in p.iterdir(): child
...
PosixPath('docs/conf.py')
PosixPath('docs/_templates')
PosixPath('docs/make.bat')
PosixPath('docs/index.rst')
PosixPath('docs/_build')
PosixPath('docs/_static')
PosixPath('docs/Makefile')
.. 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.

The children are yielded in arbitrary order, and the special entries
``'.'`` and ``'..'`` are not included. If a file is removed from or added
to the directory after creating the iterator, whether a path object for
that file be included is unspecified.

.. method:: Path.walk(top_down=True, on_error=None, follow_symlinks=False)

Expand Down Expand Up @@ -1272,6 +1237,75 @@ example because the path doesn't exist).

.. versionadded:: 3.12


Other methods
^^^^^^^^^^^^^

.. 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.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.lchmod(mode)

Like :meth:`Path.chmod` but, if the path points to a symbolic link, the
Expand Down Expand Up @@ -1401,33 +1435,6 @@ example because the path doesn't exist).
.. versionchanged:: 3.6
The *strict* parameter was added (pre-3.6 behavior is strict).

.. method:: Path.rglob(pattern, *, case_sensitive=None)

Glob the given relative *pattern* recursively. This is like calling
:func:`Path.glob` with "``**/``" added in front of the *pattern*, where
*patterns* are the same as for :mod:`fnmatch`::

>>> sorted(Path().rglob("*.py"))
[PosixPath('build/lib/pathlib.py'),
PosixPath('docs/conf.py'),
PosixPath('pathlib.py'),
PosixPath('setup.py'),
PosixPath('test_pathlib.py')]

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.

.. audit-event:: pathlib.Path.rglob self,pattern pathlib.Path.rglob

.. 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.rmdir()

Expand Down

0 comments on commit 59224b8

Please sign in to comment.