From db927eaa2bd79fc3ecb4458da67b4de52d603992 Mon Sep 17 00:00:00 2001 From: barneygale Date: Sat, 13 Jan 2024 18:04:33 +0000 Subject: [PATCH 01/16] GH-101112: Add "pattern language" section to pathlib docs Explain the `match()` / `glob()` / `rglob()` pattern language in its own section. Move `rglob()` documentation under `glob()` and reduce duplicated text. --- Doc/library/pathlib.rst | 88 ++++++++++--------- ...-01-13-18-05-25.gh-issue-110112.ae3z6t.rst | 1 + 2 files changed, 49 insertions(+), 40 deletions(-) create mode 100644 Misc/NEWS.d/next/Documentation/2024-01-13-18-05-25.gh-issue-110112.ae3z6t.rst diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst index 60791725c2323d..967c783294ac1a 100644 --- a/Doc/library/pathlib.rst +++ b/Doc/library/pathlib.rst @@ -973,11 +973,6 @@ call fails (for example because the path doesn't exist). [PosixPath('pathlib.py'), PosixPath('setup.py'), PosixPath('test_pathlib.py')] >>> sorted(Path('.').glob('*/*.py')) [PosixPath('docs/conf.py')] - - Patterns are the same as for :mod:`fnmatch`, with the addition of "``**``" - which means "this directory and all subdirectories, recursively". In other - words, it enables recursive globbing:: - >>> sorted(Path('.').glob('**/*.py')) [PosixPath('build/lib/pathlib.py'), PosixPath('docs/conf.py'), @@ -985,6 +980,9 @@ call fails (for example because the path doesn't exist). PosixPath('setup.py'), PosixPath('test_pathlib.py')] + .. seealso:: + :ref:`pattern-language` documentation. + .. note:: Using the "``**``" pattern in large directory trees may consume an inordinate amount of time. @@ -1020,6 +1018,24 @@ call fails (for example because the path doesn't exist). future Python release, patterns with this ending will match both files and directories. Add a trailing slash to match only directories. + +.. method:: Path.rglob(pattern, *, case_sensitive=None, follow_symlinks=None) + + Glob the given relative *pattern* recursively. This is exactly like + calling :func:`Path.glob` with "``**/``" added in front of the *pattern*. + + .. seealso:: + :ref:`pattern-language` and :meth:`Path.glob` documentation. + + .. audit-event:: pathlib.Path.rglob self,pattern pathlib.Path.rglob + + .. versionchanged:: 3.12 + The *case_sensitive* parameter was added. + + .. versionchanged:: 3.13 + The *follow_symlinks* parameter was added. + + .. method:: Path.group(*, follow_symlinks=True) Return the name of the group owning the file. :exc:`KeyError` is raised @@ -1447,41 +1463,6 @@ call fails (for example because the path doesn't exist). strict mode, and no exception is raised in non-strict mode. In previous versions, :exc:`RuntimeError` is raised no matter the value of *strict*. -.. method:: Path.rglob(pattern, *, case_sensitive=None, follow_symlinks=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. - - By default, or when the *follow_symlinks* keyword-only argument is set to - ``None``, this method follows symlinks except when expanding "``**``" - wildcards. Set *follow_symlinks* to ``True`` to always follow symlinks, or - ``False`` to treat all symlinks as files. - - .. 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. - - .. versionchanged:: 3.13 - The *follow_symlinks* parameter was added. - .. method:: Path.rmdir() Remove this directory. The directory must be empty. @@ -1608,6 +1589,33 @@ call fails (for example because the path doesn't exist). .. versionchanged:: 3.10 The *newline* parameter was added. + +.. _pattern-language: + +Pattern language +---------------- + +:meth:`PurePath.match`, :meth:`Path.glob` and :meth:`Path.rglob` accept +patterns with shell-style wildcards. + +The "``**``" wildcard matches any number of file or directory segments. In +other words, it enabled recursive globbing. If "``**``" occurs in any position +other than a full pattern segment, :exc:`ValueError` is raised. + +The "``*``" wildcard matches precisely one file or directory segment when it +occurs as a full pattern segment, or any number of non-separator characters +when it occurs elsewhere. + +The "``?``" wildcard matches a single non-separator character. Character +ranges such as "``[seq]``" and "``[!seq]``" match a single character within or +without the range. + +If the pattern ends with a path separator, only directories are matched. + +For a literal match, wrap the meta-characters in brackets. +For example, ``"[?]"`` matches the character ``"?"``. + + Correspondence to tools in the :mod:`os` module ----------------------------------------------- diff --git a/Misc/NEWS.d/next/Documentation/2024-01-13-18-05-25.gh-issue-110112.ae3z6t.rst b/Misc/NEWS.d/next/Documentation/2024-01-13-18-05-25.gh-issue-110112.ae3z6t.rst new file mode 100644 index 00000000000000..443ea48c337063 --- /dev/null +++ b/Misc/NEWS.d/next/Documentation/2024-01-13-18-05-25.gh-issue-110112.ae3z6t.rst @@ -0,0 +1 @@ +Document :mod:`pathlib` pattern language in its own subsection. From fbe11f3f14f58670553aec49d0a7f8aa80802680 Mon Sep 17 00:00:00 2001 From: barneygale Date: Tue, 16 Jan 2024 01:08:43 +0000 Subject: [PATCH 02/16] Delete news entry --- .../Documentation/2024-01-13-18-05-25.gh-issue-110112.ae3z6t.rst | 1 - 1 file changed, 1 deletion(-) delete mode 100644 Misc/NEWS.d/next/Documentation/2024-01-13-18-05-25.gh-issue-110112.ae3z6t.rst diff --git a/Misc/NEWS.d/next/Documentation/2024-01-13-18-05-25.gh-issue-110112.ae3z6t.rst b/Misc/NEWS.d/next/Documentation/2024-01-13-18-05-25.gh-issue-110112.ae3z6t.rst deleted file mode 100644 index 443ea48c337063..00000000000000 --- a/Misc/NEWS.d/next/Documentation/2024-01-13-18-05-25.gh-issue-110112.ae3z6t.rst +++ /dev/null @@ -1 +0,0 @@ -Document :mod:`pathlib` pattern language in its own subsection. From aa94135f98d03ff969ede55e028dd1922ef713d5 Mon Sep 17 00:00:00 2001 From: barneygale Date: Fri, 26 Jan 2024 01:24:27 +0000 Subject: [PATCH 03/16] Simplify presentation. --- Doc/library/pathlib.rst | 31 +++++++++++++++---------------- 1 file changed, 15 insertions(+), 16 deletions(-) diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst index 967c783294ac1a..d9e4f973646239 100644 --- a/Doc/library/pathlib.rst +++ b/Doc/library/pathlib.rst @@ -1595,22 +1595,21 @@ call fails (for example because the path doesn't exist). Pattern language ---------------- -:meth:`PurePath.match`, :meth:`Path.glob` and :meth:`Path.rglob` accept -patterns with shell-style wildcards. - -The "``**``" wildcard matches any number of file or directory segments. In -other words, it enabled recursive globbing. If "``**``" occurs in any position -other than a full pattern segment, :exc:`ValueError` is raised. - -The "``*``" wildcard matches precisely one file or directory segment when it -occurs as a full pattern segment, or any number of non-separator characters -when it occurs elsewhere. - -The "``?``" wildcard matches a single non-separator character. Character -ranges such as "``[seq]``" and "``[!seq]``" match a single character within or -without the range. - -If the pattern ends with a path separator, only directories are matched. +The following wildcards are supported in patterns for +:meth:`~PurePath.full_match`, :meth:`~Path.glob` and :meth:`~Path.rglob`: + +"``**``" (standalone segment) + Matches any number of file or directory segments. +"``*``" (standalone segment) + Matches one non-empty file or directory segment. +"``*``" (otherwise) + Matches any number of non-separator characters. +"``?``" + Matches one non-separator character. +"``[seq]``" + Matches one character in *seq*. +"``[!seq]``" + Matches one character not in *seq*. For a literal match, wrap the meta-characters in brackets. For example, ``"[?]"`` matches the character ``"?"``. From 9fe2866c22a8328b3708ec80ccb67e804400e9be Mon Sep 17 00:00:00 2001 From: barneygale Date: Fri, 26 Jan 2024 01:52:05 +0000 Subject: [PATCH 04/16] Convert to table, add examples. --- Doc/library/pathlib.rst | 32 ++++++++++++++++++++------------ 1 file changed, 20 insertions(+), 12 deletions(-) diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst index 1d0ca65ac626ef..3825863a54826c 100644 --- a/Doc/library/pathlib.rst +++ b/Doc/library/pathlib.rst @@ -1634,22 +1634,30 @@ Pattern language The following wildcards are supported in patterns for :meth:`~PurePath.full_match`, :meth:`~Path.glob` and :meth:`~Path.rglob`: -"``**``" (standalone segment) - Matches any number of file or directory segments. -"``*``" (standalone segment) - Matches one non-empty file or directory segment. -"``*``" (otherwise) - Matches any number of non-separator characters. -"``?``" - Matches one non-separator character. -"``[seq]``" - Matches one character in *seq*. -"``[!seq]``" - Matches one character not in *seq*. +========================= =========================================== +Wildcard Matches +========================= =========================================== +"``**``" (full segment) Any number of file or directory segments. +"``*``" (full segment) One file or directory segment. +"``*``" (otherwise) Any number of non-separator characters. +"``?``" One non-separator character. +"``[seq]``" One character in *seq*. +"``[!seq]``" One character not in *seq*. +========================= =========================================== For a literal match, wrap the meta-characters in brackets. For example, ``"[?]"`` matches the character ``"?"``. +The "``**``" wildcard enables recursive globbing: + +========================= =========================================== +Pattern Meaning +========================= =========================================== +``"**/*"`` Any path with at least one segment. +``"**/*.py"`` Any path with a final segment ending ``".py"``. +``"assets/**"`` Any path starting with ``"assets/"``. +``"assets/**/*"`` Any path starting with ``"assets/"``, excluding ``"assets/"`` itself. + Correspondence to tools in the :mod:`os` module ----------------------------------------------- From 42a75b821c223ad64972e2780730b0bcc2f1eb94 Mon Sep 17 00:00:00 2001 From: barneygale Date: Fri, 26 Jan 2024 01:54:23 +0000 Subject: [PATCH 05/16] Fix broken table. --- Doc/library/pathlib.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst index 3825863a54826c..58af35897095df 100644 --- a/Doc/library/pathlib.rst +++ b/Doc/library/pathlib.rst @@ -1657,6 +1657,7 @@ Pattern Meaning ``"**/*.py"`` Any path with a final segment ending ``".py"``. ``"assets/**"`` Any path starting with ``"assets/"``. ``"assets/**/*"`` Any path starting with ``"assets/"``, excluding ``"assets/"`` itself. +========================= =========================================== Correspondence to tools in the :mod:`os` module From 44face07277a774f2c0a9abe1c6618954dbe6e01 Mon Sep 17 00:00:00 2001 From: barneygale Date: Fri, 26 Jan 2024 02:09:56 +0000 Subject: [PATCH 06/16] Final tweaks --- Doc/library/pathlib.rst | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst index 58af35897095df..d4d662a7f318af 100644 --- a/Doc/library/pathlib.rst +++ b/Doc/library/pathlib.rst @@ -1005,14 +1005,6 @@ call fails (for example because the path doesn't exist). .. seealso:: :ref:`pattern-language` documentation. - .. note:: - Using the "``**``" pattern in large directory trees may consume - an inordinate amount of time. - - .. tip:: - Set *follow_symlinks* to ``True`` or ``False`` to improve performance - of recursive globbing. - This method calls :meth:`Path.is_dir` on the top-level directory and propagates any :exc:`OSError` exception that is raised. Subsequent :exc:`OSError` exceptions from scanning directories are suppressed. @@ -1027,6 +1019,10 @@ call fails (for example because the path doesn't exist). wildcards. Set *follow_symlinks* to ``True`` to always follow symlinks, or ``False`` to treat all symlinks as files. + .. tip:: + Set *follow_symlinks* to ``True`` or ``False`` to improve performance + of recursive globbing. + .. audit-event:: pathlib.Path.glob self,pattern pathlib.Path.glob .. versionchanged:: 3.11 @@ -1645,20 +1641,24 @@ Wildcard Matches "``[!seq]``" One character not in *seq*. ========================= =========================================== -For a literal match, wrap the meta-characters in brackets. -For example, ``"[?]"`` matches the character ``"?"``. - -The "``**``" wildcard enables recursive globbing: +The "``**``" wildcard enables recursive globbing. A few examples: ========================= =========================================== Pattern Meaning ========================= =========================================== -``"**/*"`` Any path with at least one segment. -``"**/*.py"`` Any path with a final segment ending ``".py"``. -``"assets/**"`` Any path starting with ``"assets/"``. -``"assets/**/*"`` Any path starting with ``"assets/"``, excluding ``"assets/"`` itself. +"``**/*``" Any path with at least one segment. +"``**/*.py``" Any path with a final segment ending "``.py``". +"``assets/**``" Any path starting with "``assets/``". +"``assets/**/*``" Any path starting with "``assets/``", excluding "``assets/``" itself. ========================= =========================================== +.. note:: + Globbing with the "``**``" wildcard in large directory trees may consume + an inordinate amount of time. + +For a literal match, wrap the meta-characters in brackets. +For example, ``"[?]"`` matches the character ``"?"``. + Correspondence to tools in the :mod:`os` module ----------------------------------------------- From 23d4a3f8c3cfaa706dc18ce65de58437d282fba7 Mon Sep 17 00:00:00 2001 From: barneygale Date: Sat, 27 Jan 2024 20:13:30 +0000 Subject: [PATCH 07/16] Reword note on `**`, move paragraph on escaping wildcards up. --- Doc/library/pathlib.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst index d4d662a7f318af..7b93e82c188604 100644 --- a/Doc/library/pathlib.rst +++ b/Doc/library/pathlib.rst @@ -1641,6 +1641,9 @@ Wildcard Matches "``[!seq]``" One character not in *seq*. ========================= =========================================== +For a literal match, wrap the meta-characters in brackets. +For example, ``"[?]"`` matches the character ``"?"``. + The "``**``" wildcard enables recursive globbing. A few examples: ========================= =========================================== @@ -1653,11 +1656,8 @@ Pattern Meaning ========================= =========================================== .. note:: - Globbing with the "``**``" wildcard in large directory trees may consume - an inordinate amount of time. - -For a literal match, wrap the meta-characters in brackets. -For example, ``"[?]"`` matches the character ``"?"``. + Globbing with the "``**``" wildcard visits every directory in the tree. + Large directory trees may take a long time to search. Correspondence to tools in the :mod:`os` module From 406cf4d8096898f32b015f5db3c870fef4b4466c Mon Sep 17 00:00:00 2001 From: barneygale Date: Tue, 30 Jan 2024 19:41:46 +0000 Subject: [PATCH 08/16] Explain trailing slash handling. --- Doc/library/pathlib.rst | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst index 7b93e82c188604..01ee02f9f792e9 100644 --- a/Doc/library/pathlib.rst +++ b/Doc/library/pathlib.rst @@ -1659,6 +1659,14 @@ Pattern Meaning Globbing with the "``**``" wildcard visits every directory in the tree. Large directory trees may take a long time to search. +In :meth:`Path.glob` and :meth:`~Path.rglob`, a trailing slash may be added to +the pattern to match only directories. + +.. note:: + This module normally removes trailing slashes. Paths returned from + :meth:`Path.glob` and :meth:`~Path.rglob` don't include any trailing slash + given in the pattern. :meth:`PurePath.full_match` ignores trailing slashes. + Correspondence to tools in the :mod:`os` module ----------------------------------------------- From b60970b34a3468daacf9de96e267b38d9ceab8b9 Mon Sep 17 00:00:00 2001 From: barneygale Date: Tue, 30 Jan 2024 19:57:47 +0000 Subject: [PATCH 09/16] Move language change notices into new section. --- Doc/library/pathlib.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst index bc7619a36efae8..f7228dc520d31b 100644 --- a/Doc/library/pathlib.rst +++ b/Doc/library/pathlib.rst @@ -1024,20 +1024,12 @@ call fails (for example because the path doesn't exist). .. audit-event:: pathlib.Path.glob self,pattern pathlib.Path.glob - .. 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. .. versionchanged:: 3.13 The *follow_symlinks* parameter was added. - .. versionchanged:: 3.13 - Return files and directories if *pattern* ends with "``**``". In - previous versions, only directories were returned. - .. versionchanged:: 3.13 The *pattern* parameter accepts a :term:`path-like object`. @@ -1657,6 +1649,10 @@ Pattern Meaning Globbing with the "``**``" wildcard visits every directory in the tree. Large directory trees may take a long time to search. +.. versionchanged:: 3.13 + Globbing with a pattern that ends with "``**``" returns both files and + directories. In previous versions, only directories were returned. + In :meth:`Path.glob` and :meth:`~Path.rglob`, a trailing slash may be added to the pattern to match only directories. @@ -1665,6 +1661,10 @@ the pattern to match only directories. :meth:`Path.glob` and :meth:`~Path.rglob` don't include any trailing slash given in the pattern. :meth:`PurePath.full_match` ignores trailing slashes. +.. versionchanged:: 3.11 + Globbing with a pattern that ends with a pathname components separator + (:data:`~os.sep` or :data:`~os.altsep`) returns only directories. + Correspondence to tools in the :mod:`os` module ----------------------------------------------- From 7caf2473d26c2facc8752de9f2b39118fdd23c4e Mon Sep 17 00:00:00 2001 From: barneygale Date: Tue, 30 Jan 2024 23:08:23 +0000 Subject: [PATCH 10/16] Soften note about trailing slashes. --- Doc/library/pathlib.rst | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst index f7228dc520d31b..6ae2007e5c309f 100644 --- a/Doc/library/pathlib.rst +++ b/Doc/library/pathlib.rst @@ -1654,12 +1654,8 @@ Pattern Meaning directories. In previous versions, only directories were returned. In :meth:`Path.glob` and :meth:`~Path.rglob`, a trailing slash may be added to -the pattern to match only directories. - -.. note:: - This module normally removes trailing slashes. Paths returned from - :meth:`Path.glob` and :meth:`~Path.rglob` don't include any trailing slash - given in the pattern. :meth:`PurePath.full_match` ignores trailing slashes. +the pattern to match only directories. Like all :class:`Path` objects, the +returned directories do not have a trailing slash. .. versionchanged:: 3.11 Globbing with a pattern that ends with a pathname components separator From 5311f45d75a615795c3bf20eefc00fce6b273cbc Mon Sep 17 00:00:00 2001 From: barneygale Date: Sat, 10 Feb 2024 19:43:02 +0000 Subject: [PATCH 11/16] Use definition list for wildcards, similar to `re` docs. --- Doc/library/pathlib.rst | 22 ++++++++++++---------- 1 file changed, 12 insertions(+), 10 deletions(-) diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst index 6ae2007e5c309f..7c8096e6771b91 100644 --- a/Doc/library/pathlib.rst +++ b/Doc/library/pathlib.rst @@ -1620,16 +1620,18 @@ Pattern language The following wildcards are supported in patterns for :meth:`~PurePath.full_match`, :meth:`~Path.glob` and :meth:`~Path.rglob`: -========================= =========================================== -Wildcard Matches -========================= =========================================== -"``**``" (full segment) Any number of file or directory segments. -"``*``" (full segment) One file or directory segment. -"``*``" (otherwise) Any number of non-separator characters. -"``?``" One non-separator character. -"``[seq]``" One character in *seq*. -"``[!seq]``" One character not in *seq*. -========================= =========================================== +``**`` (full segment) + Matches any number of file or directory segments. +``*`` (full segment) + Matches one file or directory segment. +``*`` (otherwise) + Matches any number of non-separator characters. +``?`` + Matches one non-separator character. +``[seq]`` + Matches one character in *seq*. +``[!seq]`` + Matches one character not in *seq*. For a literal match, wrap the meta-characters in brackets. For example, ``"[?]"`` matches the character ``"?"``. From 1461d8b4817b5187a147ff2928e2f5c78880083c Mon Sep 17 00:00:00 2001 From: barneygale Date: Mon, 12 Feb 2024 23:35:17 +0000 Subject: [PATCH 12/16] Add "comparison to the glob module" section --- Doc/library/pathlib.rst | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst index 7c8096e6771b91..46021deb11b0e1 100644 --- a/Doc/library/pathlib.rst +++ b/Doc/library/pathlib.rst @@ -1664,6 +1664,29 @@ returned directories do not have a trailing slash. (:data:`~os.sep` or :data:`~os.altsep`) returns only directories. +Comparison to the :mod:`glob` module +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The patterns accepted and results generated by :meth:`~Path.glob` and +:meth:`~Path.rglob` differ slightly from those by the :mod:`glob` module: + +1. Hidden files (beginning with a dot) are not special in pathlib. This is + like passing ``include_hidden=True`` to :func:`glob.glob`. +2. "``**``" components are always recursive in pathlib. This is like passing + ``recursive=True`` to :func:`glob.glob`. +3. "``**``" components do not follow symlinks by default in pathlib. Pass + ``follow_symlinks=True`` to :meth:`Path.glob` for :func:`glob.glob`-like + behaviour. +4. Like all :class:`PurePath` and :class:`Path` objects, the values returned + from :meth:`Path.glob` and :meth:`~Path.rglob` don't include trailing + slashes. +5. The values returned from pathlib's ``path.glob()`` and ``path.rglob()`` + include the *path* as a prefix, unlike the results of + ``glob.glob(root_dir=path)``. +6. ``bytes``-based paths and :ref:`paths relative to directory descriptors + ` are not supported by pathlib. + + Correspondence to tools in the :mod:`os` module ----------------------------------------------- From fb20b5c9c9d365d61fe670ba9952c07e1ff501b6 Mon Sep 17 00:00:00 2001 From: barneygale Date: Mon, 12 Feb 2024 23:36:26 +0000 Subject: [PATCH 13/16] Remove duplicated text --- Doc/library/pathlib.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst index 46021deb11b0e1..f9bd589a11582e 100644 --- a/Doc/library/pathlib.rst +++ b/Doc/library/pathlib.rst @@ -1656,8 +1656,7 @@ Pattern Meaning directories. In previous versions, only directories were returned. In :meth:`Path.glob` and :meth:`~Path.rglob`, a trailing slash may be added to -the pattern to match only directories. Like all :class:`Path` objects, the -returned directories do not have a trailing slash. +the pattern to match only directories. .. versionchanged:: 3.11 Globbing with a pattern that ends with a pathname components separator From d7e6ed1495768f2bd408fe7bfc72eb5c4533b5db Mon Sep 17 00:00:00 2001 From: barneygale Date: Sun, 25 Feb 2024 23:55:09 +0000 Subject: [PATCH 14/16] Address review feedback --- Doc/library/pathlib.rst | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst index f9bd589a11582e..7b91f90c7d3374 100644 --- a/Doc/library/pathlib.rst +++ b/Doc/library/pathlib.rst @@ -573,7 +573,7 @@ Pure paths provide the following methods and properties: True .. seealso:: - :ref:`pattern-language` documentation. + :ref:`pathlib-pattern-language` documentation. As with other methods, case-sensitivity follows platform defaults:: @@ -1002,7 +1002,7 @@ call fails (for example because the path doesn't exist). PosixPath('test_pathlib.py')] .. seealso:: - :ref:`pattern-language` documentation. + :ref:`pathlib-pattern-language` documentation. This method calls :meth:`Path.is_dir` on the top-level directory and propagates any :exc:`OSError` exception that is raised. Subsequent @@ -1040,7 +1040,7 @@ call fails (for example because the path doesn't exist). :func:`Path.glob` with "``**/``" added in front of the *pattern*. .. seealso:: - :ref:`pattern-language` and :meth:`Path.glob` documentation. + :ref:`pathlib-pattern-language` and :meth:`Path.glob` documentation. .. audit-event:: pathlib.Path.rglob self,pattern pathlib.Path.rglob @@ -1612,7 +1612,7 @@ call fails (for example because the path doesn't exist). The *newline* parameter was added. -.. _pattern-language: +.. _pathlib-pattern-language: Pattern language ---------------- @@ -1620,11 +1620,11 @@ Pattern language The following wildcards are supported in patterns for :meth:`~PurePath.full_match`, :meth:`~Path.glob` and :meth:`~Path.rglob`: -``**`` (full segment) - Matches any number of file or directory segments. -``*`` (full segment) +``**`` (entire segment) + Matches any number of file or directory segments, including zero. +``*`` (entire segment) Matches one file or directory segment. -``*`` (otherwise) +``*`` (part of a segment) Matches any number of non-separator characters. ``?`` Matches one non-separator character. @@ -1669,13 +1669,13 @@ Comparison to the :mod:`glob` module The patterns accepted and results generated by :meth:`~Path.glob` and :meth:`~Path.rglob` differ slightly from those by the :mod:`glob` module: -1. Hidden files (beginning with a dot) are not special in pathlib. This is +1. Files beginning with a dot are not special in pathlib. This is like passing ``include_hidden=True`` to :func:`glob.glob`. -2. "``**``" components are always recursive in pathlib. This is like passing - ``recursive=True`` to :func:`glob.glob`. -3. "``**``" components do not follow symlinks by default in pathlib. Pass - ``follow_symlinks=True`` to :meth:`Path.glob` for :func:`glob.glob`-like - behaviour. +2. "``**``" pattern components are always recursive in pathlib. This is like + passing ``recursive=True`` to :func:`glob.glob`. +3. "``**``" pattern components do not follow symlinks by default in pathlib. + Pass ``follow_symlinks=True`` to :meth:`Path.glob` for + :func:`glob.glob`-like behaviour. 4. Like all :class:`PurePath` and :class:`Path` objects, the values returned from :meth:`Path.glob` and :meth:`~Path.rglob` don't include trailing slashes. From ec8012652ed69ebdabe478150be5fc59097d1bec Mon Sep 17 00:00:00 2001 From: barneygale Date: Mon, 26 Feb 2024 00:07:06 +0000 Subject: [PATCH 15/16] Clarifications --- Doc/library/pathlib.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst index 7b91f90c7d3374..28924b4e17b290 100644 --- a/Doc/library/pathlib.rst +++ b/Doc/library/pathlib.rst @@ -1666,18 +1666,18 @@ the pattern to match only directories. Comparison to the :mod:`glob` module ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The patterns accepted and results generated by :meth:`~Path.glob` and -:meth:`~Path.rglob` differ slightly from those by the :mod:`glob` module: +The patterns accepted and results generated by :meth:`Path.glob` and +:meth:`Path.rglob` differ slightly from those by the :mod:`glob` module: 1. Files beginning with a dot are not special in pathlib. This is like passing ``include_hidden=True`` to :func:`glob.glob`. 2. "``**``" pattern components are always recursive in pathlib. This is like passing ``recursive=True`` to :func:`glob.glob`. 3. "``**``" pattern components do not follow symlinks by default in pathlib. - Pass ``follow_symlinks=True`` to :meth:`Path.glob` for - :func:`glob.glob`-like behaviour. + This behaviour has no equivalent in :func:`glob.glob`, but you can pass + ``follow_symlinks=True`` to :meth:`Path.glob` for compatible behaviour. 4. Like all :class:`PurePath` and :class:`Path` objects, the values returned - from :meth:`Path.glob` and :meth:`~Path.rglob` don't include trailing + from :meth:`Path.glob` and :meth:`Path.rglob` don't include trailing slashes. 5. The values returned from pathlib's ``path.glob()`` and ``path.rglob()`` include the *path* as a prefix, unlike the results of From 5cc4894f74f0c95abe330840d00df395ea217a1b Mon Sep 17 00:00:00 2001 From: barneygale Date: Mon, 26 Feb 2024 00:09:14 +0000 Subject: [PATCH 16/16] Missed edit. --- Doc/library/pathlib.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst index 28924b4e17b290..4b461a5d4a2949 100644 --- a/Doc/library/pathlib.rst +++ b/Doc/library/pathlib.rst @@ -1625,7 +1625,7 @@ The following wildcards are supported in patterns for ``*`` (entire segment) Matches one file or directory segment. ``*`` (part of a segment) - Matches any number of non-separator characters. + Matches any number of non-separator characters, including zero. ``?`` Matches one non-separator character. ``[seq]``