glob --- بسط الگوی مسیر به سبک یونیکس¶

کد منبع: Lib/glob.py

ماژول glob مسیرنام‌ها را با استفاده از قواعد تطبیق الگو مشابه پوسته‌ی یونیکس پیدا می‌کند. هیچ بسط تیلدی (tilde expansion) انجام نمی‌شود، اما *، ? و بازه‌های نویسه‌ای بیان‌شده با [] به‌درستی تطبیق داده می‌شوند. این کار با استفاده‌ی هماهنگ از توابع os.scandir() و fnmatch.fnmatch() انجام می‌شود، نه با فراخوانی واقعی یک زیرپوسته.

به‌طور پیش‌فرض، پرونده‌هایی که با یک نقطه (.) شروع می‌شوند، فقط با الگوهایی که آن‌ها نیز با یک نقطه شروع می‌شوند مطابقت داده می‌شوند، برخلاف fnmatch.fnmatch() یا pathlib.Path.glob(). برای بسط تیلدا و متغیرهای پوسته، از os.path.expanduser() و os.path.expandvars() استفاده کنید.

برای تطبیق به‌صورت لفظی، فرانویسه‌ها را در کروشه قرار دهید. برای مثال، '[?]' با نویسه‌ی '?' مطابقت می‌کند.

ماژول glob توابع زیر را تعریف می‌کند:

glob.glob(pathname, *, root_dir=None, dir_fd=None, recursive=False, include_hidden=False)¶

فهرستی از نام‌های مسیر منطبق با pathname برمی‌گرداند که ممکن است خالی باشد. pathname باید رشته‌ای حاوی مشخصات مسیر باشد. pathname می‌تواند مطلق (مانند /usr/src/Python-1.5/Makefile) یا نسبی (مانند ../../Tools/*/*.gif) باشد و می‌تواند حاوی وایلدکارد به سبک پوسته باشد. پیوندهای نمادین شکسته در نتایج گنجانده می‌شوند (مانند پوسته). مرتب بودن یا نبودن نتایج به سامانه‌ی پرونده بستگی دارد. اگر پرونده‌ای که شرایط را برآورده می‌کند در حین فراخوانی این تابع حذف یا اضافه شود، نامشخص است که نام مسیری برای آن پرونده گنجانده خواهد شد یا نه.

اگر root_dir برابر None نباشد، باید یک path-like object باشد که پوشه ریشه را برای جست‌وجو مشخص می‌کند. تأثیر آن بر glob() همانند تغییر پوشه جاری پیش از فراخوانی آن است. اگر pathname نسبی باشد، نتیجه شامل مسیرهایی خواهد بود که نسبت به root_dir نسبی هستند.

این تابع می‌تواند با پارامتر dir_fd از مسیرهای نسبی نسبت به توصیف‌گرهای پوشه پشتیبانی کند.

اگر recursive درست باشد، الگوی «**» با هر پرونده‌ای و صفر یا چند پوشه، زیرپوشه و پیوند نمادین به پوشه‌ها مطابقت خواهد کرد. اگر پس از الگو os.sep یا os.altsep بیاید، پرونده‌ها مطابقت نخواهند کرد.

اگر include_hidden درست باشد، وایلدکارد می‌توانند با بخش‌هایی از مسیر که با نقطه (.) شروع می‌شوند، مطابقت کنند.

یک رویداد حسابرسی glob.glob را با آرگومان‌های pathname و recursive پرتاب می‌کند.

یک رویداد حسابرسی glob.glob/2 را با آرگومان‌های pathname، recursive، root_dir و dir_fd پرتاب می‌کند.

نکته

استفاده از الگوی "**" در درخت‌های پوشه‌ای بزرگ ممکن است زمان بسیار زیادی را مصرف کند.

نکته

این تابع ممکن است نام مسیرهای تکراری را برگرداند، اگر pathname شامل چندین الگوی "**" باشد و recursive برابر true باشد.

نکته

هر استثنای OSError که در اثر پویش سامانه فایل‌بندی پرتاب شود، سرکوب می‌شود. این شامل PermissionError هنگام دسترسی به پوشه‌های بدون مجوز خواندن نیز می‌شود.

تغییر یافته در نسخه‌ی 3.5: پشتیبانی از گلوب‌های بازگشتی (recursive globs) با استفاده از "**".

تغییر یافته در نسخه‌ی 3.10: پارامترهای root_dir و dir_fd افزوده شدند.

تغییر یافته در نسخه‌ی 3.11: پارامتر include_hidden اضافه شد.

glob.iglob(pathname, *, root_dir=None, dir_fd=None, recursive=False, include_hidden=False)¶

یک iterator برمی‌گرداند که همان مقادیر را مانند glob() تولید می‌کند، بدون آنکه همه‌ی آن‌ها را به‌طور همزمان ذخیره کند.

یک رویداد حسابرسی glob.glob را با آرگومان‌های pathname و recursive پرتاب می‌کند.

یک رویداد حسابرسی glob.glob/2 را با آرگومان‌های pathname، recursive، root_dir و dir_fd پرتاب می‌کند.

نکته

این تابع ممکن است نام مسیرهای تکراری را برگرداند، اگر pathname شامل چندین الگوی "**" باشد و recursive برابر true باشد.

نکته

هر استثنای OSError که در اثر پویش سامانه فایل‌بندی پرتاب شود، سرکوب می‌شود. این شامل PermissionError هنگام دسترسی به پوشه‌های بدون مجوز خواندن نیز می‌شود.

تغییر یافته در نسخه‌ی 3.5: پشتیبانی از گلوب‌های بازگشتی (recursive globs) با استفاده از "**".

تغییر یافته در نسخه‌ی 3.10: پارامترهای root_dir و dir_fd افزوده شدند.

تغییر یافته در نسخه‌ی 3.11: پارامتر include_hidden اضافه شد.

glob.escape(pathname)¶

تمام نویسه‌های خاص ('?'، '*' و '[') را خنثی می‌کند. این کار زمانی مفید است که بخواهید یک رشته‌ی لفظی دلخواه را که ممکن است حاوی نویسه‌های خاص باشد، تطبیق دهید. نویسه‌های خاص در نقاط اشتراک‌گذاری درایو/UNC خنثی نمی‌شوند. برای مثال در ویندوز، escape('//?/c:/Quo vadis?.txt') '//?/c:/Quo vadis[?].txt' را برمی‌گرداند.

اضافه شده در نسخه‌ی 3.4.

glob.translate(pathname, *, recursive=False, include_hidden=False, seps=None)¶

مشخصات مسیر داده‌شده را به یک عبارت باقاعده برای استفاده با re.prefixmatch() تبدیل کنید. مشخصات مسیر می‌تواند حاوی وایلدکاردهای سبک پوسته باشد.

برای مثال:

>>> import glob, re
>>>
>>> regex = glob.translate('**/*.txt', recursive=True, include_hidden=True)
>>> regex
'(?s:(?:.+/)?[^/]*\\.txt)\\z'
>>> reobj = re.compile(regex)
>>> reobj.prefixmatch('foo/bar/baz.txt')
<re.Match object; span=(0, 15), match='foo/bar/baz.txt'>

جداکننده‌ها و بخش‌های مسیر برای این تابع معنادار هستند، برخلاف fnmatch.translate(). به‌طور پیش‌فرض، وایلدکارد با جداکننده‌های مسیر مطابقت نمی‌کنند، و بخش‌های الگوی * دقیقاً با یک بخش مسیر مطابقت می‌کنند.

اگر recursive درست باشد، بخش الگو «**» با هر تعداد بخش مسیر مطابقت می‌کند.

اگر include_hidden true باشد، وایلدکارد می‌توانند با بخش‌هایی از مسیر که با نقطه (.) آغاز می‌شوند، مطابقت کنند.

می‌توان دنباله‌ای از جداکننده‌های مسیر را به آرگومان seps ارائه کرد. اگر داده نشود، از os.sep و altsep (در صورت موجود بودن) استفاده می‌شود.

همچنین ببینید

متدهای pathlib.PurePath.full_match() و pathlib.Path.glob()، که این تابع را برای پیاده‌سازی تطبیق الگو و بسط الگو (globbing) فراخوانی می‌کنند.

اضافه شده در نسخه‌ی 3.13.

>>> 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/']

>>> import glob
>>> glob.glob('*.gif')
['card.gif']
>>> glob.glob('.c*')
['.card.gif']