sys.monitoring — Övervakning av exekveringshändelser

Tillagd i version 3.12.

Anteckning

sys.monitoring är en namnrymd inom sys-modulen, inte en oberoende modul, så det finns inget behov av att importera sys.monitoring, bara importera sys och sedan använda sys.monitoring.

Detta namnrymd ger tillgång till de funktioner och konstanter som krävs för att aktivera och styra händelseövervakning.

När program körs inträffar händelser som kan vara av intresse för verktyg som övervakar körningen. Namnrymden sys.monitoring tillhandahåller medel för att ta emot återuppringningar när intressanta händelser inträffar.

API:et för övervakning består av tre komponenter:

Verktygsidentifierare

En verktygsidentifierare är ett heltal och det tillhörande namnet. Verktygsidentifierare används för att hindra verktyg från att störa varandra och för att tillåta att flera verktyg arbetar samtidigt. För närvarande är verktygen helt oberoende av varandra och kan inte användas för att övervaka varandra. Denna begränsning kan komma att upphävas i framtiden.

Innan ett verktyg registrerar eller aktiverar händelser bör det välja en identifierare. Identifierare är heltal i intervallet 0 till och med 5.

Registrera och använda verktyg

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

Måste anropas innan tool_id kan användas. tool_id måste ligga i intervallet 0 till och med 5. Utlöser ett ValueError om tool_id används.

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

Avregistrera alla händelser och callback-funktioner som är kopplade till tool_id.

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

Bör anropas när ett verktyg inte längre behöver tool_id. Anropar clear_tool_id() innan tool_id släpps.

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

Returnerar namnet på verktyget om tool_id används, annars returneras None. tool_id måste ligga inom intervallet 0 till och med 5.

Alla ID:n behandlas på samma sätt av VM när det gäller händelser, men följande ID:n är fördefinierade för att underlätta samarbetet mellan verktygen:

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

Händelser

Följande händelser stöds:

sys.monitoring.events.BRANCH_LEFT

En villkorlig gren går åt vänster.

Det är upp till verktyget att avgöra hur ”vänster” och ”höger” grenar ska presenteras. Det finns ingen garanti för vilken gren som är ”vänster” och vilken som är ”höger”, förutom att den kommer att vara konsekvent under programmets gång.

sys.monitoring.events.BRANCH_RIGHT

En villkorlig gren går till höger.

sys.monitoring.events.CALL

Ett anrop i Python-koden (händelsen inträffar före anropet).

sys.monitoring.events.C_RAISE

Ett undantag som uppstår från en anropsbar funktion, med undantag för Python-funktioner (händelsen inträffar efter avslutningen).

sys.monitoring.events.C_RETURN

Retur från valfri anropsbar funktion, utom Python-funktioner (händelsen inträffar efter returen).

sys.monitoring.events.EXCEPTION_HANDLED

Ett undantag hanteras.

sys.monitoring.events.INSTRUCTION

En VM-instruktion håller på att exekveras.

sys.monitoring.events.JUMP

Ett ovillkorligt hopp i kontrollflödesdiagrammet görs.

sys.monitoring.events.LINE

En instruktion håller på att utföras som har ett annat radnummer än den föregående instruktionen.

sys.monitoring.events.PY_RESUME

Återupptagande av en Python-funktion (för generator- och coroutine-funktioner), utom för throw()-anrop.

sys.monitoring.events.PY_RETURN

Retur från en Python-funktion (sker omedelbart före returen, den uppringdes ram kommer att ligga på stacken).

sys.monitoring.events.PY_START

Start av en Python-funktion (sker omedelbart efter anropet, den anropades ram kommer att ligga på stacken)

sys.monitoring.events.PY_THROW

En Python-funktion återupptas genom ett throw()-anrop.

sys.monitoring.events.PY_UNWIND

Avsluta från en Python-funktion under undantagsupprullning. Detta inkluderar undantag som uppstår direkt inom funktionen och som tillåts fortsätta att spridas.

sys.monitoring.events.PY_YIELD

Avkastning från en Python-funktion (sker omedelbart före avkastningen, den uppkallades ram kommer att ligga på stacken).

sys.monitoring.events.RAISE

Ett undantag tas upp, utom de som orsakar en händelse av typen STOP_ITERATION.

sys.monitoring.events.RERAISE

Ett undantag tas upp igen, t.ex. i slutet av ett finally-block.

sys.monitoring.events.STOP_ITERATION

En artificiell StopIteration uppstår; se händelsen STOP_ITERATION.

Fler evenemang kan tillkomma i framtiden.

Dessa händelser är attribut i namnrymden sys.monitoring.events. Varje händelse representeras av en heltalskonstant i potens 2. För att definiera en uppsättning händelser, bitvis ELLER de enskilda händelserna tillsammans. Om du till exempel vill ange både händelserna PY_RETURN och PY_START, använder du uttrycket PY_RETURN | PY_START.

sys.monitoring.events.NO_EVENTS

Ett alias för 0 så att användare kan göra explicita jämförelser som:

if get_events(DEBUGGER_ID) == NO_EVENTS:
    ...

Om du ställer in denna händelse avaktiveras alla händelser.

Lokala evenemang

Lokala händelser är förknippade med normal körning av programmet och inträffar på tydligt definierade platser. Alla lokala händelser kan avaktiveras. De lokala händelserna är:

Föråldrad händelse

  • BRANCH

Händelsen BRANCH är utfasad i 3.14. Att använda händelserna BRANCH_LEFT och BRANCH_RIGHT ger mycket bättre prestanda eftersom de kan inaktiveras oberoende av varandra.

Kompletterande händelser

Underordnade händelser kan övervakas på samma sätt som andra händelser, men styrs av en annan händelse:

Händelserna C_RETURN och C_RAISE styrs av händelsen CALL. Händelserna C_RETURN och C_RAISE visas endast om motsvarande händelse CALL övervakas.

Andra tävlingar

Andra händelser är inte nödvändigtvis knutna till en viss plats i programmet och kan inte avaktiveras individuellt.

De andra händelser som kan övervakas är:

Händelsen STOP_ITERATION

PEP 380 specificerar att ett StopIteration-undantag höjs när ett värde returneras från en generator eller coroutine. Detta är dock ett mycket ineffektivt sätt att returnera ett värde, så vissa Python-implementationer, särskilt CPython 3.12+, ger inte upphov till ett undantag om det inte skulle vara synligt för annan kod.

För att göra det möjligt för verktyg att övervaka verkliga undantag utan att sakta ner generatorer och coroutines, tillhandahålls händelsen STOP_ITERATION. STOP_ITERATION kan inaktiveras lokalt, till skillnad från RAISE.

Observera att händelsen STOP_ITERATION och händelsen RAISE för ett undantag från StopIteration är likvärdiga och behandlas som utbytbara när händelser genereras. Implementationer kommer att föredra STOP_ITERATION av prestandaskäl, men kan generera en RAISE-händelse med en StopIteration.

Slå på och av händelser

För att kunna övervaka en händelse måste den vara aktiverad och ett motsvarande callback måste vara registrerat. Händelser kan slås på eller av genom att ställa in händelserna antingen globalt och/eller för ett visst kodobjekt. En händelse utlöses endast en gång, även om den är aktiverad både globalt och lokalt.

Global inställning av händelser

Händelser kan styras globalt genom att ändra uppsättningen av händelser som övervakas.

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

Returnerar int som representerar alla aktiva händelser.

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

Aktiverar alla händelser som anges i event_set. Utlöser ett ValueError om tool_id inte används.

Inga händelser är aktiva som standard.

Händelser per kodobjekt

Händelser kan också kontrolleras per kodobjekt. De funktioner som definieras nedan och som accepterar en types.CodeType bör vara förberedda på att acceptera ett likadant objekt från funktioner som inte är definierade i Python (se Övervakning av C API).

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

Returnerar alla lokala händelser för code

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

Aktiverar alla lokala händelser för code som har angetts i event_set. Utlöser ett ValueError om tool_id inte används.

Inaktivera händelser

sys.monitoring.DISABLE

Ett specialvärde som kan returneras från en callback-funktion för att inaktivera händelser för den aktuella kodplatsen.

Lokala händelser kan inaktiveras för en specifik kodplats genom att returnera sys.monitoring.DISABLE från en callback-funktion. Detta ändrar inte vilka händelser som ställs in, eller några andra kodplatser för samma händelse.

Att inaktivera händelser för specifika platser är mycket viktigt för högpresterande övervakning. Ett program kan t.ex. köras under en debugger utan extra kostnader om debuggern inaktiverar all övervakning utom för ett fåtal brytpunkter.

sys.monitoring.restart_events() → None

Aktivera alla händelser som inaktiverades med sys.monitoring.DISABLE för alla verktyg.

Registrering av återuppringningsfunktioner

sys.monitoring.register_callback(tool_id: int, event: int, func: Callable | None, /) → Callable | None

Registrerar den anropsbara funktionen för händelsen med det angivna verktygs_id

Om en annan återuppringning registrerats för det angivna tool_id och event, avregistreras den och returneras. Annars returnerar register_callback() None.

Utlöser en auditing event sys.monitoring.register_callback med argumentet func.

Funktioner kan avregistreras genom att anropa sys.monitoring.register_callback(tool_id, event, None).

Callback-funktioner kan registreras och avregistreras när som helst.

Callbacks anropas endast en gång oavsett om händelsen aktiveras både globalt och lokalt. Om en händelse kan aktiveras för både globala och lokala händelser med din kod, måste återuppringningen skrivas så att den kan hantera båda utlösarna.

Argument för återuppringningsfunktion

sys.monitoring.MISSING

Ett speciellt värde som skickas till en callback-funktion för att ange att det inte finns några argument för anropet.

När en aktiv händelse inträffar anropas den registrerade callback-funktionen. Callback-funktioner som returnerar ett annat objekt än DISABLE kommer inte att ha någon effekt. Olika händelser kommer att ge callback-funktionen olika argument, enligt följande:

  • PY_START och PY_RESUME:

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

  • PY_RETURN och PY_YIELD:

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

  • CALL, C_RAISE och C_RETURN (arg0 kan vara MISSING specifikt):

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

    code representerar det kodobjekt där anropet görs, medan callable är det objekt som är på väg att anropas (och därmed utlöste händelsen). Om det inte finns några argument, sätts arg0 till sys.monitoring.MISSING.

    För instansmetoder kommer callable att vara funktionsobjektet som finns i klassen med arg0 satt till instansen (dvs. self-argumentet till metoden).

  • RAISE, RERAISE, EXCEPTION_HANDLED, PY_UNWIND, PY_THROW och STOP_ITERATION:

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

  • LINE:

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

  • BRANCH_LEFT, BRANCH_RIGHT och JUMP:

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

    Observera att destination_offset är den plats där koden kommer att exekveras nästa gång.

  • INSTRUCTION:

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