نویسه‌های خاص عبارتند از:¶

نویسه‌های خاص عبارتند از:

>>> import re
>>> m = re.search('(?<=abc)def', 'abcdef')
>>> m.group(0)
'def'

>>> m = re.search(r'(?<=-)\w+', 'spam-egg')
>>> m.group(0)
'egg'

دنباله¶

دنباله‌های ویژه شامل '\' و یک نویسه از فهرست زیر هستند. اگر نویسه معمولی یک رقم ASCII یا یک حرف ASCII نباشد، عبارت باقاعده حاصل با دومین نویسه تطابق خواهد داشت. برای مثال، \$ با نویسه '$' تطابق دارد.

Standard escapes¶

بیشتر دنباله‌های خنثی‌سازی پشتیبانی‌شده توسط رشته‌نوشته‌های پایتون، توسط پارسر عبارت باقاعده نیز پذیرفته می‌شوند:

\a      \b      \f      \n
\N      \r      \t      \u
\U      \v      \x      \\

(توجه داشته باشید که \b برای نمایش مرزهای واژه به کار می‌رود و تنها در کلاس‌های نویسه به‌معنای «پس‌بر» (backspace) است.)

دنباله‌های خنثی‌سازی '\u'، '\U' و '\N' فقط در الگوهای یونیکد (str) شناسایی می‌شوند. در الگوهای bytes، این موارد خطا محسوب می‌شوند. دنباله‌های خنثی‌سازی ناشناخته‌ی حروف ASCII برای استفاده‌ی آینده محفوظ هستند و به‌عنوان خطا در نظر گرفته می‌شوند.

خنثی‌سازی‌های مبنای هشت به‌صورت محدودی گنجانده شده‌اند. اگر اولین رقم 0 باشد یا سه رقم مبنای هشت وجود داشته باشد، به‌عنوان یک خنثی‌سازی مبنای هشت در نظر گرفته می‌شود. در غیر این صورت، یک ارجاع به گروه است. مانند رشته‌های لفظی، طول خنثی‌سازی‌های مبنای هشت همیشه حداکثر سه رقم است.

پرچم‌ها¶

class re.RegexFlag¶

یک کلاس enum.IntFlag که شامل گزینه‌های regex فهرست‌شده در زیر است.

اضافه شده در نسخه‌ی 3.11: - added to __all__

re.A¶

re.ASCII¶

باعث می‌شود \w، \W، \b، \B، \d، \D، \s و \S به‌جای تطبیق کامل یونیکد، تطبیق فقط ASCII را انجام دهند. این موضوع فقط برای الگوهای یونیکد (str) معنادار است و برای الگوهای bytes نادیده گرفته می‌شود.

معادل پرچم درون‌خطی (?a) است.

نکته

پرچم U همچنان برای سازگاری با نسخه‌های پیشین وجود دارد، اما در Python 3 اضافی است، زیرا برای الگوهای str، تطبیق‌ها به‌طور پیش‌فرض یونیکد هستند و تطبیق یونیکد برای الگوهای bytes مجاز نیست. UNICODE و پرچم درون‌خطی (?u) نیز به‌طور مشابهی اضافی هستند.

re.DEBUG¶

نمایش اطلاعات اشکال‌زدایی درباره عبارت کامپایل‌شده.

پرچم درون‌خطی متناظری وجود ندارد.

re.I¶

re.IGNORECASE¶

تطبیق بدون حساسیت به بزرگی و کوچکی حروف را انجام می‌دهد؛ عبارت‌هایی مانند [A-Z] با حروف کوچک نیز تطبیق می‌کنند. تطبیق کامل یونیکد (مانند تطبیق Ü با ü) نیز عمل می‌کند، مگر اینکه از پرچم ASCII برای غیرفعال کردن تطبیق‌های غیر ASCII استفاده شود. تنظیمات locale فعلی تأثیر این پرچم را تغییر نمی‌دهد، مگر اینکه از پرچم LOCALE نیز استفاده شود.

معادل پرچم درون‌خطی (?i) است.

توجه داشته باشید که هنگامی که الگوهای یونیکد [a-z] یا [A-Z] به‌همراه پرچم IGNORECASE استفاده شوند، با ۵۲ حرف ASCII و ۴ حرف غیرASCII دیگر مطابقت خواهند داشت: 'İ' (U+0130، حرف بزرگ لاتین I با نقطه بالا)، 'ı' (U+0131، حرف کوچک لاتین i بدون نقطه)، 'ſ' (U+017F، حرف کوچک لاتین s بلند) و 'K' (U+212A، نماد کلوین). اگر پرچم ASCII استفاده شود، فقط با حروف 'a' تا 'z' و 'A' تا 'Z' مطابقت داده خواهد شد.

re.L¶

re.LOCALE¶

\w، \W، \b، \B و تطبیق بدون حساسیت به بزرگی و کوچکی حروف را به تنظیمات locale وابسته می‌کند. این پرچم را فقط می‌توان با الگوهای بایتی به کار برد.

معادل پرچم درون‌خطی (?L) است.

هشدار

استفاده از این پرچم توصیه نمی‌شود؛ در عوض تطبیق یونیکد را در نظر بگیرید. سازوکار تنظیمات locale بسیار غیرقابل‌اعتماد است، زیرا تنها یک «فرهنگ» را در هر زمان مدیریت می‌کند و فقط با تنظیمات locale ۸ بیتی کار می‌کند. تطبیق یونیکد برای الگوهای یونیکد (str) به‌طور پیش‌فرض فعال است و می‌تواند تنظیمات locale و زبان‌های مختلف را مدیریت کند.

تغییر یافته در نسخه‌ی 3.6: LOCALE فقط می‌تواند با الگوهای بایت استفاده شود و با ASCII سازگار نیست.

تغییر یافته در نسخه‌ی 3.7: اشیای عبارت باقاعده‌ی کامپایل‌شده با پرچم LOCALE دیگر به تنظیمات locale در زمان کامپایل وابسته نیستند. تنها تنظیمات locale در زمان تطبیق بر نتیجه‌ی تطبیق تأثیر می‌گذارد.

re.M¶

re.MULTILINE¶

هنگامی که تعیین شود، نویسه‌ی الگو '^' در ابتدای رشته و در ابتدای هر خط (بلافاصله پس از هر نویسه‌ی خط جدید) تطابق دارد؛ و نویسه‌ی الگو '$' در انتهای رشته و در انتهای هر خط (بلافاصله پیش از هر نویسه‌ی خط جدید) تطابق دارد. به‌طور پیش‌فرض، '^' فقط در ابتدای رشته تطابق دارد، و '$' فقط در انتهای رشته و بلافاصله پیش از نویسه‌ی خط جدید (در صورت وجود) در انتهای رشته تطابق دارد.

معادل پرچم درون‌خطی (?m) است.

re.NOFLAG¶

نشان می‌دهد که هیچ پرچمی اعمال‌نشده است؛ مقدار آن 0 است. این پرچم می‌تواند به‌عنوان مقدار پیش‌فرض برای یک آرگومان کلیدواژه‌ای تابع یا به‌عنوان مقدار پایه‌ای که به‌صورت شرطی با پرچم‌های دیگر OR می‌شود، استفاده شود. نمونه‌ای از استفاده به‌عنوان مقدار پیش‌فرض:

def myfunc(pattern, text, flag=re.NOFLAG):
    return re.search(pattern, text, flag)

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

re.S¶

re.DOTALL¶

باعث می‌شود نویسه ویژه '.' با هر نویسه‌ای، از جمله خط جدید، مطابقت کند؛ بدون این پرچم، '.' با هر چیزی به‌جز خط جدید مطابقت می‌کند.

متناظر با پرچم درون‌خطی (?s) است.

re.U¶

re.UNICODE¶

در Python 3، نویسه‌های یونیکد به‌طور پیش‌فرض برای الگوهای str تطبیق داده می‌شوند. بنابراین این پرچم بی‌مورد و بدون اثر است و فقط برای سازگاری با نسخه‌های پیشین نگه داشته شده است.

برای محدود کردن تطبیق به نویسه‌های ASCII، به‌جای آن ASCII را ببینید.

re.X¶

re.VERBOSE¶

این پرچم به شما امکان می‌دهد عبارت‌های باقاعده‌ای بنویسید که زیباتر به نظر می‌رسند و خواناتر هستند؛ زیرا می‌توانید بخش‌های منطقی الگو را به‌صورت بصری از هم جدا کنید و توضیح اضافه کنید. فضای سفید درون الگو نادیده گرفته می‌شود، مگر وقتی در یک کلاس نویسه باشد، یا وقتی یک بک‌اسلش خنثی‌نشده پیش از آن آمده باشد، یا درون توکن‌هایی مانند *?، (?: یا (?P<...>. برای مثال، (? : و * ? مجاز نیستند. وقتی سطری شامل # باشد که در یک کلاس نویسه نباشد و یک بک‌اسلش خنثی‌نشده پیش از آن نیامده باشد، تمام نویسه‌ها از چپ‌ترین # با این شرایط تا پایان خط نادیده گرفته می‌شوند.

این بدان معناست که دو شیء عبارت باقاعده زیر که با یک عدد دهدهی مطابقت دارند، از نظر عملکردی برابرند:

a = re.compile(r"""\d +  # the integral part
                   \.    # the decimal point
                   \d *  # some fractional digits""", re.X)
b = re.compile(r"\d+\.\d*")

متناظر با پرچم درون‌خطی (?x) است.

توابع¶

re.compile(pattern, flags=0)¶

یک الگوی عبارت باقاعده را به یک شیء عبارت باقاعده کامپایل می‌کند که می‌توان از آن برای تطبیق با استفاده از prefixmatch()، search() و سایر متدهای آن، که در ادامه توصیف شده‌اند، استفاده کرد.

رفتار عبارت را می‌توان با تعیین یک مقدار flags تغییر داد. مقادیر می‌توانند هر یک از متغیرهای flags باشند و با استفاده از OR بیتی (عملگر |) ترکیب شوند.

دنباله

prog = re.compile(pattern)
result = prog.search(string)

معادل است با

result = re.search(pattern, string)

اما استفاده از re.compile() و ذخیره‌ی شیء عبارت باقاعده‌ی حاصل برای استفاده‌ی مجدد، زمانی که عبارت چندین بار در یک برنامه واحد استفاده شود، کارآمدتر است.

نکته

نسخه‌های کامپایل‌شده‌ی آخرین الگوهای داده‌شده به re.compile() و به توابع تطبیق در سطح ماژول، در نهانگاه ذخیره می‌شوند؛ بنابراین برنامه‌هایی که در هر زمان تنها از چند عبارت باقاعده استفاده می‌کنند، نیازی به نگرانی درباره‌ی کامپایل کردن عبارات باقاعده ندارند.

re.search(pattern, string, flags=0)¶

string را پیمایش می‌کند تا نخستین مکانی را بیابد که عبارت باقاعده‌ی pattern در آن تطابقی ایجاد می‌کند، و یک Match متناظر برمی‌گرداند. اگر هیچ موقعیتی در رشته با الگو تطابق نداشته باشد، None برمی‌گرداند؛ توجه داشته باشید که این با یافتن یک تطابق به طول صفر در نقطه‌ای از رشته متفاوت است.

رفتار عبارت را می‌توان با تعیین یک مقدار flags تغییر داد. مقادیر می‌توانند هر یک از متغیرهای flags باشند و با استفاده از OR بیتی (عملگر |) ترکیب شوند.

re.prefixmatch(pattern, string, flags=0)¶

اگر صفر یا چند نویسه در ابتدای string با عبارت باقاعده‌ی pattern تطابق داشته باشند، یک Match متناظر برمی‌گرداند. اگر رشته با الگو تطابق نداشته باشد، None برمی‌گرداند؛ توجه داشته باشید که این با یک تطابق با طول صفر متفاوت است.

نکته

حتی در حالت MULTILINE، این مورد فقط در ابتدای رشته مطابقت پیدا می‌کند و نه در ابتدای هر سطر.

اگر می‌خواهید یک تطابق را در هر جای string پیدا کنید، در عوض از search() استفاده کنید (همچنین تابع search() در برابر prefixmatch() را ببینید).

رفتار عبارت را می‌توان با تعیین یک مقدار flags تغییر داد. مقادیر می‌توانند هر یک از متغیرهای flags باشند و با استفاده از OR بیتی (عملگر |) ترکیب شوند.

این تابع اکنون دو نام دارد و مدت‌هاست با نام match() شناخته می‌شود. هنگامی که نیاز دارید سازگاری با نسخه‌های قدیمی‌تر پایتون را حفظ کنید، از آن نام استفاده کنید.

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

re.match(pattern, string, flags=0)¶

منسوخ‌سازی نرم <Soft deprecated> از نسخه‌ی 3.15: تابع match() به نفع نام جایگزین prefixmatch() از این API که توصیف صریح‌تری دارد، به صورت منسوخ نرم درآمده است. از آن برای بیان بهتر مقصود استفاده کنید. هنجار در سایر زبان‌ها و پیاده‌سازی‌های عبارت باقاعده این است که از اصطلاح match برای ارجاع به رفتاری استفاده شود که پایتون همواره آن را search() نامیده است. نگاه کنید به توابع prefixmatch() در برابر match().

re.fullmatch(pattern, string, flags=0)¶

اگر کل string با عبارت باقاعده pattern تطابق داشته باشد، یک Match متناظر برمی‌گرداند. اگر رشته با الگو تطابق نداشته باشد، None برمی‌گرداند؛ توجه داشته باشید که این با تطابق با طول صفر متفاوت است.

رفتار عبارت را می‌توان با تعیین یک مقدار flags تغییر داد. مقادیر می‌توانند هر یک از متغیرهای flags باشند و با استفاده از OR بیتی (عملگر |) ترکیب شوند.

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

re.split(pattern, string, maxsplit=0, flags=0)¶

string را بر اساس موارد وقوع pattern تقسیم می‌کند. اگر در pattern از پرانتزهای ثبت‌کننده استفاده شود، متن همه‌ی گروه‌های موجود در الگو نیز به‌عنوان بخشی از فهرست حاصل بازگردانده می‌شود. اگر maxsplit ناصفر باشد، حداکثر maxsplit تقسیم صورت می‌گیرد و باقی‌مانده‌ی رشته به‌عنوان آخرین عنصر فهرست بازگردانده می‌شود.

>>> re.split(r'\W+', 'Words, words, words.')
['Words', 'words', 'words', '']
>>> re.split(r'(\W+)', 'Words, words, words.')
['Words', ', ', 'words', ', ', 'words', '.', '']
>>> re.split(r'\W+', 'Words, words, words.', maxsplit=1)
['Words', 'words, words.']
>>> re.split('[a-f]+', '0a3B9', flags=re.IGNORECASE)
['0', '3', '9']

اگر جداکننده دارای گروه‌های ثبت‌کننده باشد و در ابتدای رشته تطابق داشته باشد، نتیجه با یک رشته خالی آغاز می‌شود. همین حالت برای انتهای رشته نیز صادق است:

>>> re.split(r'(\W+)', '...words, words...')
['', '...', 'words', ', ', 'words', '...', '']

به این ترتیب، کامپوننت‌های جداکننده همیشه در اندیس‌های نسبی یکسان در فهرست نتیجه یافت می‌شوند.

امکان تطابق‌های خالی مجاور وجود ندارد، اما یک تطابق خالی می‌تواند بلافاصله پس از یک تطابق غیرخالی رخ دهد.

>>> re.split(r'\b', 'Words, words, words.')
['', 'Words', ', ', 'words', ', ', 'words', '.']
>>> re.split(r'\W*', '...words...')
['', '', 'w', 'o', 'r', 'd', 's', '', '']
>>> re.split(r'(\W*)', '...words...')
['', '...', '', '', 'w', '', 'o', '', 'r', '', 'd', '', 's', '...', '', '', '']

رفتار عبارت را می‌توان با تعیین یک مقدار flags تغییر داد. مقادیر می‌توانند هر یک از متغیرهای flags باشند و با استفاده از OR بیتی (عملگر |) ترکیب شوند.

تغییر یافته در نسخه‌ی 3.1: آرگومان اختیاری flags افزوده شد.

تغییر یافته در نسخه‌ی 3.7: پشتیبانی از جداسازی بر اساس الگویی که می‌تواند با رشته خالی مطابقت داشته باشد، اضافه شد.

منسوخ شده از نسخه‌ی 3.13: ارسال maxsplit و flags به‌عنوان آرگومان‌های جایگاهی منسوخ شده است. در نسخه‌های آینده پایتون، آن‌ها پارامترهای فقط کلیدواژه‌ای خواهند بود.

re.findall(pattern, string, flags=0)¶

تمام تطابق‌های غیرهم‌پوشانِ pattern در string را به‌صورت فهرستی از رشته‌ها یا تاپل‌ها برمی‌گرداند. string از چپ به راست پیمایش می‌شود و تطابق‌ها به ترتیبی که یافت می‌شوند، برگردانده می‌شوند. تطابق‌های خالی نیز در نتیجه گنجانده می‌شوند.

نتیجه به تعداد گروه‌های ثبت‌کننده در الگو بستگی دارد. اگر هیچ گروهی وجود نداشته باشد، فهرستی از رشته‌های منطبق با کل الگو برمی‌گرداند. اگر دقیقاً یک گروه وجود داشته باشد، فهرستی از رشته‌های منطبق با آن گروه برمی‌گرداند. اگر چندین گروه وجود داشته باشد، فهرستی از تاپل‌هایی از رشته‌های منطبق با گروه‌ها برمی‌گرداند. گروه‌های غیرثبت‌کننده بر شکل نتیجه تأثیری ندارند.

>>> re.findall(r'\bf[a-z]*', 'which foot or hand fell fastest')
['foot', 'fell', 'fastest']
>>> re.findall(r'(\w+)=(\d+)', 'set width=20 and height=10')
[('width', '20'), ('height', '10')]

رفتار عبارت را می‌توان با تعیین یک مقدار flags تغییر داد. مقادیر می‌توانند هر یک از متغیرهای flags باشند و با استفاده از OR بیتی (عملگر |) ترکیب شوند.

تغییر یافته در نسخه‌ی 3.7: تطابق‌های غیرخالی اکنون می‌توانند درست پس از یک تطابق خالی پیشین آغاز شوند.

re.finditer(pattern, string, flags=0)¶

یک iterator برگردانید که روی همه‌ی تطبیق‌های غیرهم‌پوشان الگوی عبارت باقاعده‌ی pattern در string، شیءهای Match را تولید می‌کند. string از چپ به راست پیمایش می‌شود و تطبیق‌ها به ترتیبی که پیدا می‌شوند برگردانده می‌شوند. تطبیق‌های خالی نیز در نتیجه گنجانده می‌شوند.

رفتار عبارت را می‌توان با تعیین یک مقدار flags تغییر داد. مقادیر می‌توانند هر یک از متغیرهای flags باشند و با استفاده از OR بیتی (عملگر |) ترکیب شوند.

تغییر یافته در نسخه‌ی 3.7: تطابق‌های غیرخالی اکنون می‌توانند درست پس از یک تطابق خالی پیشین آغاز شوند.

re.sub(pattern, repl, string, count=0, flags=0)¶

رشته‌ی حاصل از جایگزینی چپ‌ترین رخدادهای بدون هم‌پوشانی pattern در string با جایگزین repl را برمی‌گرداند. اگر pattern یافت نشود، string بدون تغییر برگردانده می‌شود. repl می‌تواند یک رشته یا یک تابع باشد؛ اگر رشته باشد، هرگونه دنباله‌ی خنثی‌سازی با بک‌اسلش در آن پردازش می‌شود. یعنی \n به یک نویسه‌ی خط جدید تبدیل می‌شود، \r به بازگشت به ابتدای سطر تبدیل می‌شود، و به همین ترتیب. دنباله‌های خنثی‌سازی ناشناخته‌ی شامل حروف ASCII برای استفاده‌ی آینده محفوظ هستند و به‌عنوان خطا تلقی می‌شوند. سایر دنباله‌های خنثی‌سازی ناشناخته مانند \& به‌حال خود باقی می‌مانند. بازارجاع‌ها (backreferences)، مانند \6، با زیررشته‌ای که گروه ۶ در الگو آن را تطبیق داده است، جایگزین می‌شوند. برای مثال:

>>> re.sub(r'def\s+([a-zA-Z_][a-zA-Z_0-9]*)\s*\(\s*\):',
...        r'static PyObject*\npy_\1(void)\n{',
...        'def myfunc():')
'static PyObject*\npy_myfunc(void)\n{'

اگر repl یک تابع باشد، برای هر رخداد غیرهمپوشان pattern فراخوانی می‌شود. این تابع یک آرگومان از نوع Match می‌گیرد و رشته جایگزینی را برمی‌گرداند. برای مثال:

>>> def dashrepl(matchobj):
...     if matchobj.group(0) == '-': return ' '
...     else: return '-'
...
>>> re.sub('-{1,2}', dashrepl, 'pro----gram-files')
'pro--gram files'
>>> re.sub(r'\sAND\s', ' & ', 'Baked Beans And Spam', flags=re.IGNORECASE)
'Baked Beans & Spam'

الگو ممکن است یک رشته یا یک Pattern باشد.

آرگومان اختیاری count حداکثر تعداد رخدادهای الگو برای جایگزینی است؛ count باید یک عدد صحیح غیرمنفی باشد. اگر حذف شود یا صفر باشد، تمام رخدادهای الگو جایگزین می‌شوند.

تطبیق‌های خالی مجاور امکان‌پذیر نیستند، اما یک تطبیق خالی می‌تواند بلافاصله پس از یک تطبیق غیرخالی رخ دهد. در نتیجه، sub('x*', '-', 'abxd') مقدار '-a-b--d-' را به‌جای '-a-b-d-' برمی‌گرداند.

در آرگومان‌های repl از نوع رشته، علاوه بر دنباله‌های خنثی‌سازی نویسه و بازارجاع‌ها شرح‌داده‌شده در بالا، \g<name> از زیررشته‌ی تطبیق‌داده‌شده با گروهی به نام name استفاده خواهد کرد، همان‌طور که با سینتکس (?P<name>...) تعریف شده است. \g<number> از شماره‌ی گروه متناظر استفاده می‌کند؛ بنابراین \g<2> معادل \2 است، اما در جایگزینی مانند \g<2>0 مبهم نیست. \20 به‌عنوان ارجاعی به گروه ۲۰ تفسیر می‌شود، نه ارجاعی به گروه ۲ که پس از آن نویسه‌ی لفظی '0' آمده است. بازارجاع \g<0> با کل زیررشته‌ی تطبیق‌داده‌شده با RE جایگزین می‌شود.

رفتار عبارت را می‌توان با تعیین یک مقدار flags تغییر داد. مقادیر می‌توانند هر یک از متغیرهای flags باشند و با استفاده از OR بیتی (عملگر |) ترکیب شوند.

تغییر یافته در نسخه‌ی 3.1: آرگومان اختیاری flags افزوده شد.

تغییر یافته در نسخه‌ی 3.5: گروه‌های مطابقت‌نشده با یک رشته خالی جایگزین می‌شوند.

تغییر یافته در نسخه‌ی 3.6: خنثی‌سازی‌های ناشناخته در pattern که از '\' و یک حرف ASCII تشکیل شده‌اند، اکنون خطا محسوب می‌شوند.

تغییر یافته در نسخه‌ی 3.7: دنباله‌های خنثی‌سازی ناشناخته در repl که از '\' و یک حرف ASCII تشکیل شده‌اند، اکنون خطا هستند. یک تطابق خالی می‌تواند بلافاصله پس از یک تطابق غیرخالی رخ دهد.

تغییر یافته در نسخه‌ی 3.12: شناسه‌ی گروه id فقط می‌تواند شامل ارقام ASCII باشد. در رشته‌های جایگزینی bytes، نام گروه name فقط می‌تواند شامل بایت‌هایی در محدوده‌ی ASCII باشد (b'\x00'-b'\x7f').

منسوخ شده از نسخه‌ی 3.13: ارسال count و flags به‌عنوان آرگومان‌های جایگاهی منسوخ شده است. در نسخه‌های آینده پایتون، آن‌ها پارامترهای فقط کلیدواژه‌ای خواهند بود.

re.subn(pattern, repl, string, count=0, flags=0)¶

همان عملیات sub() را انجام می‌دهد، اما یک تاپل به شکل (new_string, number_of_subs_made) برمی‌گرداند.

رفتار عبارت را می‌توان با تعیین یک مقدار flags تغییر داد. مقادیر می‌توانند هر یک از متغیرهای flags باشند و با استفاده از OR بیتی (عملگر |) ترکیب شوند.

re.escape(pattern)¶

نویسه‌های خاص در pattern را خنثی کنید. این کار زمانی مفید است که بخواهید یک رشته‌ی لفظی دلخواه را تطبیق دهید که ممکن است حاوی نویسه‌های ویژه‌ی عبارت باقاعده باشد. برای نمونه:

>>> print(re.escape('https://www.python.org'))
https://www\.python\.org

>>> legal_chars = string.ascii_lowercase + string.digits + "!#$%&'*+-.^_`|~:"
>>> print('[%s]+' % re.escape(legal_chars))
[abcdefghijklmnopqrstuvwxyz0123456789!\#\$%\&'\*\+\-\.\^_`\|\~:]+

>>> operators = ['+', '-', '*', '/', '**']
>>> print('|'.join(map(re.escape, sorted(operators, reverse=True))))
/|\-|\+|\*\*|\*

از این تابع نباید برای رشته جایگزین در sub() و subn() استفاده شود، فقط بک‌اسلش‌ها باید خنثی شوند. برای مثال:

>>> digits_re = r'\d+'
>>> sample = '/usr/sbin/sendmail - 0 errors, 12 warnings'
>>> print(re.sub(digits_re, digits_re.replace('\\', r'\\'), sample))
/usr/sbin/sendmail - \d+ errors, \d+ warnings

تغییر یافته در نسخه‌ی 3.3: نویسه‌ی '_' دیگر خنثی نمی‌شود.

تغییر یافته در نسخه‌ی 3.7: تنها نویسه‌هایی که می‌توانند در یک عبارت باقاعده معنای خاصی داشته باشند، خنثی می‌شوند. در نتیجه، '!'، '"'، '%'، "'"، ','، '/'، ':'، ';'، '<'، '='، '>'، '@' و "`" دیگر خنثی نمی‌شوند.

re.purge()¶

نهانگاه عبارت باقاعده را پاک می‌کند.

استثناها¶

exception re.PatternError(msg, pattern=None, pos=None)¶

استثنایی که هنگامی پرتاب می‌شود که رشته‌ای به یکی از توابع اینجا داده شود و یک عبارت باقاعده معتبر نباشد (برای مثال، ممکن است شامل پرانتزهای جفت‌نشده باشد) یا زمانی که خطای دیگری در حین کامپایل یا تطبیق رخ دهد. اگر رشته‌ای هیچ تطبیقی برای یک الگو نداشته باشد، هرگز خطا محسوب نمی‌شود. نمونه PatternError دارای ویژگی‌های اضافی زیر است:

msg¶

پیام خطای قالب‌بندی‌نشده.

pattern¶

الگوی عبارت باقاعده.

pos¶

اندیسی در pattern که کامپایل در آن ناموفق بود (ممکن است None باشد).

lineno¶

سطر متناظر با pos (ممکن است None باشد).

colno¶

ستون متناظر با pos (ممکن است None باشد).

تغییر یافته در نسخه‌ی 3.5: ویژگی‌های بیشتری اضافه شد.

تغییر یافته در نسخه‌ی 3.13: PatternError در ابتدا با نام error نام‌گذاری شده بود؛ این نام برای سازگاری با نسخه‌های پیشین به‌عنوان یک نام مستعار حفظ شده است.

بررسی برای یک جفت¶

در این مثال، از تابع کمکی زیر استفاده می‌کنیم تا اشیای تطبیق (match objects) را کمی مناسب‌تر نمایش دهیم:

def displaymatch(match):
    if match is None:
        return None
    return '<Match: %r, groups=%r>' % (match.group(), match.groups())

فرض کنید در حال نوشتن یک برنامه پوکر هستید که در آن دست یک بازیکن به‌صورت یک رشته ۵ نویسه‌ای نمایش داده می‌شود و هر نویسه نمایانگر یک کارت است: "a" برای آس، "k" برای شاه، "q" برای بی‌بی، "j" برای سرباز، "t" برای ۱۰، و "2" تا "9" نمایانگر کارتی با همان مقدار.

برای بررسی اینکه آیا یک رشته‌ی داده‌شده یک دست معتبر است، می‌توانید کار زیر را انجام دهید:

>>> valid_hand_re = re.compile(r"^[a2-9tjqk]{5}$")
>>> displaymatch(valid_hand_re.search("akt5q"))  # معتبر.
"<Match: 'akt5q', groups=()>"
>>> displaymatch(valid_hand_re.search("akt5e"))  # نامعتبر.
>>> displaymatch(valid_hand_re.search("akt"))    # نامعتبر.
>>> displaymatch(valid_hand_re.search("727ak"))  # معتبر.
"<Match: '727ak', groups=()>"

آن دست آخر، "727ak"، شامل یک جفت، یا دو کارت با ارزش یکسان بود. برای تطبیق این موضوع با یک عبارت باقاعده، می‌توان از بازارجاع‌ها (backreferences) به این شکل استفاده کرد:

>>> pair_re = re.compile(r".*(.).*\1")
>>> displaymatch(pair_re.prefixmatch("717ak"))     # جفت از ۷ها.
"<Match: '717', groups=('7',)>"
>>> displaymatch(pair_re.prefixmatch("718ak"))     # بدون جفت.
>>> displaymatch(pair_re.prefixmatch("354aa"))     # جفت از آس‌ها.
"<Match: '354aa', groups=('a',)>"

برای فهمیدن این که یک جفت از چه کارتی تشکیل شده است، می‌توانید از متد group() شیء تطابق به شکل زیر استفاده کنید:

>>> pair_re = re.compile(r".*(.).*\1")
>>> pair_re.prefixmatch("717ak").group(1)
'7'

# خطا به این دلیل که prefixmatch() مقدار None را برمی‌گرداند که متد group() را ندارد:
>>> pair_re.prefixmatch("718ak").group(1)
Traceback (most recent call last):
  File "<pyshell#23>", line 1, in <module>
    pair_re.prefixmatch("718ak").group(1)
AttributeError: 'NoneType' object has no attribute 'group'

>>> pair_re.prefixmatch("354aa").group(1)
'a'

شبیه‌سازی scanf()¶

پایتون در حال حاضر معادلی برای scanf() ندارد. عبارات باقاعده معمولاً از رشته‌های قالب scanf() قدرتمندتر هستند، هرچند پرجزئیات‌تر نیز می‌باشند. جدول زیر چند نگاشت کم‌وبیش معادل میان نشانه‌های قالب scanf() و عبارات باقاعده ارائه می‌دهد.

برای استخراج نام پرونده و اعداد از یک رشته مانند:

/usr/sbin/sendmail - 0 errors, 4 warnings

می‌توانید از قالب scanf() مانند زیر استفاده کنید:

%s - %d errors, %d warnings

عبارت باقاعده‌ی معادل به شکل زیر خواهد بود:

(\S+) - (\d+) errors, (\d+) warnings

تابع search() در برابر prefixmatch()¶

پایتون عملیات‌های اولیه‌ی مختلفی را بر پایه‌ی عبارات باقاعده ارائه می‌دهد:

• re.prefixmatch() وجود تطابق را تنها در ابتدای رشته بررسی می‌کند

• re.search() وجود تطابق در هر جای رشته را بررسی می‌کند (Perl به‌طور پیش‌فرض همین کار را انجام می‌دهد).

• re.fullmatch() بررسی می‌کند که کل رشته تطابق داشته باشد

برای مثال:

>>> re.prefixmatch("c", "abcdef")  # بدون تطابق
>>> re.search("c", "abcdef")       # تطابق
<re.Match object; span=(2, 3), match='c'>
>>> re.fullmatch("p.*n", "python") # تطابق
<re.Match object; span=(0, 6), match='python'>
>>> re.fullmatch("r.*n", "python") # بدون تطابق

عبارت‌های باقاعده‌ای که با '^' شروع می‌شوند را می‌توان همراه با search() برای محدود کردن تطابق به ابتدای رشته استفاده کرد:

>>> re.prefixmatch("c", "abcdef")  # No match
>>> re.search("^c", "abcdef")      # No match
>>> re.search("^a", "abcdef")      # Match
<re.Match object; span=(0, 1), match='a'>

با این حال، توجه داشته باشید که در حالت MULTILINE تابع prefixmatch() تنها در ابتدای رشته مطابقت پیدا می‌کند، در حالی که استفاده از search() با یک عبارت باقاعده که با '^' شروع می‌شود، در ابتدای هر سطر مطابقت خواهد داشت.

>>> re.prefixmatch("X", "A\nB\nX", re.MULTILINE)  # No match
>>> re.search("^X", "A\nB\nX", re.MULTILINE)  # Match
<re.Match object; span=(4, 5), match='X'>

توابع prefixmatch() در برابر match()¶

چرا تابع و متد match() به نفع املای طولانی‌تر prefixmatch() توصیه نمی‌شود؟

از زمانی که عبارات باقاعده به پایتون اضافه شدند، بسیاری از زبان‌های دیگر کتابخانه‌های پشتیبانی از عبارات باقاعده را دریافت کرده‌اند. با این حال، در محبوب‌ترین آن‌ها، از اصطلاح match در APIهای خود استفاده می‌کنند تا به رفتار بدون لنگر ارجاع دهند که در پایتون توسط search() فراهم شده است. بنابراین، استفاده از اصطلاح ساده‌ی match ممکن است برای کسانی که به زبان‌های دیگر عادت دارند و با واگرایی API پایتون از آنچه به هنجار صنعت تبدیل شده است آشنا نیستند، هنگام خواندن یا نوشتن کد نامفهوم باشد.

به نقل از ذن پایتون (python3 -m this): "صریح بودن بهتر از ضمنی بودن است". هر کسی که نام prefixmatch() را می‌خواند احتمالاً معناشناسی مورد نظر را درک خواهد کرد. هنگام خواندن match() همچنان بذر تردیدی درباره‌ی رفتار مورد نظر برای هر کسی که از پیش با این تله‌ی قدیمی پایتون آشنا نیست، باقی می‌ماند.

ما قصد نداریم نام قدیمی‌تر match() را حذف کنیم، زیرا بیش از ۳۰ سال است که در کد استفاده می‌شود. این نام به صورت منسوخ نرم درآمده است: کدهایی که از نسخه‌های قدیمی‌تر پایتون پشتیبانی می‌کنند باید به استفاده از match() ادامه دهند، در حالی که کدهای جدید باید prefixmatch() را ترجیح دهند.

ساخت یک دفترچه تلفن¶

split() یک رشته را به فهرستی جداشده با الگوی داده‌شده تقسیم می‌کند. این متد برای تبدیل داده‌های متنی به ساختارهای داده‌ای که به‌راحتی توسط پایتون قابل خواندن و اصلاح هستند، بسیار ارزشمند است؛ همان‌طور که در مثال زیر که یک دفترچه تلفن ایجاد می‌کند، نشان داده شده است.

ابتدا، ورودی در اینجا آمده است. معمولاً ممکن است از یک پرونده آمده باشد، در اینجا از سینتکس رشته سه‌نقل‌قولی استفاده می‌کنیم

>>> text = """Ross McFluff: 834.345.1254 155 Elm Street
...
... Ronald Heathmore: 892.345.3428 436 Finley Avenue
... Frank Burger: 925.541.7625 662 South Dogwood Way
...
...
... Heather Albrecht: 548.326.4584 919 Park Place"""

مدخل‌ها با یک یا چند سطر جدید از هم جدا شده‌اند. اکنون رشته را به فهرستی تبدیل می‌کنیم که در آن هر خط غیرخالی مدخل جداگانه‌ی خود را دارد:

>>> entries = re.split("\n+", text)
>>> entries
['Ross McFluff: 834.345.1254 155 Elm Street',
'Ronald Heathmore: 892.345.3428 436 Finley Avenue',
'Frank Burger: 925.541.7625 662 South Dogwood Way',
'Heather Albrecht: 548.326.4584 919 Park Place']

در نهایت، هر ورودی را به فهرستی شامل نام، نام خانوادگی، شماره تلفن و نشانی تفکیک کنید. ما از پارامتر maxsplit در split() استفاده می‌کنیم، زیرا نشانی حاوی فاصله‌ها، یعنی الگوی تفکیک ما، است:

>>> [re.split(":? ", entry, maxsplit=3) for entry in entries]
[['Ross', 'McFluff', '834.345.1254', '155 Elm Street'],
['Ronald', 'Heathmore', '892.345.3428', '436 Finley Avenue'],
['Frank', 'Burger', '925.541.7625', '662 South Dogwood Way'],
['Heather', 'Albrecht', '548.326.4584', '919 Park Place']]

الگوی :? دونقطه‌ی پس از نام خانوادگی را تطبیق می‌دهد، به‌طوری که این دونقطه در فهرست نتیجه ظاهر نمی‌شود. با maxsplit برابر 4، می‌توانیم شماره‌ی خانه را از نام خیابان جدا کنیم:

>>> [re.split(":? ", entry, maxsplit=4) for entry in entries]
[['Ross', 'McFluff', '834.345.1254', '155', 'Elm Street'],
['Ronald', 'Heathmore', '892.345.3428', '436', 'Finley Avenue'],
['Frank', 'Burger', '925.541.7625', '662', 'South Dogwood Way'],
['Heather', 'Albrecht', '548.326.4584', '919', 'Park Place']]

پردازش متن¶

sub() هر رخداد از یک الگو را با یک رشته یا نتیجه‌ی یک تابع جایگزین می‌کند. این مثال استفاده از sub() را با یک تابع برای دگرگون‌سازی (munge) متن، یا تصادفی کردن ترتیب همه‌ی نویسه‌های هر واژه از یک جمله به‌جز نخستین و آخرین نویسه نشان می‌دهد:

>>> def repl(m):
...     inner_word = list(m.group(2))
...     random.shuffle(inner_word)
...     return m.group(1) + "".join(inner_word) + m.group(3)
...
>>> text = "Professor Abdolmalek, please report your absences promptly."
>>> re.sub(r"(\w)(\w+)(\w)", repl, text)
'Poefsrosr Aealmlobdk, pslaee reorpt your abnseces plmrptoy.'
>>> re.sub(r"(\w)(\w+)(\w)", repl, text)
'Pofsroser Aodlambelk, plasee reoprt yuor asnebces potlmrpy.'

یافتن تمام قیدها¶

findall() همه رخدادهای یک الگو را تطبیق می‌دهد، نه فقط اولین رخداد را آن‌گونه که search() انجام می‌دهد. برای مثال، اگر نویسنده‌ای بخواهد همه قیدها را در متنی پیدا کند، ممکن است از findall() به شکل زیر استفاده کند:

>>> text = "He was carefully disguised but captured quickly by police."
>>> re.findall(r"\w+ly\b", text)
['carefully', 'quickly']

یافتن تمام قیدها و موقعیت‌های آن‌ها¶

اگر کسی بخواهد اطلاعات بیشتری درباره‌ی همه‌ی تطبیق‌های یک الگو فراتر از متن تطبیق‌یافته داشته باشد، finditer() مفید است، زیرا به‌جای رشته‌ها، اشیای Match را فراهم می‌کند. در ادامه‌ی مثال پیشین، اگر نویسنده‌ای بخواهد همه‌ی قیدها و موقعیت‌های آن‌ها را در متنی بیابد، از finditer() به شیوه‌ی زیر استفاده می‌کند:

>>> text = "He was carefully disguised but captured quickly by police."
>>> for m in re.finditer(r"\w+ly\b", text):
...     print('%02d-%02d: %s' % (m.start(), m.end(), m.group(0)))
07-16: carefully
40-47: quickly

نمادگذاری رشته‌ی خام¶

نمادگذاری رشته‌ی خام (r"text") عبارت‌های باقاعده را قابل‌مدیر نگه می‌دارد. بدون آن، برای خنثی کردن هر بک‌اسلش ('\') در یک عبارت باقاعده باید پیش از آن یک بک‌اسلش دیگر قرار داد. برای مثال، دو خط کد زیر از نظر عملکرد یکسان هستند:

>>> re.search(r"\W(.)\1\W", " ff ")
<re.Match object; span=(0, 4), match=' ff '>
>>> re.search("\\W(.)\\1\\W", " ff ")
<re.Match object; span=(0, 4), match=' ff '>

وقتی می‌خواهید یک بک‌اسلش لفظی را تطبیق دهید، باید آن را در عبارت باقاعده خنثی کنید. با نمادگذاری رشته خام، این به معنای r"\\" است. بدون نمادگذاری رشته خام، باید از "\\\\" استفاده کنید، که سطرهای کد زیر را از نظر عملکردی یکسان می‌کند:

>>> re.search(r"\\", r"\\")
<re.Match object; span=(0, 1), match='\\'>
>>> re.search("\\\\", r"\\")
<re.Match object; span=(0, 1), match='\\'>

نوشتن یک توکن‌ساز¶

یک توکن‌ساز (tokenizer) یا اسکنر (scanner) رشته‌ای را تحلیل می‌کند تا گروه‌هایی از نویسه‌ها را دسته‌بندی کند. این نخستین گام مفید در نوشتن یک کامپایلر یا مفسر است.

دسته‌های متن با عبارات باقاعده مشخص می‌شوند. روش کار این است که آن‌ها را در یک عبارت باقاعده‌ی اصلی واحد ترکیب کنید و روی تطابق‌های متوالی حلقه بزنید:

from typing import NamedTuple
import re

class Token(NamedTuple):
    type: str
    value: int | float | str
    line: int
    column: int

def tokenize(code):
    keywords = {'IF', 'THEN', 'ENDIF', 'FOR', 'NEXT', 'GOSUB', 'RETURN'}
    token_specification = [
        ('NUMBER',   r'\d+(\.\d*)?'),  # Integer or decimal number
        ('ASSIGN',   r':='),           # Assignment operator
        ('END',      r';'),            # Statement terminator
        ('ID',       r'[A-Za-z]+'),    # Identifiers
        ('OP',       r'[+\-*/]'),      # Arithmetic operators
        ('NEWLINE',  r'\n'),           # Line endings
        ('SKIP',     r'[ \t]+'),       # Skip over spaces and tabs
        ('MISMATCH', r'.'),            # Any other character
    ]
    tok_regex = '|'.join('(?P<%s>%s)' % pair for pair in token_specification)
    line_num = 1
    line_start = 0
    for mo in re.finditer(tok_regex, code):
        kind = mo.lastgroup
        value = mo.group()
        column = mo.start() - line_start
        if kind == 'NUMBER':
            value = float(value) if '.' in value else int(value)
        elif kind == 'ID' and value in keywords:
            kind = value
        elif kind == 'NEWLINE':
            line_start = mo.end()
            line_num += 1
            continue
        elif kind == 'SKIP':
            continue
        elif kind == 'MISMATCH':
            raise RuntimeError(f'{value!r} unexpected on line {line_num}')
        yield Token(kind, value, line_num, column)

statements = '''
    IF quantity THEN
        total := total + price * quantity;
        tax := price * 0.05;
    ENDIF;
'''

for token in tokenize(statements):
    print(token)

توکن‌ساز (tokenizer) خروجی زیر را تولید می‌کند:

Token(type='IF', value='IF', line=2, column=4)
Token(type='ID', value='quantity', line=2, column=7)
Token(type='THEN', value='THEN', line=2, column=16)
Token(type='ID', value='total', line=3, column=8)
Token(type='ASSIGN', value=':=', line=3, column=14)
Token(type='ID', value='total', line=3, column=17)
Token(type='OP', value='+', line=3, column=23)
Token(type='ID', value='price', line=3, column=25)
Token(type='OP', value='*', line=3, column=31)
Token(type='ID', value='quantity', line=3, column=33)
Token(type='END', value=';', line=3, column=41)
Token(type='ID', value='tax', line=4, column=8)
Token(type='ASSIGN', value=':=', line=4, column=12)
Token(type='ID', value='price', line=4, column=15)
Token(type='OP', value='*', line=4, column=21)
Token(type='NUMBER', value=0.05, line=4, column=23)
Token(type='END', value=';', line=4, column=27)
Token(type='ENDIF', value='ENDIF', line=5, column=4)
Token(type='END', value=';', line=5, column=9)