ثبت و استفاده از ابزارها¶

sys.monitoring.use_tool_id(tool_id: int, name: str, /) → None¶

باید پیش از آنکه بتوان از tool_id استفاده کرد، فراخوانی شود. tool_id باید در بازه‌ی ۰ تا ۵ باشد (شامل ۰ و ۵). اگر tool_id در حال استفاده باشد، یک ValueError پرتاب می‌شود.

sys.monitoring.clear_tool_id(tool_id: int, /) → None¶

ثبت تمام رویدادها و توابع کال‌بک مرتبط با tool_id را لغو می‌کند.

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

sys.monitoring.free_tool_id(tool_id: int, /) → None¶

باید هنگامی فراخوانی شود که یک ابزار دیگر به tool_id نیازی ندارد. پیش از آزادسازی tool_id، clear_tool_id() را فراخوانی می‌کند.

تغییر یافته در نسخه‌ی 3.14: اکنون قبل از آزادسازی tool_id تابع clear_tool_id() را فراخوانی می‌کند. پیش از این، رویدادهای سراسری یا محلی مرتبط با tool_id غیرفعال نمی‌شدند، و هیچ تابع کال‌بکی ثبت‌حذف نمی‌شد.

sys.monitoring.get_tool(tool_id: int, /) → str | None¶

اگر tool_id در حال استفاده باشد، نام ابزار را برمی‌گرداند؛ در غیر این صورت None را برمی‌گرداند. tool_id باید در بازه‌ی ۰ تا ۵ (شامل هر دو) باشد.

ماشین مجازی (VM) همه‌ی شناسه‌ها را از نظر رویدادها یکسان در نظر می‌گیرد، اما شناسه‌های زیر از پیش تعریف‌شده‌اند تا همکاری ابزارها آسان‌تر شود:

sys.monitoring.DEBUGGER_ID = 0
sys.monitoring.COVERAGE_ID = 1
sys.monitoring.PROFILER_ID = 2
sys.monitoring.OPTIMIZER_ID = 5

رویدادهای محلی¶

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

• PY_START

• PY_RESUME

• PY_RETURN

• PY_YIELD

• CALL

• LINE

• INSTRUCTION

• JUMP

• BRANCH_LEFT

• BRANCH_RIGHT

• STOP_ITERATION

رویداد منسوخ¶

• BRANCH

رویداد BRANCH در 3.14 منسوخ شده است. استفاده از رویدادهای BRANCH_LEFT و BRANCH_RIGHT عملکرد بسیار بهتری خواهد داشت، زیرا می‌توان آن‌ها را به‌طور مستقل غیرفعال کرد.

رویدادهای جانبی¶

رویدادهای کمکی را می‌توان مانند سایر رویدادها پایش کرد، اما توسط رویداد دیگری کنترل می‌شوند:

• C_RAISE

• C_RETURN

رویدادهای C_RETURN و C_RAISE توسط رویداد CALL کنترل می‌شوند. رویدادهای C_RETURN و C_RAISE تنها در صورتی مشاهده می‌شوند که رویداد CALL متناظر پایش شود.

رویدادهای دیگر¶

سایر رویدادها لزوماً به مکان خاصی در برنامه گره نخورده‌اند و نمی‌توان آن‌ها را به صورت فردی به ازای هر مکان غیرفعال کرد.

رویدادهای دیگری که می‌توان آن‌ها را پایش کرد عبارتند از:

• PY_THROW

• PY_UNWIND

• RAISE

• EXCEPTION_HANDLED

• RERAISE

رویداد STOP_ITERATION¶

PEP 380 مشخص می‌کند که هنگام برگرداندن یک مقدار از یک تولیدگر یا هم‌روال، استثنای StopIteration پرتاب می‌شود. با این حال، این روش بسیار ناکارآمدی برای برگرداندن یک مقدار است، بنابراین برخی از پیاده‌سازی‌های پایتون، به‌ویژه CPython 3.12+، استثنایی پرتاب نمی‌کنند مگر اینکه برای کد دیگر قابل مشاهده باشد.

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

توجه داشته باشید که رویداد STOP_ITERATION و رویداد RAISE برای استثنای StopIteration معادل هستند و هنگام تولید رویدادها، به‌عنوان قابل تعویض در نظر گرفته می‌شوند. پیاده‌سازی‌ها به دلایل کارایی، STOP_ITERATION را ترجیح می‌دهند، اما ممکن است یک رویداد RAISE همراه با یک StopIteration تولید کنند.

تنظیم رویدادها به‌صورت سراسری¶

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

sys.monitoring.get_events(tool_id: int, /) → int¶

یک int بازمی‌گرداند که همه رویدادهای فعال را نشان می‌دهد.

sys.monitoring.set_events(tool_id: int, event_set: int, /) → None¶

تمام رویدادهایی را که در event_set تنظیم شده‌اند، فعال می‌کند. اگر tool_id در حال استفاده نباشد، یک ValueError پرتاب می‌کند.

هیچ رویدادی به‌طور پیش‌فرض فعال نیست.

رویدادها به‌ازای هر شیء کد¶

رویدادها را همچنین می‌توان بر اساس هر شیء کد کنترل کرد. توابع تعریف‌شده در زیر که یک types.CodeType را می‌پذیرند، باید آماده باشند تا یک شیء مشابه را از توابعی که در پایتون تعریف نشده‌اند بپذیرند (به API پایش C مراجعه کنید).

sys.monitoring.get_local_events(tool_id: int, code: CodeType, /) → int¶

تمام رویدادهای محلی برای code را برمی‌گرداند

sys.monitoring.set_local_events(tool_id: int, code: CodeType, event_set: int, /) → None¶

تمام رویدادهای محلی برای code را که در event_set تنظیم شده‌اند، فعال می‌کند. اگر tool_id در حال استفاده نباشد، یک ValueError پرتاب می‌کند.

غیرفعال‌سازی رویدادها¶

sys.monitoring.DISABLE¶

مقدار خاصی که می‌توان آن را از یک تابع کال‌بک بازگرداند تا رویدادها را برای موقعیت فعلی کد غیرفعال کند.

رویدادهای محلی را می‌توان برای یک موقعیت کد مشخص با برگرداندن sys.monitoring.DISABLE از یک تابع کال‌بک غیرفعال کرد. این کار، رویدادهای تنظیم‌شده یا سایر موقعیت‌های کد برای همان رویداد را تغییر نمی‌دهد.

سایر رویدادها را می‌توان با بازگرداندن sys.monitoring.DISABLE از یک تابع کال‌بک، به ازای هر شیء کد غیرفعال کرد. این کار رویداد را برای کل شیء کد (برای ابزار فعلی) غیرفعال می‌کند.

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

sys.monitoring.restart_events() → None¶

تمام رویدادهایی را که توسط sys.monitoring.DISABLE غیرفعال‌شده بودند، برای همه ابزارها فعال کنید.

آرگومان‌های تابع کال‌بک¶

sys.monitoring.MISSING¶

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

هنگامی که یک رویداد فعال رخ می‌دهد، تابع کال‌بک ثبت‌شده فراخوانی می‌شود. توابع کال‌بکی که شیء‌ای غیر از DISABLE برمی‌گردانند، بی‌اثر خواهند بود. رویدادهای مختلف، آرگومان‌های مختلفی را در اختیار تابع کال‌بک قرار می‌دهند، به شرح زیر:

• PY_START و PY_RESUME:

  func(code: CodeType, instruction_offset: int) -> object
  

• PY_RETURN و PY_YIELD:

  func(code: CodeType, instruction_offset: int, retval: object) -> object
  

• CALL، C_RAISE و C_RETURN (arg0 می‌تواند به‌طور خاص MISSING باشد):

  func(code: CodeType, instruction_offset: int, callable: object, arg0: object) -> object
  

  code نمایانگر شیء کدی است که فراخوانی در آن انجام می‌شود، در حالی که callable شیء‌ای است که قرار است فراخوانی شود (و در نتیجه رویداد را فعال کرده است). اگر آرگومانی وجود نداشته باشد، arg0 برابر با sys.monitoring.MISSING تنظیم می‌شود.

  برای متدهای نمونه، callable شیء تابعی خواهد بود که در کلاس یافت می‌شود، با arg0 تنظیم‌شده به نمونه (یعنی آرگومان self متد).

• RAISE، RERAISE، EXCEPTION_HANDLED، PY_UNWIND، PY_THROW و STOP_ITERATION:

  func(code: CodeType, instruction_offset: int, exception: BaseException) -> object
  

• LINE:

  func(code: CodeType, line_number: int) -> object
  

• BRANCH_LEFT، BRANCH_RIGHT و JUMP:

  func(code: CodeType, instruction_offset: int, destination_offset: int) -> object
  

  توجه داشته باشید که destination_offset محل اجرای بعدی کد است.

• INSTRUCTION:

  func(code: CodeType, instruction_offset: int) -> object