From b0c57e8c153b3eaf1a81be8f27f41b9f9de367b9 Mon Sep 17 00:00:00 2001 From: barneygale Date: Thu, 5 Oct 2023 18:57:34 +0100 Subject: [PATCH 1/3] GH-110417: Improve ordering of info in `glob` docs Move examples of `glob()` usage into the `.. function:: glob()` block, and move the mention of `fnmatch` to just before the mention of `pathlib`. As a result, the description and examples of `glob()` are not interrupted by descriptions of `iglob()` and `escape()`. --- Doc/library/glob.rst | 64 +++++++++++++++++++++----------------------- 1 file changed, 30 insertions(+), 34 deletions(-) diff --git a/Doc/library/glob.rst b/Doc/library/glob.rst index 0e4cfe7ebed797..92642d63d29700 100644 --- a/Doc/library/glob.rst +++ b/Doc/library/glob.rst @@ -34,6 +34,8 @@ unlike :func:`fnmatch.fnmatch` or :func:`pathlib.Path.glob`. For a literal match, wrap the meta-characters in brackets. For example, ``'[?]'`` matches the character ``'?'``. +.. seealso:: + The :mod:`fnmatch` module offers shell-style filename (not path) expansion. .. seealso:: The :mod:`pathlib` module offers high-level path objects. @@ -70,6 +72,34 @@ For example, ``'[?]'`` matches the character ``'?'``. If *include_hidden* is true, "``**``" pattern will match hidden directories. + For example, consider a directory containing the following files: + :file:`1.gif`, :file:`2.txt`, :file:`card.gif` and a subdirectory :file:`sub` + which contains only the file :file:`3.txt`. :func:`glob` will produce + the following results. Notice how any leading components of the path are + preserved. :: + + >>> import glob + >>> glob.glob('./[0-9].*') + ['./1.gif', './2.txt'] + >>> glob.glob('*.gif') + ['1.gif', 'card.gif'] + >>> glob.glob('?.gif') + ['1.gif'] + >>> glob.glob('**/*.txt', recursive=True) + ['2.txt', 'sub/3.txt'] + >>> glob.glob('./**/', recursive=True) + ['./', './sub/'] + + If the directory contains files starting with ``.`` they won't be matched by + default. For example, consider a directory containing :file:`card.gif` and + :file:`.card.gif`:: + + >>> import glob + >>> glob.glob('*.gif') + ['card.gif'] + >>> glob.glob('.c*') + ['.card.gif'] + .. audit-event:: glob.glob pathname,recursive glob.glob .. audit-event:: glob.glob/2 pathname,recursive,root_dir,dir_fd glob.glob @@ -115,37 +145,3 @@ For example, ``'[?]'`` matches the character ``'?'``. ``escape('//?/c:/Quo vadis?.txt')`` returns ``'//?/c:/Quo vadis[?].txt'``. .. versionadded:: 3.4 - - -For example, consider a directory containing the following files: -:file:`1.gif`, :file:`2.txt`, :file:`card.gif` and a subdirectory :file:`sub` -which contains only the file :file:`3.txt`. :func:`glob` will produce -the following results. Notice how any leading components of the path are -preserved. :: - - >>> import glob - >>> glob.glob('./[0-9].*') - ['./1.gif', './2.txt'] - >>> glob.glob('*.gif') - ['1.gif', 'card.gif'] - >>> glob.glob('?.gif') - ['1.gif'] - >>> glob.glob('**/*.txt', recursive=True) - ['2.txt', 'sub/3.txt'] - >>> glob.glob('./**/', recursive=True) - ['./', './sub/'] - -If the directory contains files starting with ``.`` they won't be matched by -default. For example, consider a directory containing :file:`card.gif` and -:file:`.card.gif`:: - - >>> import glob - >>> glob.glob('*.gif') - ['card.gif'] - >>> glob.glob('.c*') - ['.card.gif'] - -.. seealso:: - - Module :mod:`fnmatch` - Shell-style filename (not path) expansion From 689fcd6351a3082d7ff7289360438dcd84b1f755 Mon Sep 17 00:00:00 2001 From: barneygale Date: Fri, 13 Oct 2023 16:23:54 +0100 Subject: [PATCH 2/3] Undo most changes, add "Examples" heading. --- Doc/library/glob.rst | 72 ++++++++++++++++++++++++-------------------- 1 file changed, 39 insertions(+), 33 deletions(-) diff --git a/Doc/library/glob.rst b/Doc/library/glob.rst index 92642d63d29700..daaecfc8404aa3 100644 --- a/Doc/library/glob.rst +++ b/Doc/library/glob.rst @@ -34,11 +34,7 @@ unlike :func:`fnmatch.fnmatch` or :func:`pathlib.Path.glob`. For a literal match, wrap the meta-characters in brackets. For example, ``'[?]'`` matches the character ``'?'``. -.. seealso:: - The :mod:`fnmatch` module offers shell-style filename (not path) expansion. - -.. seealso:: - The :mod:`pathlib` module offers high-level path objects. +The :mod:`glob` module defines the following functions: .. function:: glob(pathname, *, root_dir=None, dir_fd=None, recursive=False, \ @@ -72,34 +68,6 @@ For example, ``'[?]'`` matches the character ``'?'``. If *include_hidden* is true, "``**``" pattern will match hidden directories. - For example, consider a directory containing the following files: - :file:`1.gif`, :file:`2.txt`, :file:`card.gif` and a subdirectory :file:`sub` - which contains only the file :file:`3.txt`. :func:`glob` will produce - the following results. Notice how any leading components of the path are - preserved. :: - - >>> import glob - >>> glob.glob('./[0-9].*') - ['./1.gif', './2.txt'] - >>> glob.glob('*.gif') - ['1.gif', 'card.gif'] - >>> glob.glob('?.gif') - ['1.gif'] - >>> glob.glob('**/*.txt', recursive=True) - ['2.txt', 'sub/3.txt'] - >>> glob.glob('./**/', recursive=True) - ['./', './sub/'] - - If the directory contains files starting with ``.`` they won't be matched by - default. For example, consider a directory containing :file:`card.gif` and - :file:`.card.gif`:: - - >>> import glob - >>> glob.glob('*.gif') - ['card.gif'] - >>> glob.glob('.c*') - ['.card.gif'] - .. audit-event:: glob.glob pathname,recursive glob.glob .. audit-event:: glob.glob/2 pathname,recursive,root_dir,dir_fd glob.glob @@ -145,3 +113,41 @@ For example, ``'[?]'`` matches the character ``'?'``. ``escape('//?/c:/Quo vadis?.txt')`` returns ``'//?/c:/Quo vadis[?].txt'``. .. versionadded:: 3.4 + + +Examples +-------- + +Consider a directory containing the following files: +:file:`1.gif`, :file:`2.txt`, :file:`card.gif` and a subdirectory :file:`sub` +which contains only the file :file:`3.txt`. :func:`glob` will produce +the following results. Notice how any leading components of the path are +preserved. :: + + >>> import glob + >>> glob.glob('./[0-9].*') + ['./1.gif', './2.txt'] + >>> glob.glob('*.gif') + ['1.gif', 'card.gif'] + >>> glob.glob('?.gif') + ['1.gif'] + >>> glob.glob('**/*.txt', recursive=True) + ['2.txt', 'sub/3.txt'] + >>> glob.glob('./**/', recursive=True) + ['./', './sub/'] + +If the directory contains files starting with ``.`` they won't be matched by +default. For example, consider a directory containing :file:`card.gif` and +:file:`.card.gif`:: + + >>> import glob + >>> glob.glob('*.gif') + ['card.gif'] + >>> glob.glob('.c*') + ['.card.gif'] + +.. seealso:: + The :mod:`fnmatch` module offers shell-style filename (not path) expansion. + +.. seealso:: + The :mod:`pathlib` module offers high-level path objects. From b977a3da664c65e11d33789484359a35a0c39109 Mon Sep 17 00:00:00 2001 From: barneygale Date: Mon, 13 Nov 2023 17:35:43 +0000 Subject: [PATCH 3/3] Fix ordering --- Doc/library/glob.rst | 63 ++++++++++++++++++++++---------------------- 1 file changed, 31 insertions(+), 32 deletions(-) diff --git a/Doc/library/glob.rst b/Doc/library/glob.rst index daa69b15e43c6e..6e4f72c19ff4c9 100644 --- a/Doc/library/glob.rst +++ b/Doc/library/glob.rst @@ -115,38 +115,6 @@ The :mod:`glob` module defines the following functions: .. versionadded:: 3.4 -Examples --------- - -Consider a directory containing the following files: -:file:`1.gif`, :file:`2.txt`, :file:`card.gif` and a subdirectory :file:`sub` -which contains only the file :file:`3.txt`. :func:`glob` will produce -the following results. Notice how any leading components of the path are -preserved. :: - - >>> import glob - >>> glob.glob('./[0-9].*') - ['./1.gif', './2.txt'] - >>> glob.glob('*.gif') - ['1.gif', 'card.gif'] - >>> glob.glob('?.gif') - ['1.gif'] - >>> glob.glob('**/*.txt', recursive=True) - ['2.txt', 'sub/3.txt'] - >>> glob.glob('./**/', recursive=True) - ['./', './sub/'] - -If the directory contains files starting with ``.`` they won't be matched by -default. For example, consider a directory containing :file:`card.gif` and -:file:`.card.gif`:: - - >>> import glob - >>> glob.glob('*.gif') - ['card.gif'] - >>> glob.glob('.c*') - ['.card.gif'] - - .. function:: translate(pathname, *, recursive=False, include_hidden=False, seps=None) Convert the given path specification to a regular expression for use with @@ -185,6 +153,37 @@ default. For example, consider a directory containing :file:`card.gif` and .. versionadded:: 3.13 +Examples +-------- + +Consider a directory containing the following files: +:file:`1.gif`, :file:`2.txt`, :file:`card.gif` and a subdirectory :file:`sub` +which contains only the file :file:`3.txt`. :func:`glob` will produce +the following results. Notice how any leading components of the path are +preserved. :: + + >>> import glob + >>> glob.glob('./[0-9].*') + ['./1.gif', './2.txt'] + >>> glob.glob('*.gif') + ['1.gif', 'card.gif'] + >>> glob.glob('?.gif') + ['1.gif'] + >>> glob.glob('**/*.txt', recursive=True) + ['2.txt', 'sub/3.txt'] + >>> glob.glob('./**/', recursive=True) + ['./', './sub/'] + +If the directory contains files starting with ``.`` they won't be matched by +default. For example, consider a directory containing :file:`card.gif` and +:file:`.card.gif`:: + + >>> import glob + >>> glob.glob('*.gif') + ['card.gif'] + >>> glob.glob('.c*') + ['.card.gif'] + .. seealso:: The :mod:`fnmatch` module offers shell-style filename (not path) expansion.