Skip to content

Commit

Permalink
pythonGH-119054: Add "Reading directories" section to pathlib docs (p…
Browse files Browse the repository at this point in the history
…ython#119956)

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

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
  • Loading branch information
barneygale and JelleZijlstra committed Jun 6, 2024
1 parent 5bdc87b commit 14e1506
Showing 1 changed file with 102 additions and 95 deletions.
197 changes: 102 additions & 95 deletions Doc/library/pathlib.rst
Original file line number Diff line number Diff line change
Expand Up @@ -820,6 +820,9 @@ bugs or failures in your application)::
% (cls.__name__,))
UnsupportedOperation: 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).


Parsing and generating URIs
^^^^^^^^^^^^^^^^^^^^^^^^^^^
Expand Down Expand Up @@ -1151,69 +1154,32 @@ Reading and writing files
.. 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.
Reading directories
^^^^^^^^^^^^^^^^^^^

.. method:: Path.expanduser()
.. method:: Path.iterdir()

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 = 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')

>>> p = PosixPath('~/films/Monty Python')
>>> p.expanduser()
PosixPath('/home/eric/films/Monty Python')
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.

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


.. method:: Path.glob(pattern, *, case_sensitive=None, recurse_symlinks=False)
Expand Down Expand Up @@ -1281,43 +1247,6 @@ example because the path doesn't exist).
The *pattern* parameter accepts a :term:`path-like object`.


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

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.

This method normally follows symlinks; to get the group of the symlink, add
the argument ``follow_symlinks=False``.

.. versionchanged:: 3.13
Raises :exc:`UnsupportedOperation` if the :mod:`grp` module is not
available. In previous versions, :exc:`NotImplementedError` was raised.

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


.. method:: Path.iterdir()

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

>>> 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')

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)

Generate the file names in a directory tree by walking the tree
Expand Down Expand Up @@ -1413,6 +1342,84 @@ 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(*, follow_symlinks=True)

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.

This method normally follows symlinks; to get the group of the symlink, add
the argument ``follow_symlinks=False``.

.. versionchanged:: 3.13
Raises :exc:`UnsupportedOperation` if the :mod:`grp` module is not
available. In previous versions, :exc:`NotImplementedError` was raised.

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


.. method:: Path.lchmod(mode)

Like :meth:`Path.chmod` but, if the path points to a symbolic link, the
Expand Down

0 comments on commit 14e1506

Please sign in to comment.