diff options
Diffstat (limited to 'devdocs/python~3.12/library%2Fglob.html')
| -rw-r--r-- | devdocs/python~3.12/library%2Fglob.html | 35 |
1 files changed, 35 insertions, 0 deletions
diff --git a/devdocs/python~3.12/library%2Fglob.html b/devdocs/python~3.12/library%2Fglob.html new file mode 100644 index 00000000..f02f8f7a --- /dev/null +++ b/devdocs/python~3.12/library%2Fglob.html @@ -0,0 +1,35 @@ + <span id="glob-unix-style-pathname-pattern-expansion"></span><h1>glob — Unix style pathname pattern expansion</h1> <p><strong>Source code:</strong> <a class="reference external" href="https://github.com/python/cpython/tree/3.12/Lib/glob.py">Lib/glob.py</a></p> <p id="index-1">The <a class="reference internal" href="#module-glob" title="glob: Unix shell style pathname pattern expansion."><code>glob</code></a> module finds all the pathnames matching a specified pattern according to the rules used by the Unix shell, although results are returned in arbitrary order. No tilde expansion is done, but <code>*</code>, <code>?</code>, and character ranges expressed with <code>[]</code> will be correctly matched. This is done by using the <a class="reference internal" href="os#os.scandir" title="os.scandir"><code>os.scandir()</code></a> and <a class="reference internal" href="fnmatch#fnmatch.fnmatch" title="fnmatch.fnmatch"><code>fnmatch.fnmatch()</code></a> functions in concert, and not by actually invoking a subshell.</p> <p>Note that files beginning with a dot (<code>.</code>) can only be matched by patterns that also start with a dot, unlike <a class="reference internal" href="fnmatch#fnmatch.fnmatch" title="fnmatch.fnmatch"><code>fnmatch.fnmatch()</code></a> or <a class="reference internal" href="pathlib#pathlib.Path.glob" title="pathlib.Path.glob"><code>pathlib.Path.glob()</code></a>. (For tilde and shell variable expansion, use <a class="reference internal" href="os.path#os.path.expanduser" title="os.path.expanduser"><code>os.path.expanduser()</code></a> and <a class="reference internal" href="os.path#os.path.expandvars" title="os.path.expandvars"><code>os.path.expandvars()</code></a>.)</p> <p>For a literal match, wrap the meta-characters in brackets. For example, <code>'[?]'</code> matches the character <code>'?'</code>.</p> <div class="admonition seealso"> <p class="admonition-title">See also</p> <p>The <a class="reference internal" href="pathlib#module-pathlib" title="pathlib: Object-oriented filesystem paths"><code>pathlib</code></a> module offers high-level path objects.</p> </div> <dl class="py function"> <dt class="sig sig-object py" id="glob.glob"> +<code>glob.glob(pathname, *, root_dir=None, dir_fd=None, recursive=False, include_hidden=False)</code> </dt> <dd> +<p>Return a possibly empty list of path names that match <em>pathname</em>, which must be a string containing a path specification. <em>pathname</em> can be either absolute (like <code>/usr/src/Python-1.5/Makefile</code>) or relative (like <code>../../Tools/*/*.gif</code>), and can contain shell-style wildcards. Broken symlinks are included in the results (as in the shell). Whether or not the results are sorted depends on the file system. If a file that satisfies conditions is removed or added during the call of this function, whether a path name for that file will be included is unspecified.</p> <p>If <em>root_dir</em> is not <code>None</code>, it should be a <a class="reference internal" href="../glossary#term-path-like-object"><span class="xref std std-term">path-like object</span></a> specifying the root directory for searching. It has the same effect on <a class="reference internal" href="#module-glob" title="glob: Unix shell style pathname pattern expansion."><code>glob()</code></a> as changing the current directory before calling it. If <em>pathname</em> is relative, the result will contain paths relative to <em>root_dir</em>.</p> <p>This function can support <a class="reference internal" href="os#dir-fd"><span class="std std-ref">paths relative to directory descriptors</span></a> with the <em>dir_fd</em> parameter.</p> <p id="index-2">If <em>recursive</em> is true, the pattern “<code>**</code>” will match any files and zero or more directories, subdirectories and symbolic links to directories. If the pattern is followed by an <a class="reference internal" href="os#os.sep" title="os.sep"><code>os.sep</code></a> or <a class="reference internal" href="os#os.altsep" title="os.altsep"><code>os.altsep</code></a> then files will not match.</p> <p>If <em>include_hidden</em> is true, “<code>**</code>” pattern will match hidden directories.</p> <p class="audit-hook">Raises an <a class="reference internal" href="sys#auditing"><span class="std std-ref">auditing event</span></a> <code>glob.glob</code> with arguments <code>pathname</code>, <code>recursive</code>.</p> <p class="audit-hook">Raises an <a class="reference internal" href="sys#auditing"><span class="std std-ref">auditing event</span></a> <code>glob.glob/2</code> with arguments <code>pathname</code>, <code>recursive</code>, <code>root_dir</code>, <code>dir_fd</code>.</p> <div class="admonition note"> <p class="admonition-title">Note</p> <p>Using the “<code>**</code>” pattern in large directory trees may consume an inordinate amount of time.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.5: </span>Support for recursive globs using “<code>**</code>”.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.10: </span>Added the <em>root_dir</em> and <em>dir_fd</em> parameters.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.11: </span>Added the <em>include_hidden</em> parameter.</p> </div> </dd> +</dl> <dl class="py function"> <dt class="sig sig-object py" id="glob.iglob"> +<code>glob.iglob(pathname, *, root_dir=None, dir_fd=None, recursive=False, include_hidden=False)</code> </dt> <dd> +<p>Return an <a class="reference internal" href="../glossary#term-iterator"><span class="xref std std-term">iterator</span></a> which yields the same values as <a class="reference internal" href="#module-glob" title="glob: Unix shell style pathname pattern expansion."><code>glob()</code></a> without actually storing them all simultaneously.</p> <p class="audit-hook">Raises an <a class="reference internal" href="sys#auditing"><span class="std std-ref">auditing event</span></a> <code>glob.glob</code> with arguments <code>pathname</code>, <code>recursive</code>.</p> <p class="audit-hook">Raises an <a class="reference internal" href="sys#auditing"><span class="std std-ref">auditing event</span></a> <code>glob.glob/2</code> with arguments <code>pathname</code>, <code>recursive</code>, <code>root_dir</code>, <code>dir_fd</code>.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.5: </span>Support for recursive globs using “<code>**</code>”.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.10: </span>Added the <em>root_dir</em> and <em>dir_fd</em> parameters.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.11: </span>Added the <em>include_hidden</em> parameter.</p> </div> </dd> +</dl> <dl class="py function"> <dt class="sig sig-object py" id="glob.escape"> +<code>glob.escape(pathname)</code> </dt> <dd> +<p>Escape all special characters (<code>'?'</code>, <code>'*'</code> and <code>'['</code>). This is useful if you want to match an arbitrary literal string that may have special characters in it. Special characters in drive/UNC sharepoints are not escaped, e.g. on Windows <code>escape('//?/c:/Quo vadis?.txt')</code> returns <code>'//?/c:/Quo vadis[?].txt'</code>.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.4.</span></p> </div> </dd> +</dl> <p>For example, consider a directory containing the following files: <code>1.gif</code>, <code>2.txt</code>, <code>card.gif</code> and a subdirectory <code>sub</code> which contains only the file <code>3.txt</code>. <a class="reference internal" href="#module-glob" title="glob: Unix shell style pathname pattern expansion."><code>glob()</code></a> will produce the following results. Notice how any leading components of the path are preserved.</p> <pre data-language="python">>>> 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/'] +</pre> <p>If the directory contains files starting with <code>.</code> they won’t be matched by default. For example, consider a directory containing <code>card.gif</code> and <code>.card.gif</code>:</p> <pre data-language="python">>>> import glob +>>> glob.glob('*.gif') +['card.gif'] +>>> glob.glob('.c*') +['.card.gif'] +</pre> <div class="admonition seealso"> <p class="admonition-title">See also</p> <dl class="simple"> <dt> +<code>Module</code> <a class="reference internal" href="fnmatch#module-fnmatch" title="fnmatch: Unix shell style filename pattern matching."><code>fnmatch</code></a> +</dt> +<dd> +<p>Shell-style filename (not path) expansion</p> </dd> </dl> </div> <div class="_attribution"> + <p class="_attribution-p"> + © 2001–2023 Python Software Foundation<br>Licensed under the PSF License.<br> + <a href="https://docs.python.org/3.12/library/glob.html" class="_attribution-link">https://docs.python.org/3.12/library/glob.html</a> + </p> +</div> |