mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-09-27 02:39:58 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 13

GH-110417: Fix glob docs ordering (#110418)

Browse source 
Fix incorrect placement of `translate()` docs from cf67ebf.

Move "see also: pathlib" admonition to the bottom of the page, alongside one for fnmatch. This helps the module introduction flow more naturally into the function descriptions.

Add an "Examples" subheading just before the examples. This makes it more obvious that examples aren't specifically related to the preceding documentation of `escape()` and `translate()`.
This commit is contained in:
Barney Gale 2023-11-13 17:48:16 +00:00 • committed by GitHub
parent cf67ebfb31
commit d5491a6eff
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 36 additions and 35 deletions
Download patch file Download diff file Expand all files Collapse all files

71
Doc/library/glob.rst
View file

@ -34,9 +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:`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, \
@ -117,35 +115,6 @@ For example, ``'[?]'`` matches the character ``'?'``.
.. 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']
.. function:: translate(pathname, *, recursive=False, include_hidden=False, seps=None)
Convert the given path specification to a regular expression for use with
@ -184,7 +153,39 @@ default. For example, consider a directory containing :file:`card.gif` and
.. versionadded:: 3.13
.. seealso::
Examples
--------
Module :mod:`fnmatch`
Shell-style filename (not path) expansion
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.