pdb --- اشکال‌زدای پایتون

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

---

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

اشکال‌زدا قابل گسترش است -- در واقع به‌عنوان کلاس Pdb تعریف شده است. این مورد در حال حاضر مستند نشده است اما با خواندن کد منبع به‌راحتی قابل درک است. رابط گسترش از ماژول‌های bdb و cmd استفاده می‌کند.

همچنین ملاحظه نمائید

ماژول faulthandler

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

ماژول traceback

رابط استاندارد برای استخراج، قالب‌بندی و چاپ ردگیری پشته برنامه‌های پایتون.

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

import pdb; pdb.set_trace()

یا:

breakpoint()

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

تغییر یافته در نسخه‌ی 3.7: می‌توانید از breakpoint() توکار، وقتی با مقادیر پیش‌فرض فراخوانی شود، به‌جای import pdb; pdb.set_trace() استفاده کنید.

def double(x):
   breakpoint()
   return x * 2
val = 3
print(f"{val} * 2 is {double(val)}")

اعلان اشکال‌زدا (Pdb) است، که نشانگر این است که شما در حالت اشکال‌زدایی هستید:

...(2)double()
-> breakpoint()
(Pdb) p x
3
(Pdb) continue
3 * 2 is 6

تغییر یافته در نسخه‌ی 3.3: تکمیل با Tab از طریق ماژول readline برای دستورات و آرگومان‌های دستور در دسترس است؛ برای مثال، نام‌های سراسری و محلی فعلی به‌عنوان آرگومان‌های دستور p پیشنهاد می‌شوند.

رابط خط فرمان

همچنین می‌توانید pdb را از خط فرمان برای اشکال‌زدایی از اسکریپت‌های دیگر فراخوانی کنید. برای مثال:

python -m pdb [-c command] (-m module | -p pid | pyfile) [args ...]

هنگامی که pdb به‌عنوان یک ماژول فراخوانی شود، اگر برنامه‌ای که در حال اشکال‌زدایی آن است به‌صورت غیرعادی خارج شود، pdb به‌طور خودکار وارد اشکال‌زدایی پس از خاتمه (post-mortem debugging) می‌شود. پس از اشکال‌زدایی پس از خاتمه (یا پس از خروج عادی برنامه)، pdb برنامه را مجدداً راه‌اندازی می‌کند. راه‌اندازی مجدد خودکار، وضعیت pdb (مانند نقاط شکست) را حفظ می‌کند و در بیشتر موارد مفیدتر از خروج از اشکال‌زدا هنگام خروج برنامه است.

-c, --command <command>

برای اجرای دستورات به‌گونه‌ای که گویی در یک پرونده .pdbrc داده شده‌اند؛ دستورات اشکال‌زدا را ببینید.

تغییر یافته در نسخه‌ی 3.2: گزینه -c افزوده شد.

-m <module>

برای اجرای ماژول‌ها به شیوه‌ای مشابه python -m. همانند یک اسکریپت، اشکال‌زدا اجرا را درست پیش از نخستین خط ماژول متوقف می‌کند.

تغییر یافته در نسخه‌ی 3.7: گزینه -m افزوده شد.

-p, --pid <pid>

به فرآیند با PID مشخص‌شده متصل شوید.

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

برای اتصال به یک فرآیند پایتون در حال اجرا جهت اشکال‌زدایی از راه دور، از گزینه -p یا --pid به‌همراه PID فرآیند هدف استفاده کنید:

python -m pdb -p 1234

توجه

اتصال به فرایندی که در یک فراخوانی سیستم مسدودشده است یا در انتظار ورودی/خروجی است، تنها زمانی کار می‌کند که دستورالعمل بایت‌کد بعدی اجرا شود یا فرایند یک سیگنال دریافت کند.

کاربرد معمول برای اجرای یک دستور تحت کنترل اشکال‌زدا به این صورت است:

>>> import pdb
>>> def f(x):
...     print(1 / x)
>>> pdb.run("f(2)")
> <string>(1)<module>()
(Pdb) continue
0.5
>>>

روش معمول برای بررسی برنامه‌ای که از کار افتاده است:

>>> import pdb
>>> def f(x):
...     print(1 / x)
...
>>> f(0)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "<stdin>", line 2, in f
ZeroDivisionError: division by zero
>>> pdb.pm()
> <stdin>(2)f()
(Pdb) p x
0
(Pdb)

تغییر یافته در نسخه‌ی 3.13: پیاده‌سازی PEP 667 به این معناست که انتساب‌های نام انجام‌شده از طریق pdb بلافاصله بر محدوده فعال تأثیر می‌گذارند، حتی هنگام اجرا در داخل یک optimized scope.

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

pdb.run(statement, globals=None, locals=None)

دستور (که به‌صورت یک رشته یا شیء کد داده شده است) را تحت کنترل اشکال‌زدا اجرا کنید. اعلان اشکال‌زدا پیش از اجرای هر کدی ظاهر می‌شود؛ می‌توانید نقطه‌های توقف را تنظیم کنید و continue را تایپ کنید، یا می‌توانید با استفاده از step یا next دستور را گام‌به‌گام اجرا کنید (تمام این دستورها در ادامه توضیح داده شده‌اند). آرگومان‌های اختیاری globals و locals محیطی را که کد در آن اجرا می‌شود مشخص می‌کنند؛ به‌طور پیش‌فرض از دیکشنری ماژول __main__ استفاده می‌شود. (به توضیح توابع توکار exec() یا eval() مراجعه کنید.)

pdb.runeval(expression, globals=None, locals=None)

عبارت (داده‌شده به‌صورت یک رشته یا یک شیء کد) را تحت کنترل اشکال‌زدا ارزیابی می‌کند. هنگامی که runeval() بازمی‌گردد، مقدار عبارت را برمی‌گرداند. در غیر این صورت، این تابع مشابه run() است.

pdb.runcall(function, *args, **kwds)

function (یک شیء تابع یا متد، نه یک رشته) را با آرگومان‌های داده‌شده فراخوانی می‌کند. هنگامی که runcall() بازمی‌گردد، هر آنچه را که فراخوانی تابع بازگردانده باشد، برمی‌گرداند. اعلان اشکال‌زدا به محض ورود به تابع ظاهر می‌شود.

pdb.set_trace(*, header=None, commands=None)

در فریم پشته‌ی فراخواننده وارد اشکال‌زدا می‌شود. این برای سخت‌کد کردن یک نقطه توقف در نقطه‌ای مشخص از برنامه مفید است، حتی اگر کد در غیر این صورت در حال اشکال‌زدایی نباشد (مثلاً هنگامی که یک ادعا شکست می‌خورد). اگر داده شود، header درست پیش از آغاز اشکال‌زدایی در کنسول چاپ می‌شود. آرگومان commands، در صورت داده شدن، فهرستی از دستورها است که هنگام شروع اشکال‌زدا اجرا می‌شوند.

تغییر یافته در نسخه‌ی 3.7: آرگومان فقط کلیدواژه‌ای header.

تغییر یافته در نسخه‌ی 3.13: set_trace() بلافاصله وارد اشکال‌زدا می‌شود، نه در خط بعدی کدی که قرار است اجرا شود.

اضافه شده در نسخه‌ی 3.14: آرگومان commands.

awaitable pdb.set_trace_async(*, header=None, commands=None)

نسخه‌ی ناهمگام از set_trace(). این تابع باید در یک تابع ناهمگام همراه با await استفاده شود.

async def f():
    await pdb.set_trace_async()

در صورتی که اشکال‌زدا توسط این تابع فراخوانی شود، دستورهای await پشتیبانی می‌شوند.

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

pdb.post_mortem(t=None)

وارد اشکال‌زدایی پس از خاتمه (post-mortem debugging) برای استثنای داده‌شده یا شیء ردگیری پشته می‌شود. اگر هیچ مقداری داده نشود، از استثنایی که در حال حاضر رسیدگی می‌شود استفاده می‌کند، یا اگر استثنایی وجود نداشته باشد، ValueError را پرتاب می‌کند.

تغییر یافته در نسخه‌ی 3.13: پشتیبانی از اشیای استثنا افزوده شد.

pdb.pm()

وارد اشکال‌زدایی پس از خاتمه (post-mortem debugging) استثنای یافت‌شده در sys.last_exc شوید.

pdb.set_default_backend(backend)

دو بک‌اند پشتیبانی‌شده برای pdb وجود دارد: 'settrace' و 'monitoring'. برای جزئیات، bdb.Bdb را ببینید. کاربر می‌تواند بک‌اند پیش‌فرض را برای استفاده در صورتی که هنگام نمونه‌سازی Pdb هیچ بک‌اندی مشخص نشده باشد، تنظیم کند. اگر هیچ بک‌اندی مشخص نشده باشد، پیش‌فرض 'settrace' است.

توجه

breakpoint() و set_trace() تحت تأثیر این تابع قرار نمی‌گیرند. آن‌ها همیشه از بک‌اند 'monitoring' استفاده می‌کنند.

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

pdb.get_default_backend()

بک‌اند پیش‌فرض pdb را برمی‌گرداند.

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

توابع run* و set_trace() نام‌های مستعاری برای نمونه‌سازی از کلاس Pdb و فراخوانی متدی با همان نام هستند. اگر می‌خواهید به امکانات بیشتری دسترسی داشته باشید، باید این کار را خودتان انجام دهید:

class pdb.Pdb(completekey='tab', stdin=None, stdout=None, skip=None, nosigint=False, readrc=True, mode=None, backend=None, colorize=False)

Pdb کلاس اشکال‌زدا است.

آرگومان‌های completekey، stdin و stdout به کلاس زیربنایی cmd.Cmd ارسال می‌شوند؛ برای توضیحات به آنجا مراجعه کنید.

آرگومان skip، در صورت داده شدن، باید پیمایش‌پذیری از الگوهای نام ماژول به‌سبک glob باشد. اشکال‌زدا به فریم‌هایی که از ماژولی منطبق با یکی از این الگوها سرچشمه می‌گیرند، وارد نخواهد شد. [1]

به‌طور پیش‌فرض، Pdb هنگامی که فرمان continue را می‌دهید، یک هندلر برای سیگنال SIGINT تنظیم می‌کند (که هنگام فشار دادن Ctrl-C در کنسول توسط کاربر ارسال می‌شود). این به شما امکان می‌دهد که با فشار دادن Ctrl-C دوباره وارد اشکال‌زدا شوید. اگر می‌خواهید Pdb هندلر SIGINT را تغییر ندهد، nosigint را روی true تنظیم کنید.

آرگومان readrc به‌طور پیش‌فرض true است و کنترل می‌کند که آیا Pdb پرونده‌های .pdbrc را از سامانه فایل‌بندی بارگذاری کند یا خیر.

آرگومان mode مشخص می‌کند که اشکال‌زدا چگونه فراخوانی شده است. این آرگومان بر نحوه کار برخی دستورهای اشکال‌زدا تأثیر می‌گذارد. مقدارهای معتبر 'inline' (که توسط تابع توکار breakpoint() استفاده می‌شود)، 'cli' (که در فراخوانی از خط فرمان استفاده می‌شود) یا None (برای رفتار سازگار با نسخه‌های پیشین، همان‌گونه که پیش از افزودن آرگومان mode وجود داشت) هستند.

آرگومان backend مشخص می‌کند که برای اشکال‌زدا از کدام بک‌اند استفاده شود. اگر None ارسال شود، از بک‌اند پیش‌فرض استفاده خواهد شد. set_default_backend() را ببینید. در غیر این صورت، بک‌اندهای پشتیبانی‌شده 'settrace' و 'monitoring' هستند.

آرگومان colorize، اگر روی True تنظیم شود، در صورت پشتیبانی از رنگ، خروجی رنگی را در اشکال‌زدا فعال می‌کند. این قابلیت کد منبع نمایش‌داده‌شده در pdb را برجسته می‌کند.

نمونه فراخوانی برای فعال‌سازی ردگیری با skip:

import pdb; pdb.Pdb(skip=['django.*']).set_trace()

یک رویداد حسابرسی pdb.Pdb را بدون آرگومان پرتاب می‌کند.

تغییر یافته در نسخه‌ی 3.1: پارامتر skip افزوده شد.

تغییر یافته در نسخه‌ی 3.2: پارامتر nosigint افزوده شد. پیش‌تر، هرگز یک هندلر SIGINT توسط Pdb تنظیم نمی‌شد.

تغییر یافته در نسخه‌ی 3.6: آرگومان readrc.

اضافه شده در نسخه‌ی 3.14: آرگومان mode افزوده شد.

اضافه شده در نسخه‌ی 3.14: آرگومان backend افزوده شد.

اضافه شده در نسخه‌ی 3.14: آرگومان colorize افزوده شد.

تغییر یافته در نسخه‌ی 3.14: نقاط توقف درون‌خطی مانند breakpoint() یا pdb.set_trace() همیشه برنامه را در فریم فراخوان متوقف می‌کنند و الگوی skip را (در صورت وجود) نادیده می‌گیرند.

run(statement, globals=None, locals=None)

runeval(expression, globals=None, locals=None)

runcall(function, *args, **kwds)

set_trace()

مستندات توابعی را که در بالا توضیح داده شد، ببینید.

دستورات اشکال‌زدا

فرمان‌های شناسایی‌شده توسط اشکال‌زدا، در زیر فهرست شده‌اند. بیشتر فرمان‌ها را می‌توان مطابق آنچه نشان داده‌شده است به یک یا دو حرف مخفف کرد؛ برای مثال h(elp) یعنی می‌توان از h یا help برای وارد کردن فرمان help استفاده کرد (اما نه he یا hel، و نه H یا Help یا HELP). آرگومان‌های فرمان‌ها باید با فضای سفید (فاصله یا تب) از هم جدا شوند. آرگومان‌های اختیاری در سینتکس فرمان داخل کروشه ([]) قرار می‌گیرند؛ نباید کروشه‌ها را تایپ کنید. موارد جایگزین در سینتکس فرمان با خط عمودی (|) از هم جدا می‌شوند.

با وارد کردن یک خط خالی، آخرین دستور واردشده تکرار می‌شود. استثنا: اگر آخرین دستور یک دستور list باشد، ۱۱ خط بعدی فهرست می‌شوند.

فرمان‌هایی که اشکال‌زدا آن‌ها را نمی‌شناسد، به‌عنوان دستورات پایتون در نظر گرفته می‌شوند و در زمینه‌ی برنامه‌ای که اشکال‌زدایی می‌شود اجرا می‌شوند. همچنین می‌توان یک علامت تعجب (!) را به‌عنوان پیشوند به دستورات پایتون اضافه کرد. این روشی قدرتمند برای بازرسی برنامه‌ای است که اشکال‌زدایی می‌شود؛ حتی امکان تغییر یک متغیر یا فراخوانی یک تابع نیز وجود دارد. هنگامی که در چنین دستوری یک استثنا رخ دهد، نام استثنا چاپ می‌شود اما وضعیت اشکال‌زدا تغییر نمی‌کند.

تغییر یافته در نسخه‌ی 3.13: عبارت‌ها/دستورهایی که پیشوند آن‌ها یک دستور pdb است، اکنون به‌درستی شناسایی و اجرا می‌شوند.

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

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

برای تنظیم یک متغیر سراسری موقت، از یک متغیر کمکی (convenience variable) استفاده کنید. متغیر کمکی متغیری است که نام آن با $ شروع می‌شود. برای مثال، $foo = 1 متغیر سراسری $foo را تنظیم می‌کند که می‌توانید در نشست اشکال‌زدا از آن استفاده کنید. متغیرهای کمکی هنگامی که برنامه اجرای خود را از سر می‌گیرد، پاک می‌شوند، بنابراین احتمال تداخل آن‌ها با برنامه شما، در مقایسه با استفاده از متغیرهای معمولی مانند foo = 1، کمتر است.

چهار متغیر کمکی از پیش تنظیم‌شده وجود دارد:

• $_frame: فریمفعلی‌ای که در حال اشکال‌زدایی آن هستید

• $_retval: مقدار بازگشتی در صورتی که فریمدر حال بازگشت باشد

• $_exception: استثنا، اگر فریم در حال پرتاب استثنا باشد

• $_asynctask: وظیفه asyncio اگر pdb در یک تابع ناهمگام متوقف شود

اضافه شده در نسخه‌ی 3.12: قابلیت متغیر سهولت‌بخش اضافه شد.

اضافه شده در نسخه‌ی 3.14: متغیر کمکی $_asynctask افزوده شد.

اگر پرونده .pdbrc در پوشه خانه کاربر یا پوشه جاری وجود داشته باشد، با کدگذاری 'utf-8' خوانده و اجرا می‌شود، گویی که در اعلان اشکال‌زدا تایپ شده باشد، با این استثنا که سطرهای خالی و سطرهایی که با # شروع می‌شوند نادیده گرفته می‌شوند. این موضوع به‌ویژه برای نام‌های مستعار مفید است. اگر هر دو پرونده وجود داشته باشند، ابتدا پرونده موجود در پوشه خانه خوانده می‌شود و پرونده محلی می‌تواند نام‌های مستعار تعریف‌شده در آن را بازنویسی کند.

تغییر یافته در نسخه‌ی 3.2: .pdbrc اکنون می‌تواند شامل دستورهایی باشد که اشکال‌زدایی را ادامه می‌دهند، مانند continue یا next. پیش از این، این دستورها اثری نداشتند.

تغییر یافته در نسخه‌ی 3.11: .pdbrc اکنون با کدگذاری 'utf-8' خوانده می‌شود. پیش‌تر، با کدگذاری locale سیستم خوانده می‌شد.

h(elp) [command]

بدون آرگومان، فهرست فرمان‌های در دسترس را چاپ می‌کند. با یک فرمان به‌عنوان آرگومان، راهنمای آن فرمان را چاپ می‌کند. help pdb مستندات کامل (docstring ماژول pdb) را نمایش می‌دهد. از آنجا که آرگومان فرمان باید یک شناسه باشد، برای دریافت راهنمای فرمان ! باید help exec وارد شود.

w(here) [count]

یک ردگیری پشته را چاپ کنید، به‌گونه‌ای که جدیدترین فریم در پایین باشد. اگر count برابر ۰ باشد، مدخل فریم فعلی را چاپ کنید. اگر count منفی باشد، قدیمی‌ترین فریم‌ها به تعداد - count را چاپ کنید. اگر count مثبت باشد، جدیدترین فریم‌ها به تعداد count را چاپ کنید. یک فلش (>) فریم فعلی را نشان می‌دهد، که زمینه‌ی بیشتر فرمان‌ها را مشخص می‌کند.

تغییر یافته در نسخه‌ی 3.14: آرگومان count اضافه شده است.

d(own) [count]

فریم جاری را count سطح (پیش‌فرض ۱) در ردگیری پشته به پایین جابه‌جا کنید (به یک فریم جدیدتر).

u(p) [count]

فریم جاری را در ردگیری پشته count سطح به بالا حرکت دهید (به‌طور پیش‌فرض یک سطح، به یک فریم قدیمی‌تر).

b(reak) [([filename:]lineno | function) [, condition]]

با آرگومان lineno، یک نقطه توقف در خط lineno در پرونده جاری تنظیم کنید. می‌توانید پیش از شماره خط، یک filename و یک دونقطه قرار دهید تا نقطه توقفی در پرونده‌ای دیگر مشخص شود (احتمالاً پرونده‌ای که هنوز بارگذاری نشده است). پرونده در sys.path جستجو می‌شود. شکل‌های قابل‌قبول برای filename عبارتند از /abspath/to/file.py، relpath/file.py، module و package.module.

با آرگومان function، یک نقطه توقف در نخستین دستور قابل‌اجرا در آن تابع تنظیم کنید. function می‌تواند هر عبارتی باشد که در فضای نام جاری به یک تابع ارزیابی می‌شود.

اگر آرگومان دوم وجود داشته باشد، این آرگومان عبارتی است که باید پیش از اعمال نقطه توقف (breakpoint) به مقدار درست ارزیابی شود.

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

به هر نقطه توقف یک شماره اختصاص داده می‌شود که تمام دستورات دیگر نقطه توقف به آن ارجاع می‌دهند.

tbreak [([filename:]lineno | function) [, condition]]

نقطه توقف موقتی که به‌طور خودکار پس از نخستین برخورد حذف می‌شود. آرگومان‌ها همان آرگومان‌های break هستند.

cl(ear) [filename:lineno | bpnumber ...]

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

disable bpnumber [bpnumber ...]

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

enable bpnumber [bpnumber ...]

نقاط توقف مشخص‌شده را فعال کنید.

ignore bpnumber [count]

شمار نادیده‌گرفتن را برای شماره‌ی نقطه توقف داده‌شده تنظیم کنید. اگر count حذف شود، شمار نادیده‌گرفتن روی ۰ تنظیم می‌شود. یک نقطه توقف زمانی فعال می‌شود که شمار نادیده‌گرفتن صفر باشد. وقتی غیرصفر باشد، هر بار که به نقطه توقف رسیده شود و نقطه توقف غیرفعال نباشد و هر شرط مرتبط به‌صورت درست ارزیابی شود، count کاهش می‌یابد.

condition bpnumber [condition]

یک شرط جدید برای نقطه توقف تنظیم کنید، عبارتی که باید پیش از اجرای نقطه توقف به مقدار درست ارزیابی شود. اگر شرط ذکر نشده باشد، هر شرط موجود حذف می‌شود؛ یعنی نقطه توقف بی‌شرط می‌شود.

commands [bpnumber]

فهرستی از دستورات را برای نقطه توقف شماره bpnumber مشخص کنید. خود دستورات در سطرهای بعدی ظاهر می‌شوند. برای پایان دادن به دستورات، خطی را وارد کنید که فقط شامل end باشد. یک مثال:

(Pdb) commands 1
(com) p some_variable
(com) end
(Pdb)

برای حذف همه‌ی دستورات از یک نقطه توقف، commands را وارد کنید و بلافاصله پس از آن end را وارد کنید؛ یعنی هیچ دستوری ندهید.

بدون آرگومان bpnumber، commands به آخرین نقطه توقف تنظیم‌شده اشاره می‌کند.

می‌توانید از دستورهای نقطه توقف برای شروع دوباره برنامه خود استفاده کنید. کافی است از دستور continue، یا step، یا هر دستور دیگری که اجرا را از سر می‌گیرد، استفاده کنید.

مشخص کردن هر فرمانی که اجرا را از سر می‌گیرد (در حال حاضر continue، step، next، return، until، jump، quit و مخفف‌های آن‌ها) به فهرست فرمان‌ها پایان می‌دهد (گویی بلافاصله پس از آن فرمان end آمده است). این به این دلیل است که هر زمان که اجرا را از سر بگیرید (حتی با یک next یا step ساده)، ممکن است با نقطه توقف دیگری مواجه شوید—که ممکن است فهرست فرمان‌های خودش را داشته باشد و به ابهام‌هایی درباره‌ی این‌که کدام فهرست اجرا شود منجر شود.

اگر فهرست فرمان‌ها شامل فرمان silent یا فرمانی باشد که اجرا را از سر می‌گیرد، پیام نقطه توقف حاوی اطلاعات مربوط به فریمنمایش داده نمی‌شود.

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

s(tep)

خط فعلی را اجرا کنید و در اولین فرصت ممکن متوقف شوید (چه در تابعی که فراخوانی می‌شود، چه در خط بعدی در تابع فعلی).

n(ext)

اجرا را تا رسیدن به خط بعدی در تابع فعلی یا بازگشت آن ادامه دهید. (تفاوت بین next و step این است که step در داخل یک تابع فراخوانی‌شده متوقف می‌شود، در حالی که next توابع فراخوانی‌شده را با سرعت (تقریباً) کامل اجرا می‌کند و فقط در خط بعدی در تابع فعلی متوقف می‌شود.)

unt(il) [lineno]

بدون آرگومان، اجرا را تا رسیدن به خطی با شماره‌ای بزرگ‌تر از شماره فعلی ادامه می‌دهد.

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

تغییر یافته در نسخه‌ی 3.2: امکان مشخص کردن شماره خط به‌صورت صریح.

r(eturn)

اجرا را تا زمانی که تابع فعلی بازگشت کند، ادامه دهید.

c(ont(inue))

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

j(ump) lineno

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

باید توجه داشت که هر پرشی مجاز نیست -- برای مثال، پرش به وسط یک حلقه for یا به بیرون از یک بند finally ممکن نیست.

l(ist) [first[, last]]

کد منبع پرونده جاری را فهرست می‌کند. بدون آرگومان، ۱۱ خط اطراف خط جاری را فهرست می‌کند یا فهرست قبلی را ادامه می‌دهد. با . به‌عنوان آرگومان، ۱۱ خط اطراف خط جاری را فهرست می‌کند. با یک آرگومان، ۱۱ خط اطراف آن خط را فهرست می‌کند. با دو آرگومان، محدوده داده‌شده را فهرست می‌کند؛ اگر آرگومان دوم کمتر از آرگومان اول باشد، به‌عنوان تعداد تفسیر می‌شود.

خط فعلی در فریمفعلی با -> مشخص می‌شود. اگر یک استثنا در حال اشکال‌زدایی باشد، خطی که استثنا در آن ابتدا پرتاب یا منتشر شده است، در صورتی که با خط فعلی متفاوت باشد، با >> مشخص می‌شود.

تغییر یافته در نسخه‌ی 3.2: نشانگر >> افزوده شد.

ll | longlist

تمام کد منبع برای تابع یا فریمجاری را فهرست می‌کند. سطرهای قابل‌توجه همانند list علامت‌گذاری می‌شوند.

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

a(rgs)

آرگومان‌های تابع جاری و مقادیر فعلی آن‌ها را چاپ می‌کند.

p expression

expression را در زمینه‌ی فعلی ارزیابی کنید و مقدار آن را چاپ کنید.

توجه

همچنین می‌توان از print() استفاده کرد، اما این یک دستور اشکال‌زدا نیست — این کار تابع print() پایتون را اجرا می‌کند.

pp expression

مانند دستور p، با این تفاوت که مقدار عبارت با استفاده از ماژول pprint زیبانویسی می‌شود.

whatis expression

نوع عبارت را چاپ کنید.

source expression

سعی می‌کند کد منبع عبارت را به‌دست آورد و آن را نمایش دهد.

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

display [expression]

مقدار عبارت را در صورت تغییر، هر بار که اجرا در فریم جاری متوقف می‌شود، نمایش دهید.

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

توجه

Display عبارت را ارزیابی می‌کند و آن را با نتیجه‌ی ارزیابی پیشین عبارت مقایسه می‌کند، بنابراین وقتی نتیجه تغییرپذیر باشد، display ممکن است نتواند تغییرات را تشخیص دهد.

مثال:

lst = []
breakpoint()
pass
lst.append(1)
print(lst)

خروجی متوجه نخواهد شد که lst تغییر کرده است، زیرا نتیجه‌ی ارزیابی پیش از آن‌که مقایسه شود، به‌وسیله‌ی lst.append(1) به‌صورت درجا تغییر می‌یابد:

example.py(3)<module>()
-> pass
(Pdb) display lst
display lst: []
(Pdb) n
> example.py(4)<module>()
-> lst.append(1)
(Pdb) n
> example.py(5)<module>()
-> print(lst)
(Pdb)

می‌توانید با استفاده از چند ترفند در سازوکار کپی، آن را به‌کار بیندازید:

example.py(3)<module>()
-> pass
(Pdb) display lst[:]
display lst[:]: []
(Pdb) n
> example.py(4)<module>()
-> lst.append(1)
(Pdb) n
> example.py(5)<module>()
-> print(lst)
display lst[:]: [1]  [old: []]
(Pdb)

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

undisplay [expression]

دیگر عبارت را در فریم فعلی نمایش ندهید. بدون عبارت، تمام عبارت‌های نمایشی را برای فریم فعلی پاک کنید.

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

interact

یک مفسر تعاملی را (با استفاده از ماژول code) در یک فضای نام سراسری جدید که از فضای نام های محلی و سراسری محدوده فعلی مقداردهی اولیه شده است، راه‌اندازی کنید. برای خروج از مفسر و بازگشت به اشکال‌زدا، از exit() یا quit() استفاده کنید.

توجه

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

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

تغییر یافته در نسخه‌ی 3.13: برای خروج از دستور interact می‌توانید از exit() و quit() استفاده کنید.

تغییر یافته در نسخه‌ی 3.13: interact خروجی خود را به‌جای sys.stderr به کانال خروجی اشکال‌زدا هدایت می‌کند.

alias [name [command]]

یک نام مستعار به نام name ایجاد کنید که command را اجرا می‌کند. command نباید داخل علامت‌های نقل‌قول قرار گیرد. پارامترهای جایگزین‌پذیر را می‌توان با %1، %2، ... و %9 مشخص کرد، در حالی که %* با تمام پارامترها جایگزین می‌شود. اگر command ذکر نشود، نام مستعار فعلی برای name نمایش داده می‌شود. اگر هیچ آرگومانی داده نشود، همه نام‌های مستعار فهرست می‌شوند.

نام‌های مستعار ممکن است تودرتو باشند و می‌توانند شامل هر چیزی باشند که بتوان آن را به‌صورت مجاز در خط فرمان pdb وارد کرد. توجه داشته باشید که دستورات داخلی pdb می‌توانند توسط نام‌های مستعار جایگزین شوند. چنین دستوری سپس تا حذف نام مستعار پنهان می‌ماند. جایگزینی نام مستعار به‌صورت بازگشتی بر نخستین کلمه خط فرمان اعمال می‌شود؛ تمام کلمات دیگر خط دست‌نخورده باقی می‌مانند.

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

# Print instance variables (usage "pi classInst")
alias pi for k in %1.__dict__.keys(): print(f"%1.{k} = {%1.__dict__[k]}")
# Print instance variables in self
alias ps pi self

unalias name

نام مستعار مشخص‌شده name را حذف کنید.

! statement

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

(Pdb) ! n=42
(Pdb)

برای تنظیم یک متغیر سراسری، می‌توانید یک دستور global را در همان خط پیش از دستور انتساب قرار دهید، برای مثال:

(Pdb) global list_options; list_options = ['-l']
(Pdb)

run [args ...]

restart [args ...]

برنامه پایتون در حال اشکال‌زدایی را دوباره اجرا کنید. اگر args ارائه شود، با shlex تجزیه می‌شود و نتیجه به‌عنوان sys.argv جدید استفاده می‌شود. تاریخچه، نقاط توقف، اقدامات و گزینه‌های اشکال‌زدا حفظ می‌شوند. restart نام مستعاری برای run است.

تغییر یافته در نسخه‌ی 3.14: دستورات run و restart هنگامی که اشکال‌زدا در حالت 'inline' فراخوانی می‌شود، غیرفعال هستند.

q(uit)

از اشکال‌زدا خارج شوید. برنامه‌ای که در حال اجرا است، خاتمه داده می‌شود. ورودی پایان پرونده معادل quit است.

اگر اشکال‌زدا در حالت 'inline' فراخوانی شود، یک پیام تأیید نمایش داده خواهد شد. هر یک از y، Y، <Enter> یا EOF خروج را تأیید می‌کند.

تغییر یافته در نسخه‌ی 3.14: اگر اشکال‌زدا در حالت 'inline' فراخوانی شود، یک اعلان تأیید نمایش داده خواهد شد. پس از تأیید، اشکال‌زدا بلافاصله sys.exit() را فراخوانی می‌کند، به‌جای اینکه bdb.BdbQuit را در رویداد ردگیری بعدی پرتاب کند.

debug code

وارد یک اشکال‌زدای بازگشتی شوید که code را گام‌به‌گام اجرا می‌کند (که یک عبارت یا دستور دلخواه برای اجرا در محیط فعلی است).

retval

مقدار بازگشتی آخرین return تابع جاری را چاپ می‌کند.

exceptions [excnumber]

فهرست یا پرش میان استثناهای زنجیره‌ای.

هنگام استفاده از pdb.pm() یا Pdb.post_mortem(...) با یک استثنای زنجیره‌ای به‌جای ردگیری پشته، به کاربر امکان داده می‌شود که با استفاده از دستور exceptions برای فهرست کردن استثناها و exceptions <number> برای تغییر به آن استثنا، بین استثناهای زنجیره‌ای جابه‌جا شود.

مثال:

def out():
    try:
        middle()
    except Exception as e:
        raise ValueError("reraise middle() error") from e

def middle():
    try:
        return inner(0)
    except Exception as e:
        raise ValueError("Middle fail")

def inner(x):
    1 / x

out()

فراخوانی pdb.pm() به شما امکان می‌دهد بین استثناها جابه‌جا شوید:

example.py(5)out()
-> raise ValueError("reraise middle() error") from e

(Pdb) exceptions
  0 ZeroDivisionError('division by zero')
  1 ValueError('Middle fail')
> 2 ValueError('reraise middle() error')

(Pdb) exceptions 0
> example.py(16)inner()
-> 1 / x

(Pdb) up
> example.py(10)middle()
-> return inner(0)

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

پانویس‌ها

[1]

این‌که یک فریممنشأگرفته از یک ماژول خاص در نظر گرفته شود، با __name__ در سراسری‌های فریم تعیین می‌شود.