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.match()تبدیل میکند. مشخصه مسیر میتواند شامل وایلدکارد بهسبک پوسته باشد.برای مثال:
>>> import glob, re >>> >>> regex = glob.translate('**/*.txt', recursive=True, include_hidden=True) >>> regex '(?s:(?:.+/)?[^/]*\\.txt)\\z' >>> reobj = re.compile(regex) >>> reobj.match('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.
مثالها¶
پوشهای را در نظر بگیرید که شامل پروندههای زیر است: 1.gif، 2.txt، card.gif و یک زیرپوشه sub که فقط شامل پرونده 3.txt است. glob() نتایج زیر را تولید خواهد کرد. توجه کنید که چگونه اجزای ابتدایی مسیر حفظ میشوند.
>>> 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/']
اگر پوشه حاوی پروندههایی باشد که با . شروع میشوند، بهطور پیشفرض تطبیق داده نمیشوند. برای مثال، پوشهای را در نظر بگیرید که حاوی card.gif و .card.gif است:
>>> import glob
>>> glob.glob('*.gif')
['card.gif']
>>> glob.glob('.c*')
['.card.gif']
همچنین ملاحظه نمائید
ماژول fnmatch بسط نام پرونده (نه مسیر) بهسبک پوسته را ارائه میدهد.
همچنین ملاحظه نمائید
ماژول pathlib اشیای مسیر سطح بالا را ارائه میدهد.