From c9a65830706e9c8ba08310ff2672bf8fc87e4762 Mon Sep 17 00:00:00 2001 From: barneygale Date: Sun, 2 Jun 2024 21:03:40 +0100 Subject: [PATCH 1/3] GH-119054: Add "Listing directories" section to pathlib docs Add a dedicated subsection for `Path.iterdir()`-related methods, specifically `iterdir()`, `glob()`, `rglob()` and `walk()`. --- Doc/library/pathlib.rst | 197 ++++++++++++++++++++-------------------- 1 file changed, 101 insertions(+), 96 deletions(-) diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst index f37bb33321fa53..d38c16bdddcc52 100644 --- a/Doc/library/pathlib.rst +++ b/Doc/library/pathlib.rst @@ -1151,69 +1151,29 @@ 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. - -.. method:: Path.expanduser() +Listing directories +^^^^^^^^^^^^^^^^^^^ - 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. +.. method:: Path.iterdir() - :: + 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, whether a path object for + that file be included is unspecified. .. method:: Path.glob(pattern, *, case_sensitive=None, recurse_symlinks=False) @@ -1281,43 +1241,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 +1336,88 @@ example because the path doesn't exist). .. versionadded:: 3.12 + +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, + 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 From a6a92b574b2628076fddcae10c3f3a4788903d80 Mon Sep 17 00:00:00 2001 From: Barney Gale Date: Fri, 7 Jun 2024 00:09:46 +0100 Subject: [PATCH 2/3] Update Doc/library/pathlib.rst Co-authored-by: Jelle Zijlstra --- Doc/library/pathlib.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst index d38c16bdddcc52..dbe8001fb95b12 100644 --- a/Doc/library/pathlib.rst +++ b/Doc/library/pathlib.rst @@ -1172,8 +1172,8 @@ Listing directories 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. + to the directory after creating the iterator, it is unspecified whether + a path object for that file is included. .. method:: Path.glob(pattern, *, case_sensitive=None, recurse_symlinks=False) From 4a49d91387d93ab7e9f1976f0a65cfe5889e24eb Mon Sep 17 00:00:00 2001 From: barneygale Date: Fri, 7 Jun 2024 00:11:22 +0100 Subject: [PATCH 3/3] Address review feedback --- Doc/library/pathlib.rst | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst index dbe8001fb95b12..b7ab44706a0160 100644 --- a/Doc/library/pathlib.rst +++ b/Doc/library/pathlib.rst @@ -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,7 +1154,7 @@ Reading and writing files .. versionadded:: 3.5 -Listing directories +Reading directories ^^^^^^^^^^^^^^^^^^^ .. method:: Path.iterdir() @@ -1175,6 +1178,9 @@ Listing directories 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, recurse_symlinks=False) @@ -1340,10 +1346,6 @@ Listing directories 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