mirror of
https://github.com/python/cpython
synced 2024-10-15 00:28:04 +00:00
GH-119054: Add "Reading directories" section to pathlib docs (#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>
This commit is contained in:
parent
5bdc87b885
commit
14e1506a6d
|
@ -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
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
@ -1151,69 +1154,32 @@ Reading and writing files
|
|||
.. versionadded:: 3.5
|
||||
|
||||
|
||||
Other methods
|
||||
^^^^^^^^^^^^^
|
||||
Reading directories
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Some of these methods can raise an :exc:`OSError` if a system call fails (for
|
||||
example because the path doesn't exist).
|
||||
.. method:: Path.iterdir()
|
||||
|
||||
When the path points to a directory, yield path objects of the directory
|
||||
contents::
|
||||
|
||||
.. classmethod:: Path.cwd()
|
||||
>>> 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')
|
||||
|
||||
Return a new path object representing the current directory (as returned
|
||||
by :func:`os.getcwd`)::
|
||||
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.
|
||||
|
||||
>>> 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
|
||||
If the path is not a directory or otherwise inaccessible, :exc:`OSError` is
|
||||
raised.
|
||||
|
||||
|
||||
.. method:: Path.glob(pattern, *, case_sensitive=None, recurse_symlinks=False)
|
||||
|
@ -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
|
||||
|
@ -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
|
||||
|
|
Loading…
Reference in a new issue