parthtamu/rag-code-assistant
0
1<!DOCTYPE html>2 3<html lang="en" data-content_root="../">4 <head>5 <meta charset="utf-8" />6 <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />7<meta property="og:title" content="sys.monitoring — Execution event monitoring" />8<meta property="og:type" content="website" />9<meta property="og:url" content="https://docs.python.org/3/library/sys.monitoring.html" />10<meta property="og:site_name" content="Python documentation" />11<meta property="og:description" content="This namespace provides access to the functions and constants necessary to activate and control event monitoring. As programs execute, events occur that might be of interest to tools that monitor e..." />12<meta property="og:image:width" content="1146" />13<meta property="og:image:height" content="600" />14<meta property="og:image" content="https://docs.python.org/3.15/_images/social_previews/summary_library_sys.monitoring_6f9b6e00.png" />15<meta property="og:image:alt" content="This namespace provides access to the functions and constants necessary to activate and control event monitoring. As programs execute, events occur that might be of interest to tools that monitor e..." />16<meta name="description" content="This namespace provides access to the functions and constants necessary to activate and control event monitoring. As programs execute, events occur that might be of interest to tools that monitor e..." />17<meta name="twitter:card" content="summary_large_image" />18<meta name="theme-color" content="#3776ab">19 20 <title>sys.monitoring — Execution event monitoring — Python 3.15.0a6 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">21 22 <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=b86133f3" />23 <link rel="stylesheet" type="text/css" href="../_static/classic.css?v=234b1a7c" />24 <link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=89a2f22a" />25 <link rel="stylesheet" type="text/css" href="../_static/profiling-sampling-visualization.css?v=0c2600ae" />26 <link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=5349f25f" />27 28 <script src="../_static/documentation_options.js?v=6b7c9ff5"></script>29 <script src="../_static/doctools.js?v=9bcbadda"></script>30 <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>31 <script src="../_static/profiling-sampling-visualization.js?v=9811ed04"></script>32 33 <script src="../_static/sidebar.js"></script>34 35 <link rel="search" type="application/opensearchdescription+xml"36 title="Search within Python 3.15.0a6 documentation"37 href="../_static/opensearch.xml"/>38 <link rel="author" title="About these documents" href="../about.html" />39 <link rel="index" title="Index" href="../genindex.html" />40 <link rel="search" title="Search" href="../search.html" />41 <link rel="copyright" title="Copyright" href="../copyright.html" />42 <link rel="next" title="sysconfig — Provide access to Python’s configuration information" href="sysconfig.html" />43 <link rel="prev" title="sys — System-specific parameters and functions" href="sys.html" />44 45 46 <script defer file-types="bz2,epub,zip" data-domain="docs.python.org" src="https://analytics.python.org/js/script.file-downloads.outbound-links.js"></script>47 48 <link rel="canonical" href="https://docs.python.org/3/library/sys.monitoring.html">49 50 51 52 53 <style>54 @media only screen {55 table.full-width-table {56 width: 100%;57 }58 }59 </style>60<link rel="stylesheet" href="../_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css">61 <link rel="shortcut icon" type="image/png" href="../_static/py.svg">62 <script type="text/javascript" src="../_static/copybutton.js"></script>63 <script type="text/javascript" src="../_static/menu.js"></script>64 <script type="text/javascript" src="../_static/search-focus.js"></script>65 <script type="text/javascript" src="../_static/themetoggle.js"></script> 66 <script type="text/javascript" src="../_static/rtd_switcher.js"></script>67 <meta name="readthedocs-addons-api-version" content="1">68 69 </head>70<body>71<div class="mobile-nav">72 <input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"73 aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu">74 <nav class="nav-content" role="navigation">75 <label for="menuToggler" class="toggler__label">76 <span></span>77 </label>78 <span class="nav-items-wrapper">79 <a href="https://www.python.org/" class="nav-logo">80 <img src="../_static/py.svg" alt="Python logo">81 </a>82 <span class="version_switcher_placeholder"></span>83 <form role="search" class="search" action="../search.html" method="get">84 <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">85 <path fill-rule="nonzero" fill="currentColor" d="M15.5 14h-.79l-.28-.27a6.5 6.5 0 001.48-5.34c-.47-2.78-2.79-5-5.59-5.34a6.505 6.505 0 00-7.27 7.27c.34 2.8 2.56 5.12 5.34 5.59a6.5 6.5 0 005.34-1.48l.27.28v.79l4.25 4.25c.41.41 1.08.41 1.49 0 .41-.41.41-1.08 0-1.49L15.5 14zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z"></path>86 </svg>87 <input placeholder="Quick search" aria-label="Quick search" type="search" name="q">88 <input type="submit" value="Go">89 </form>90 </span>91 </nav>92 <div class="menu-wrapper">93 <nav class="menu" role="navigation" aria-label="main navigation">94 <div class="language_switcher_placeholder"></div>95 96<label class="theme-selector-label">97 Theme98 <select class="theme-selector" oninput="activateTheme(this.value)">99 <option value="auto" selected>Auto</option>100 <option value="light">Light</option>101 <option value="dark">Dark</option>102 </select>103</label>104 <div>105 <h3><a href="../contents.html">Table of Contents</a></h3>106 <ul>107<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">sys.monitoring</span></code> — Execution event monitoring</a><ul>108<li><a class="reference internal" href="#tool-identifiers">Tool identifiers</a><ul>109<li><a class="reference internal" href="#registering-and-using-tools">Registering and using tools</a></li>110</ul>111</li>112<li><a class="reference internal" href="#events">Events</a><ul>113<li><a class="reference internal" href="#local-events">Local events</a></li>114<li><a class="reference internal" href="#deprecated-event">Deprecated event</a></li>115<li><a class="reference internal" href="#ancillary-events">Ancillary events</a></li>116<li><a class="reference internal" href="#other-events">Other events</a></li>117<li><a class="reference internal" href="#the-stop-iteration-event">The STOP_ITERATION event</a></li>118</ul>119</li>120<li><a class="reference internal" href="#turning-events-on-and-off">Turning events on and off</a><ul>121<li><a class="reference internal" href="#setting-events-globally">Setting events globally</a></li>122<li><a class="reference internal" href="#per-code-object-events">Per code object events</a></li>123<li><a class="reference internal" href="#disabling-events">Disabling events</a></li>124</ul>125</li>126<li><a class="reference internal" href="#registering-callback-functions">Registering callback functions</a><ul>127<li><a class="reference internal" href="#callback-function-arguments">Callback function arguments</a></li>128</ul>129</li>130</ul>131</li>132</ul>133 134 </div>135 <div>136 <h4>Previous topic</h4>137 <p class="topless"><a href="sys.html"138 title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">sys</span></code> — System-specific parameters and functions</a></p>139 </div>140 <div>141 <h4>Next topic</h4>142 <p class="topless"><a href="sysconfig.html"143 title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">sysconfig</span></code> — Provide access to Python’s configuration information</a></p>144 </div>145 <script>146 document.addEventListener('DOMContentLoaded', () => {147 const title = document.querySelector('meta[property="og:title"]').content;148 const elements = document.querySelectorAll('.improvepage');149 const pageurl = window.location.href.split('?')[0];150 elements.forEach(element => {151 const url = new URL(element.href.split('?')[0].replace("-nojs", ""));152 url.searchParams.set('pagetitle', title);153 url.searchParams.set('pageurl', pageurl);154 url.searchParams.set('pagesource', "library/sys.monitoring.rst");155 element.href = url.toString();156 });157 });158 </script>159 <div role="note" aria-label="source link">160 <h3>This page</h3>161 <ul class="this-page-menu">162 <li><a href="../bugs.html">Report a bug</a></li>163 <li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>164 <li>165 <a href="https://github.com/python/cpython/blob/main/Doc/library/sys.monitoring.rst?plain=1"166 rel="nofollow">Show source167 </a>168 </li>169 170 </ul>171 </div>172 </nav>173 </div>174</div>175 176 177 <div class="related" role="navigation" aria-label="Related">178 <h3>Navigation</h3>179 <ul>180 <li class="right" style="margin-right: 10px">181 <a href="../genindex.html" title="General Index"182 accesskey="I">index</a></li>183 <li class="right" >184 <a href="../py-modindex.html" title="Python Module Index"185 >modules</a> |</li>186 <li class="right" >187 <a href="sysconfig.html" title="sysconfig — Provide access to Python’s configuration information"188 accesskey="N">next</a> |</li>189 <li class="right" >190 <a href="sys.html" title="sys — System-specific parameters and functions"191 accesskey="P">previous</a> |</li>192 193 <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>194 <li><a href="https://www.python.org/">Python</a> »</li>195 <li class="switchers">196 <div class="language_switcher_placeholder"></div>197 <div class="version_switcher_placeholder"></div>198 </li>199 <li>200 201 </li>202 <li id="cpython-language-and-version">203 <a href="../index.html">3.15.0a6 Documentation</a> »204 </li>205 206 <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>207 <li class="nav-item nav-item-2"><a href="python.html" accesskey="U">Python Runtime Services</a> »</li>208 <li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">sys.monitoring</span></code> — Execution event monitoring</a></li>209 <li class="right">210 211 212 <div class="inline-search" role="search">213 <form class="inline-search" action="../search.html" method="get">214 <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box">215 <input type="submit" value="Go">216 </form>217 </div>218 |219 </li>220 <li class="right">221<label class="theme-selector-label">222 Theme223 <select class="theme-selector" oninput="activateTheme(this.value)">224 <option value="auto" selected>Auto</option>225 <option value="light">Light</option>226 <option value="dark">Dark</option>227 </select>228</label> |</li>229 230 </ul>231 </div> 232 233 <div class="document">234 <div class="documentwrapper">235 <div class="bodywrapper">236 <div class="body" role="main">237 238 <section id="module-sys.monitoring">239<span id="sys-monitoring-execution-event-monitoring"></span><h1><code class="xref py py-mod docutils literal notranslate"><span class="pre">sys.monitoring</span></code> — Execution event monitoring<a class="headerlink" href="#module-sys.monitoring" title="Link to this heading">¶</a></h1>240<div class="versionadded">241<p><span class="versionmodified added">Added in version 3.12.</span></p>242</div>243<hr class="docutils" />244<div class="admonition note">245<p class="admonition-title">Note</p>246<p><code class="xref py py-mod docutils literal notranslate"><span class="pre">sys.monitoring</span></code> is a namespace within the <a class="reference internal" href="sys.html#module-sys" title="sys: Access system-specific parameters and functions."><code class="xref py py-mod docutils literal notranslate"><span class="pre">sys</span></code></a> module,247not an independent module, so there is no need to248<code class="docutils literal notranslate"><span class="pre">import</span> <span class="pre">sys.monitoring</span></code>, simply <code class="docutils literal notranslate"><span class="pre">import</span> <span class="pre">sys</span></code> and then use249<code class="docutils literal notranslate"><span class="pre">sys.monitoring</span></code>.</p>250</div>251<p>This namespace provides access to the functions and constants necessary to252activate and control event monitoring.</p>253<p>As programs execute, events occur that might be of interest to tools that254monitor execution. The <code class="xref py py-mod docutils literal notranslate"><span class="pre">sys.monitoring</span></code> namespace provides means to255receive callbacks when events of interest occur.</p>256<p>The monitoring API consists of three components:</p>257<ul class="simple">258<li><p><a class="reference internal" href="#tool-identifiers">Tool identifiers</a></p></li>259<li><p><a class="reference internal" href="#events">Events</a></p></li>260<li><p><a class="reference internal" href="#callbacks"><span class="std std-ref">Callbacks</span></a></p></li>261</ul>262<section id="tool-identifiers">263<h2>Tool identifiers<a class="headerlink" href="#tool-identifiers" title="Link to this heading">¶</a></h2>264<p>A tool identifier is an integer and the associated name.265Tool identifiers are used to discourage tools from interfering with each266other and to allow multiple tools to operate at the same time.267Currently tools are completely independent and cannot be used to268monitor each other. This restriction may be lifted in the future.</p>269<p>Before registering or activating events, a tool should choose an identifier.270Identifiers are integers in the range 0 to 5 inclusive.</p>271<section id="registering-and-using-tools">272<h3>Registering and using tools<a class="headerlink" href="#registering-and-using-tools" title="Link to this heading">¶</a></h3>273<dl class="py function">274<dt class="sig sig-object py" id="sys.monitoring.use_tool_id">275<span class="sig-prename descclassname"><span class="pre">sys.monitoring.</span></span><span class="sig-name descname"><span class="pre">use_tool_id</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">tool_id</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="functions.html#int" title="int"><span class="pre">int</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">name</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="stdtypes.html#str" title="str"><span class="pre">str</span></a></span></em>, <em class="sig-param"><span class="positional-only-separator o"><abbr title="Positional-only parameter separator (PEP 570)"><span class="pre">/</span></abbr></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">→</span> <span class="sig-return-typehint"><a class="reference internal" href="constants.html#None" title="None"><span class="pre">None</span></a></span></span><a class="headerlink" href="#sys.monitoring.use_tool_id" title="Link to this definition">¶</a></dt>276<dd><p>Must be called before <em>tool_id</em> can be used.277<em>tool_id</em> must be in the range 0 to 5 inclusive.278Raises a <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a> if <em>tool_id</em> is in use.</p>279</dd></dl>280 281<dl class="py function">282<dt class="sig sig-object py" id="sys.monitoring.clear_tool_id">283<span class="sig-prename descclassname"><span class="pre">sys.monitoring.</span></span><span class="sig-name descname"><span class="pre">clear_tool_id</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">tool_id</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="functions.html#int" title="int"><span class="pre">int</span></a></span></em>, <em class="sig-param"><span class="positional-only-separator o"><abbr title="Positional-only parameter separator (PEP 570)"><span class="pre">/</span></abbr></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">→</span> <span class="sig-return-typehint"><a class="reference internal" href="constants.html#None" title="None"><span class="pre">None</span></a></span></span><a class="headerlink" href="#sys.monitoring.clear_tool_id" title="Link to this definition">¶</a></dt>284<dd><p>Unregister all events and callback functions associated with <em>tool_id</em>.</p>285</dd></dl>286 287<dl class="py function">288<dt class="sig sig-object py" id="sys.monitoring.free_tool_id">289<span class="sig-prename descclassname"><span class="pre">sys.monitoring.</span></span><span class="sig-name descname"><span class="pre">free_tool_id</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">tool_id</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="functions.html#int" title="int"><span class="pre">int</span></a></span></em>, <em class="sig-param"><span class="positional-only-separator o"><abbr title="Positional-only parameter separator (PEP 570)"><span class="pre">/</span></abbr></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">→</span> <span class="sig-return-typehint"><a class="reference internal" href="constants.html#None" title="None"><span class="pre">None</span></a></span></span><a class="headerlink" href="#sys.monitoring.free_tool_id" title="Link to this definition">¶</a></dt>290<dd><p>Should be called once a tool no longer requires <em>tool_id</em>.291Will call <a class="reference internal" href="#sys.monitoring.clear_tool_id" title="sys.monitoring.clear_tool_id"><code class="xref py py-func docutils literal notranslate"><span class="pre">clear_tool_id()</span></code></a> before releasing <em>tool_id</em>.</p>292</dd></dl>293 294<dl class="py function">295<dt class="sig sig-object py" id="sys.monitoring.get_tool">296<span class="sig-prename descclassname"><span class="pre">sys.monitoring.</span></span><span class="sig-name descname"><span class="pre">get_tool</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">tool_id</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="functions.html#int" title="int"><span class="pre">int</span></a></span></em>, <em class="sig-param"><span class="positional-only-separator o"><abbr title="Positional-only parameter separator (PEP 570)"><span class="pre">/</span></abbr></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">→</span> <span class="sig-return-typehint"><a class="reference internal" href="stdtypes.html#str" title="str"><span class="pre">str</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference internal" href="constants.html#None" title="None"><span class="pre">None</span></a></span></span><a class="headerlink" href="#sys.monitoring.get_tool" title="Link to this definition">¶</a></dt>297<dd><p>Returns the name of the tool if <em>tool_id</em> is in use,298otherwise it returns <code class="docutils literal notranslate"><span class="pre">None</span></code>.299<em>tool_id</em> must be in the range 0 to 5 inclusive.</p>300</dd></dl>301 302<p>All IDs are treated the same by the VM with regard to events, but the303following IDs are pre-defined to make co-operation of tools easier:</p>304<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">sys</span><span class="o">.</span><span class="n">monitoring</span><span class="o">.</span><span class="n">DEBUGGER_ID</span> <span class="o">=</span> <span class="mi">0</span>305<span class="n">sys</span><span class="o">.</span><span class="n">monitoring</span><span class="o">.</span><span class="n">COVERAGE_ID</span> <span class="o">=</span> <span class="mi">1</span>306<span class="n">sys</span><span class="o">.</span><span class="n">monitoring</span><span class="o">.</span><span class="n">PROFILER_ID</span> <span class="o">=</span> <span class="mi">2</span>307<span class="n">sys</span><span class="o">.</span><span class="n">monitoring</span><span class="o">.</span><span class="n">OPTIMIZER_ID</span> <span class="o">=</span> <span class="mi">5</span>308</pre></div>309</div>310</section>311</section>312<section id="events">313<h2>Events<a class="headerlink" href="#events" title="Link to this heading">¶</a></h2>314<p>The following events are supported:</p>315<dl class="std monitoring-event">316<dt class="sig sig-object std" id="monitoring-event-BRANCH_LEFT">317<span class="sig-prename descclassname"><span class="pre">sys.monitoring.events.</span></span><span class="sig-name descname"><span class="pre">BRANCH_LEFT</span></span><a class="headerlink" href="#monitoring-event-BRANCH_LEFT" title="Link to this definition">¶</a></dt>318<dd><p>A conditional branch goes left.</p>319<p>It is up to the tool to determine how to present “left” and “right” branches.320There is no guarantee which branch is “left” and which is “right”, except321that it will be consistent for the duration of the program.</p>322</dd></dl>323 324<dl class="std monitoring-event">325<dt class="sig sig-object std" id="monitoring-event-BRANCH_RIGHT">326<span class="sig-prename descclassname"><span class="pre">sys.monitoring.events.</span></span><span class="sig-name descname"><span class="pre">BRANCH_RIGHT</span></span><a class="headerlink" href="#monitoring-event-BRANCH_RIGHT" title="Link to this definition">¶</a></dt>327<dd><p>A conditional branch goes right.</p>328</dd></dl>329 330<dl class="std monitoring-event">331<dt class="sig sig-object std" id="monitoring-event-CALL">332<span class="sig-prename descclassname"><span class="pre">sys.monitoring.events.</span></span><span class="sig-name descname"><span class="pre">CALL</span></span><a class="headerlink" href="#monitoring-event-CALL" title="Link to this definition">¶</a></dt>333<dd><p>A call in Python code (event occurs before the call).</p>334</dd></dl>335 336<dl class="std monitoring-event">337<dt class="sig sig-object std" id="monitoring-event-C_RAISE">338<span class="sig-prename descclassname"><span class="pre">sys.monitoring.events.</span></span><span class="sig-name descname"><span class="pre">C_RAISE</span></span><a class="headerlink" href="#monitoring-event-C_RAISE" title="Link to this definition">¶</a></dt>339<dd><p>An exception raised from any callable, except for Python functions (event occurs after the exit).</p>340</dd></dl>341 342<dl class="std monitoring-event">343<dt class="sig sig-object std" id="monitoring-event-C_RETURN">344<span class="sig-prename descclassname"><span class="pre">sys.monitoring.events.</span></span><span class="sig-name descname"><span class="pre">C_RETURN</span></span><a class="headerlink" href="#monitoring-event-C_RETURN" title="Link to this definition">¶</a></dt>345<dd><p>Return from any callable, except for Python functions (event occurs after the return).</p>346</dd></dl>347 348<dl class="std monitoring-event">349<dt class="sig sig-object std" id="monitoring-event-EXCEPTION_HANDLED">350<span class="sig-prename descclassname"><span class="pre">sys.monitoring.events.</span></span><span class="sig-name descname"><span class="pre">EXCEPTION_HANDLED</span></span><a class="headerlink" href="#monitoring-event-EXCEPTION_HANDLED" title="Link to this definition">¶</a></dt>351<dd><p>An exception is handled.</p>352</dd></dl>353 354<dl class="std monitoring-event">355<dt class="sig sig-object std" id="monitoring-event-INSTRUCTION">356<span class="sig-prename descclassname"><span class="pre">sys.monitoring.events.</span></span><span class="sig-name descname"><span class="pre">INSTRUCTION</span></span><a class="headerlink" href="#monitoring-event-INSTRUCTION" title="Link to this definition">¶</a></dt>357<dd><p>A VM instruction is about to be executed.</p>358</dd></dl>359 360<dl class="std monitoring-event">361<dt class="sig sig-object std" id="monitoring-event-JUMP">362<span class="sig-prename descclassname"><span class="pre">sys.monitoring.events.</span></span><span class="sig-name descname"><span class="pre">JUMP</span></span><a class="headerlink" href="#monitoring-event-JUMP" title="Link to this definition">¶</a></dt>363<dd><p>An unconditional jump in the control flow graph is made.</p>364</dd></dl>365 366<dl class="std monitoring-event">367<dt class="sig sig-object std" id="monitoring-event-LINE">368<span class="sig-prename descclassname"><span class="pre">sys.monitoring.events.</span></span><span class="sig-name descname"><span class="pre">LINE</span></span><a class="headerlink" href="#monitoring-event-LINE" title="Link to this definition">¶</a></dt>369<dd><p>An instruction is about to be executed that has a different line number from the preceding instruction.</p>370</dd></dl>371 372<dl class="std monitoring-event">373<dt class="sig sig-object std" id="monitoring-event-PY_RESUME">374<span class="sig-prename descclassname"><span class="pre">sys.monitoring.events.</span></span><span class="sig-name descname"><span class="pre">PY_RESUME</span></span><a class="headerlink" href="#monitoring-event-PY_RESUME" title="Link to this definition">¶</a></dt>375<dd><p>Resumption of a Python function (for generator and coroutine functions), except for <code class="docutils literal notranslate"><span class="pre">throw()</span></code> calls.</p>376</dd></dl>377 378<dl class="std monitoring-event">379<dt class="sig sig-object std" id="monitoring-event-PY_RETURN">380<span class="sig-prename descclassname"><span class="pre">sys.monitoring.events.</span></span><span class="sig-name descname"><span class="pre">PY_RETURN</span></span><a class="headerlink" href="#monitoring-event-PY_RETURN" title="Link to this definition">¶</a></dt>381<dd><p>Return from a Python function (occurs immediately before the return, the callee’s frame will be on the stack).</p>382</dd></dl>383 384<dl class="std monitoring-event">385<dt class="sig sig-object std" id="monitoring-event-PY_START">386<span class="sig-prename descclassname"><span class="pre">sys.monitoring.events.</span></span><span class="sig-name descname"><span class="pre">PY_START</span></span><a class="headerlink" href="#monitoring-event-PY_START" title="Link to this definition">¶</a></dt>387<dd><p>Start of a Python function (occurs immediately after the call, the callee’s frame will be on the stack)</p>388</dd></dl>389 390<dl class="std monitoring-event">391<dt class="sig sig-object std" id="monitoring-event-PY_THROW">392<span class="sig-prename descclassname"><span class="pre">sys.monitoring.events.</span></span><span class="sig-name descname"><span class="pre">PY_THROW</span></span><a class="headerlink" href="#monitoring-event-PY_THROW" title="Link to this definition">¶</a></dt>393<dd><p>A Python function is resumed by a <code class="docutils literal notranslate"><span class="pre">throw()</span></code> call.</p>394</dd></dl>395 396<dl class="std monitoring-event">397<dt class="sig sig-object std" id="monitoring-event-PY_UNWIND">398<span class="sig-prename descclassname"><span class="pre">sys.monitoring.events.</span></span><span class="sig-name descname"><span class="pre">PY_UNWIND</span></span><a class="headerlink" href="#monitoring-event-PY_UNWIND" title="Link to this definition">¶</a></dt>399<dd><p>Exit from a Python function during exception unwinding. This includes exceptions raised directly within the400function and that are allowed to continue to propagate.</p>401</dd></dl>402 403<dl class="std monitoring-event">404<dt class="sig sig-object std" id="monitoring-event-PY_YIELD">405<span class="sig-prename descclassname"><span class="pre">sys.monitoring.events.</span></span><span class="sig-name descname"><span class="pre">PY_YIELD</span></span><a class="headerlink" href="#monitoring-event-PY_YIELD" title="Link to this definition">¶</a></dt>406<dd><p>Yield from a Python function (occurs immediately before the yield, the callee’s frame will be on the stack).</p>407</dd></dl>408 409<dl class="std monitoring-event">410<dt class="sig sig-object std" id="monitoring-event-RAISE">411<span class="sig-prename descclassname"><span class="pre">sys.monitoring.events.</span></span><span class="sig-name descname"><span class="pre">RAISE</span></span><a class="headerlink" href="#monitoring-event-RAISE" title="Link to this definition">¶</a></dt>412<dd><p>An exception is raised, except those that cause a <a class="reference internal" href="#monitoring-event-STOP_ITERATION"><code class="xref std std-monitoring-event docutils literal notranslate"><span class="pre">STOP_ITERATION</span></code></a> event.</p>413</dd></dl>414 415<dl class="std monitoring-event">416<dt class="sig sig-object std" id="monitoring-event-RERAISE">417<span class="sig-prename descclassname"><span class="pre">sys.monitoring.events.</span></span><span class="sig-name descname"><span class="pre">RERAISE</span></span><a class="headerlink" href="#monitoring-event-RERAISE" title="Link to this definition">¶</a></dt>418<dd><p>An exception is re-raised, for example at the end of a <a class="reference internal" href="../reference/compound_stmts.html#finally"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">finally</span></code></a> block.</p>419</dd></dl>420 421<dl class="std monitoring-event">422<dt class="sig sig-object std" id="monitoring-event-STOP_ITERATION">423<span class="sig-prename descclassname"><span class="pre">sys.monitoring.events.</span></span><span class="sig-name descname"><span class="pre">STOP_ITERATION</span></span><a class="headerlink" href="#monitoring-event-STOP_ITERATION" title="Link to this definition">¶</a></dt>424<dd><p>An artificial <a class="reference internal" href="exceptions.html#StopIteration" title="StopIteration"><code class="xref py py-exc docutils literal notranslate"><span class="pre">StopIteration</span></code></a> is raised; see <a class="reference internal" href="#the-stop-iteration-event">the STOP_ITERATION event</a>.</p>425</dd></dl>426 427<p>More events may be added in the future.</p>428<p>These events are attributes of the <code class="xref py py-mod docutils literal notranslate"><span class="pre">sys.monitoring.events</span></code> namespace.429Each event is represented as a power-of-2 integer constant.430To define a set of events, simply bitwise OR the individual events together.431For example, to specify both <a class="reference internal" href="#monitoring-event-PY_RETURN"><code class="xref std std-monitoring-event docutils literal notranslate"><span class="pre">PY_RETURN</span></code></a> and <a class="reference internal" href="#monitoring-event-PY_START"><code class="xref std std-monitoring-event docutils literal notranslate"><span class="pre">PY_START</span></code></a>432events, use the expression <code class="docutils literal notranslate"><span class="pre">PY_RETURN</span> <span class="pre">|</span> <span class="pre">PY_START</span></code>.</p>433<dl class="std monitoring-event">434<dt class="sig sig-object std" id="monitoring-event-NO_EVENTS">435<span class="sig-prename descclassname"><span class="pre">sys.monitoring.events.</span></span><span class="sig-name descname"><span class="pre">NO_EVENTS</span></span><a class="headerlink" href="#monitoring-event-NO_EVENTS" title="Link to this definition">¶</a></dt>436<dd><p>An alias for <code class="docutils literal notranslate"><span class="pre">0</span></code> so users can do explicit comparisons like:</p>437<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">if</span> <span class="n">get_events</span><span class="p">(</span><span class="n">DEBUGGER_ID</span><span class="p">)</span> <span class="o">==</span> <span class="n">NO_EVENTS</span><span class="p">:</span>438 <span class="o">...</span>439</pre></div>440</div>441<p>Setting this event deactivates all events.</p>442</dd></dl>443 444<section id="local-events">445<span id="monitoring-event-local"></span><h3>Local events<a class="headerlink" href="#local-events" title="Link to this heading">¶</a></h3>446<p>Local events are associated with normal execution of the program and happen447at clearly defined locations. All local events can be disabled.448The local events are:</p>449<ul class="simple">450<li><p><a class="reference internal" href="#monitoring-event-PY_START"><code class="xref std std-monitoring-event docutils literal notranslate"><span class="pre">PY_START</span></code></a></p></li>451<li><p><a class="reference internal" href="#monitoring-event-PY_RESUME"><code class="xref std std-monitoring-event docutils literal notranslate"><span class="pre">PY_RESUME</span></code></a></p></li>452<li><p><a class="reference internal" href="#monitoring-event-PY_RETURN"><code class="xref std std-monitoring-event docutils literal notranslate"><span class="pre">PY_RETURN</span></code></a></p></li>453<li><p><a class="reference internal" href="#monitoring-event-PY_YIELD"><code class="xref std std-monitoring-event docutils literal notranslate"><span class="pre">PY_YIELD</span></code></a></p></li>454<li><p><a class="reference internal" href="#monitoring-event-CALL"><code class="xref std std-monitoring-event docutils literal notranslate"><span class="pre">CALL</span></code></a></p></li>455<li><p><a class="reference internal" href="#monitoring-event-LINE"><code class="xref std std-monitoring-event docutils literal notranslate"><span class="pre">LINE</span></code></a></p></li>456<li><p><a class="reference internal" href="#monitoring-event-INSTRUCTION"><code class="xref std std-monitoring-event docutils literal notranslate"><span class="pre">INSTRUCTION</span></code></a></p></li>457<li><p><a class="reference internal" href="#monitoring-event-JUMP"><code class="xref std std-monitoring-event docutils literal notranslate"><span class="pre">JUMP</span></code></a></p></li>458<li><p><a class="reference internal" href="#monitoring-event-BRANCH_LEFT"><code class="xref std std-monitoring-event docutils literal notranslate"><span class="pre">BRANCH_LEFT</span></code></a></p></li>459<li><p><a class="reference internal" href="#monitoring-event-BRANCH_RIGHT"><code class="xref std std-monitoring-event docutils literal notranslate"><span class="pre">BRANCH_RIGHT</span></code></a></p></li>460<li><p><a class="reference internal" href="#monitoring-event-STOP_ITERATION"><code class="xref std std-monitoring-event docutils literal notranslate"><span class="pre">STOP_ITERATION</span></code></a></p></li>461</ul>462</section>463<section id="deprecated-event">464<h3>Deprecated event<a class="headerlink" href="#deprecated-event" title="Link to this heading">¶</a></h3>465<ul class="simple">466<li><p><code class="docutils literal notranslate"><span class="pre">BRANCH</span></code></p></li>467</ul>468<p>The <code class="docutils literal notranslate"><span class="pre">BRANCH</span></code> event is deprecated in 3.14.469Using <a class="reference internal" href="#monitoring-event-BRANCH_LEFT"><code class="xref std std-monitoring-event docutils literal notranslate"><span class="pre">BRANCH_LEFT</span></code></a> and <a class="reference internal" href="#monitoring-event-BRANCH_RIGHT"><code class="xref std std-monitoring-event docutils literal notranslate"><span class="pre">BRANCH_RIGHT</span></code></a>470events will give much better performance as they can be disabled471independently.</p>472</section>473<section id="ancillary-events">474<h3>Ancillary events<a class="headerlink" href="#ancillary-events" title="Link to this heading">¶</a></h3>475<p>Ancillary events can be monitored like other events, but are controlled476by another event:</p>477<ul class="simple">478<li><p><a class="reference internal" href="#monitoring-event-C_RAISE"><code class="xref std std-monitoring-event docutils literal notranslate"><span class="pre">C_RAISE</span></code></a></p></li>479<li><p><a class="reference internal" href="#monitoring-event-C_RETURN"><code class="xref std std-monitoring-event docutils literal notranslate"><span class="pre">C_RETURN</span></code></a></p></li>480</ul>481<p>The <a class="reference internal" href="#monitoring-event-C_RETURN"><code class="xref std std-monitoring-event docutils literal notranslate"><span class="pre">C_RETURN</span></code></a> and <a class="reference internal" href="#monitoring-event-C_RAISE"><code class="xref std std-monitoring-event docutils literal notranslate"><span class="pre">C_RAISE</span></code></a> events482are controlled by the <a class="reference internal" href="#monitoring-event-CALL"><code class="xref std std-monitoring-event docutils literal notranslate"><span class="pre">CALL</span></code></a> event.483<code class="xref std std-monitoring-event docutils literal notranslate"><span class="pre">C_RETURN</span></code> and <code class="xref std std-monitoring-event docutils literal notranslate"><span class="pre">C_RAISE</span></code> events will only be484seen if the corresponding <code class="xref std std-monitoring-event docutils literal notranslate"><span class="pre">CALL</span></code> event is being monitored.</p>485</section>486<section id="other-events">487<span id="monitoring-event-global"></span><h3>Other events<a class="headerlink" href="#other-events" title="Link to this heading">¶</a></h3>488<p>Other events are not necessarily tied to a specific location in the489program and cannot be individually disabled via <a class="reference internal" href="#sys.monitoring.DISABLE" title="sys.monitoring.DISABLE"><code class="xref py py-data docutils literal notranslate"><span class="pre">DISABLE</span></code></a>.</p>490<p>The other events that can be monitored are:</p>491<ul class="simple">492<li><p><a class="reference internal" href="#monitoring-event-PY_THROW"><code class="xref std std-monitoring-event docutils literal notranslate"><span class="pre">PY_THROW</span></code></a></p></li>493<li><p><a class="reference internal" href="#monitoring-event-PY_UNWIND"><code class="xref std std-monitoring-event docutils literal notranslate"><span class="pre">PY_UNWIND</span></code></a></p></li>494<li><p><a class="reference internal" href="#monitoring-event-RAISE"><code class="xref std std-monitoring-event docutils literal notranslate"><span class="pre">RAISE</span></code></a></p></li>495<li><p><a class="reference internal" href="#monitoring-event-EXCEPTION_HANDLED"><code class="xref std std-monitoring-event docutils literal notranslate"><span class="pre">EXCEPTION_HANDLED</span></code></a></p></li>496</ul>497</section>498<section id="the-stop-iteration-event">499<h3>The STOP_ITERATION event<a class="headerlink" href="#the-stop-iteration-event" title="Link to this heading">¶</a></h3>500<p><span class="target" id="index-0"></span><a class="pep reference external" href="https://peps.python.org/pep-0380/#use-of-stopiteration-to-return-values"><strong>PEP 380</strong></a>501specifies that a <a class="reference internal" href="exceptions.html#StopIteration" title="StopIteration"><code class="xref py py-exc docutils literal notranslate"><span class="pre">StopIteration</span></code></a> exception is raised when returning a value502from a generator or coroutine. However, this is a very inefficient way to503return a value, so some Python implementations, notably CPython 3.12+, do not504raise an exception unless it would be visible to other code.</p>505<p>To allow tools to monitor for real exceptions without slowing down generators506and coroutines, the <a class="reference internal" href="#monitoring-event-STOP_ITERATION"><code class="xref std std-monitoring-event docutils literal notranslate"><span class="pre">STOP_ITERATION</span></code></a> event is provided.507<code class="xref std std-monitoring-event docutils literal notranslate"><span class="pre">STOP_ITERATION</span></code> can be locally disabled, unlike508<a class="reference internal" href="#monitoring-event-RAISE"><code class="xref std std-monitoring-event docutils literal notranslate"><span class="pre">RAISE</span></code></a>.</p>509<p>Note that the <a class="reference internal" href="#monitoring-event-STOP_ITERATION"><code class="xref std std-monitoring-event docutils literal notranslate"><span class="pre">STOP_ITERATION</span></code></a> event and the510<a class="reference internal" href="#monitoring-event-RAISE"><code class="xref std std-monitoring-event docutils literal notranslate"><span class="pre">RAISE</span></code></a> event for a <a class="reference internal" href="exceptions.html#StopIteration" title="StopIteration"><code class="xref py py-exc docutils literal notranslate"><span class="pre">StopIteration</span></code></a> exception are511equivalent, and are treated as interchangeable when generating events.512Implementations will favor <code class="xref std std-monitoring-event docutils literal notranslate"><span class="pre">STOP_ITERATION</span></code> for performance513reasons, but may generate a <code class="xref std std-monitoring-event docutils literal notranslate"><span class="pre">RAISE</span></code> event with a514<code class="xref py py-exc docutils literal notranslate"><span class="pre">StopIteration</span></code>.</p>515</section>516</section>517<section id="turning-events-on-and-off">518<h2>Turning events on and off<a class="headerlink" href="#turning-events-on-and-off" title="Link to this heading">¶</a></h2>519<p>In order to monitor an event, it must be turned on and a corresponding callback520must be registered. Events can be turned on or off by setting the events either521globally and/or for a particular code object. An event will trigger only once,522even if it is turned on both globally and locally.</p>523<section id="setting-events-globally">524<h3>Setting events globally<a class="headerlink" href="#setting-events-globally" title="Link to this heading">¶</a></h3>525<p>Events can be controlled globally by modifying the set of events being monitored.</p>526<dl class="py function">527<dt class="sig sig-object py" id="sys.monitoring.get_events">528<span class="sig-prename descclassname"><span class="pre">sys.monitoring.</span></span><span class="sig-name descname"><span class="pre">get_events</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">tool_id</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="functions.html#int" title="int"><span class="pre">int</span></a></span></em>, <em class="sig-param"><span class="positional-only-separator o"><abbr title="Positional-only parameter separator (PEP 570)"><span class="pre">/</span></abbr></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">→</span> <span class="sig-return-typehint"><a class="reference internal" href="functions.html#int" title="int"><span class="pre">int</span></a></span></span><a class="headerlink" href="#sys.monitoring.get_events" title="Link to this definition">¶</a></dt>529<dd><p>Returns the <code class="docutils literal notranslate"><span class="pre">int</span></code> representing all the active events.</p>530</dd></dl>531 532<dl class="py function">533<dt class="sig sig-object py" id="sys.monitoring.set_events">534<span class="sig-prename descclassname"><span class="pre">sys.monitoring.</span></span><span class="sig-name descname"><span class="pre">set_events</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">tool_id</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="functions.html#int" title="int"><span class="pre">int</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">event_set</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="functions.html#int" title="int"><span class="pre">int</span></a></span></em>, <em class="sig-param"><span class="positional-only-separator o"><abbr title="Positional-only parameter separator (PEP 570)"><span class="pre">/</span></abbr></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">→</span> <span class="sig-return-typehint"><a class="reference internal" href="constants.html#None" title="None"><span class="pre">None</span></a></span></span><a class="headerlink" href="#sys.monitoring.set_events" title="Link to this definition">¶</a></dt>535<dd><p>Activates all events which are set in <em>event_set</em>.536Raises a <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a> if <em>tool_id</em> is not in use.</p>537</dd></dl>538 539<p>No events are active by default.</p>540</section>541<section id="per-code-object-events">542<h3>Per code object events<a class="headerlink" href="#per-code-object-events" title="Link to this heading">¶</a></h3>543<p>Events can also be controlled on a per code object basis. The functions544defined below which accept a <a class="reference internal" href="types.html#types.CodeType" title="types.CodeType"><code class="xref py py-class docutils literal notranslate"><span class="pre">types.CodeType</span></code></a> should be prepared545to accept a look-alike object from functions which are not defined546in Python (see <a class="reference internal" href="../c-api/monitoring.html#c-api-monitoring"><span class="std std-ref">Monitoring C API</span></a>).</p>547<dl class="py function">548<dt class="sig sig-object py" id="sys.monitoring.get_local_events">549<span class="sig-prename descclassname"><span class="pre">sys.monitoring.</span></span><span class="sig-name descname"><span class="pre">get_local_events</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">tool_id</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="functions.html#int" title="int"><span class="pre">int</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">code</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="types.html#types.CodeType" title="types.CodeType"><span class="pre">CodeType</span></a></span></em>, <em class="sig-param"><span class="positional-only-separator o"><abbr title="Positional-only parameter separator (PEP 570)"><span class="pre">/</span></abbr></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">→</span> <span class="sig-return-typehint"><a class="reference internal" href="functions.html#int" title="int"><span class="pre">int</span></a></span></span><a class="headerlink" href="#sys.monitoring.get_local_events" title="Link to this definition">¶</a></dt>550<dd><p>Returns all the <a class="reference internal" href="#monitoring-event-local"><span class="std std-ref">local events</span></a> for <em>code</em></p>551</dd></dl>552 553<dl class="py function">554<dt class="sig sig-object py" id="sys.monitoring.set_local_events">555<span class="sig-prename descclassname"><span class="pre">sys.monitoring.</span></span><span class="sig-name descname"><span class="pre">set_local_events</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">tool_id</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="functions.html#int" title="int"><span class="pre">int</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">code</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="types.html#types.CodeType" title="types.CodeType"><span class="pre">CodeType</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">event_set</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="functions.html#int" title="int"><span class="pre">int</span></a></span></em>, <em class="sig-param"><span class="positional-only-separator o"><abbr title="Positional-only parameter separator (PEP 570)"><span class="pre">/</span></abbr></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">→</span> <span class="sig-return-typehint"><a class="reference internal" href="constants.html#None" title="None"><span class="pre">None</span></a></span></span><a class="headerlink" href="#sys.monitoring.set_local_events" title="Link to this definition">¶</a></dt>556<dd><p>Activates all the <a class="reference internal" href="#monitoring-event-local"><span class="std std-ref">local events</span></a> for <em>code</em>557which are set in <em>event_set</em>. Raises a <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a> if <em>tool_id</em> is not558in use.</p>559</dd></dl>560 561</section>562<section id="disabling-events">563<h3>Disabling events<a class="headerlink" href="#disabling-events" title="Link to this heading">¶</a></h3>564<dl class="py data">565<dt class="sig sig-object py" id="sys.monitoring.DISABLE">566<span class="sig-prename descclassname"><span class="pre">sys.monitoring.</span></span><span class="sig-name descname"><span class="pre">DISABLE</span></span><a class="headerlink" href="#sys.monitoring.DISABLE" title="Link to this definition">¶</a></dt>567<dd><p>A special value that can be returned from a callback function to disable568events for the current code location.</p>569</dd></dl>570 571<p><a class="reference internal" href="#monitoring-event-local"><span class="std std-ref">Local events</span></a> can be disabled for a specific code572location by returning <a class="reference internal" href="#sys.monitoring.DISABLE" title="sys.monitoring.DISABLE"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.monitoring.DISABLE</span></code></a> from a callback function.573This does not change which events are set, or any other code locations for the574same event.</p>575<p>Disabling events for specific locations is very important for high576performance monitoring. For example, a program can be run under a577debugger with no overhead if the debugger disables all monitoring578except for a few breakpoints.</p>579<p>If <a class="reference internal" href="#sys.monitoring.DISABLE" title="sys.monitoring.DISABLE"><code class="xref py py-data docutils literal notranslate"><span class="pre">DISABLE</span></code></a> is returned by a callback for a580<a class="reference internal" href="#monitoring-event-global"><span class="std std-ref">global event</span></a>, <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a> will be raised581by the interpreter in a non-specific location (that is, no traceback will be582provided).</p>583<dl class="py function">584<dt class="sig sig-object py" id="sys.monitoring.restart_events">585<span class="sig-prename descclassname"><span class="pre">sys.monitoring.</span></span><span class="sig-name descname"><span class="pre">restart_events</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">→</span> <span class="sig-return-typehint"><a class="reference internal" href="constants.html#None" title="None"><span class="pre">None</span></a></span></span><a class="headerlink" href="#sys.monitoring.restart_events" title="Link to this definition">¶</a></dt>586<dd><p>Enable all the events that were disabled by <a class="reference internal" href="#sys.monitoring.DISABLE" title="sys.monitoring.DISABLE"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.monitoring.DISABLE</span></code></a>587for all tools.</p>588</dd></dl>589 590</section>591</section>592<section id="registering-callback-functions">593<span id="callbacks"></span><h2>Registering callback functions<a class="headerlink" href="#registering-callback-functions" title="Link to this heading">¶</a></h2>594<dl class="py function">595<dt class="sig sig-object py" id="sys.monitoring.register_callback">596<span class="sig-prename descclassname"><span class="pre">sys.monitoring.</span></span><span class="sig-name descname"><span class="pre">register_callback</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">tool_id</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="functions.html#int" title="int"><span class="pre">int</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">event</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="functions.html#int" title="int"><span class="pre">int</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">func</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="collections.abc.html#collections.abc.Callable" title="collections.abc.Callable"><span class="pre">Callable</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference internal" href="constants.html#None" title="None"><span class="pre">None</span></a></span></em>, <em class="sig-param"><span class="positional-only-separator o"><abbr title="Positional-only parameter separator (PEP 570)"><span class="pre">/</span></abbr></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">→</span> <span class="sig-return-typehint"><a class="reference internal" href="collections.abc.html#collections.abc.Callable" title="collections.abc.Callable"><span class="pre">Callable</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference internal" href="constants.html#None" title="None"><span class="pre">None</span></a></span></span><a class="headerlink" href="#sys.monitoring.register_callback" title="Link to this definition">¶</a></dt>597<dd><p>Registers the callable <em>func</em> for the <em>event</em> with the given <em>tool_id</em></p>598<p>If another callback was registered for the given <em>tool_id</em> and <em>event</em>,599it is unregistered and returned.600Otherwise <code class="xref py py-func docutils literal notranslate"><span class="pre">register_callback()</span></code> returns <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>601<p class="audit-hook">Raises an <a class="reference internal" href="sys.html#auditing"><span class="std std-ref">auditing event</span></a> <code class="docutils literal notranslate"><span class="pre">sys.monitoring.register_callback</span></code> with argument <code class="docutils literal notranslate"><span class="pre">func</span></code>.</p>602</dd></dl>603 604<p>Functions can be unregistered by calling605<code class="docutils literal notranslate"><span class="pre">sys.monitoring.register_callback(tool_id,</span> <span class="pre">event,</span> <span class="pre">None)</span></code>.</p>606<p>Callback functions can be registered and unregistered at any time.</p>607<p>Callbacks are called only once regardless if the event is turned on both608globally and locally. As such, if an event could be turned on for both global609and local events by your code then the callback needs to be written to handle610either trigger.</p>611<section id="callback-function-arguments">612<h3>Callback function arguments<a class="headerlink" href="#callback-function-arguments" title="Link to this heading">¶</a></h3>613<dl class="py data">614<dt class="sig sig-object py" id="sys.monitoring.MISSING">615<span class="sig-prename descclassname"><span class="pre">sys.monitoring.</span></span><span class="sig-name descname"><span class="pre">MISSING</span></span><a class="headerlink" href="#sys.monitoring.MISSING" title="Link to this definition">¶</a></dt>616<dd><p>A special value that is passed to a callback function to indicate617that there are no arguments to the call.</p>618</dd></dl>619 620<p>When an active event occurs, the registered callback function is called.621Callback functions returning an object other than <a class="reference internal" href="#sys.monitoring.DISABLE" title="sys.monitoring.DISABLE"><code class="xref py py-data docutils literal notranslate"><span class="pre">DISABLE</span></code></a> will have no effect.622Different events will provide the callback function with different arguments, as follows:</p>623<ul>624<li><p><a class="reference internal" href="#monitoring-event-PY_START"><code class="xref std std-monitoring-event docutils literal notranslate"><span class="pre">PY_START</span></code></a> and <a class="reference internal" href="#monitoring-event-PY_RESUME"><code class="xref std std-monitoring-event docutils literal notranslate"><span class="pre">PY_RESUME</span></code></a>:</p>625<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">func</span><span class="p">(</span><span class="n">code</span><span class="p">:</span> <span class="n">CodeType</span><span class="p">,</span> <span class="n">instruction_offset</span><span class="p">:</span> <span class="nb">int</span><span class="p">)</span> <span class="o">-></span> <span class="nb">object</span>626</pre></div>627</div>628</li>629<li><p><a class="reference internal" href="#monitoring-event-PY_RETURN"><code class="xref std std-monitoring-event docutils literal notranslate"><span class="pre">PY_RETURN</span></code></a> and <a class="reference internal" href="#monitoring-event-PY_YIELD"><code class="xref std std-monitoring-event docutils literal notranslate"><span class="pre">PY_YIELD</span></code></a>:</p>630<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">func</span><span class="p">(</span><span class="n">code</span><span class="p">:</span> <span class="n">CodeType</span><span class="p">,</span> <span class="n">instruction_offset</span><span class="p">:</span> <span class="nb">int</span><span class="p">,</span> <span class="n">retval</span><span class="p">:</span> <span class="nb">object</span><span class="p">)</span> <span class="o">-></span> <span class="nb">object</span>631</pre></div>632</div>633</li>634<li><p><a class="reference internal" href="#monitoring-event-CALL"><code class="xref std std-monitoring-event docutils literal notranslate"><span class="pre">CALL</span></code></a>, <a class="reference internal" href="#monitoring-event-C_RAISE"><code class="xref std std-monitoring-event docutils literal notranslate"><span class="pre">C_RAISE</span></code></a> and <a class="reference internal" href="#monitoring-event-C_RETURN"><code class="xref std std-monitoring-event docutils literal notranslate"><span class="pre">C_RETURN</span></code></a>635(<em>arg0</em> can be <a class="reference internal" href="#sys.monitoring.MISSING" title="sys.monitoring.MISSING"><code class="xref py py-data docutils literal notranslate"><span class="pre">MISSING</span></code></a> specifically):</p>636<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">func</span><span class="p">(</span><span class="n">code</span><span class="p">:</span> <span class="n">CodeType</span><span class="p">,</span> <span class="n">instruction_offset</span><span class="p">:</span> <span class="nb">int</span><span class="p">,</span> <span class="nb">callable</span><span class="p">:</span> <span class="nb">object</span><span class="p">,</span> <span class="n">arg0</span><span class="p">:</span> <span class="nb">object</span><span class="p">)</span> <span class="o">-></span> <span class="nb">object</span>637</pre></div>638</div>639<p><em>code</em> represents the code object where the call is being made, while640<em>callable</em> is the object that is about to be called (and thus641triggered the event).642If there are no arguments, <em>arg0</em> is set to <a class="reference internal" href="#sys.monitoring.MISSING" title="sys.monitoring.MISSING"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.monitoring.MISSING</span></code></a>.</p>643<p>For instance methods, <em>callable</em> will be the function object as found on the644class with <em>arg0</em> set to the instance (i.e. the <code class="docutils literal notranslate"><span class="pre">self</span></code> argument to the645method).</p>646</li>647<li><p><a class="reference internal" href="#monitoring-event-RAISE"><code class="xref std std-monitoring-event docutils literal notranslate"><span class="pre">RAISE</span></code></a>, <a class="reference internal" href="#monitoring-event-RERAISE"><code class="xref std std-monitoring-event docutils literal notranslate"><span class="pre">RERAISE</span></code></a>, <a class="reference internal" href="#monitoring-event-EXCEPTION_HANDLED"><code class="xref std std-monitoring-event docutils literal notranslate"><span class="pre">EXCEPTION_HANDLED</span></code></a>,648<a class="reference internal" href="#monitoring-event-PY_UNWIND"><code class="xref std std-monitoring-event docutils literal notranslate"><span class="pre">PY_UNWIND</span></code></a>, <a class="reference internal" href="#monitoring-event-PY_THROW"><code class="xref std std-monitoring-event docutils literal notranslate"><span class="pre">PY_THROW</span></code></a> and <a class="reference internal" href="#monitoring-event-STOP_ITERATION"><code class="xref std std-monitoring-event docutils literal notranslate"><span class="pre">STOP_ITERATION</span></code></a>:</p>649<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">func</span><span class="p">(</span><span class="n">code</span><span class="p">:</span> <span class="n">CodeType</span><span class="p">,</span> <span class="n">instruction_offset</span><span class="p">:</span> <span class="nb">int</span><span class="p">,</span> <span class="n">exception</span><span class="p">:</span> <span class="ne">BaseException</span><span class="p">)</span> <span class="o">-></span> <span class="nb">object</span>650</pre></div>651</div>652</li>653<li><p><a class="reference internal" href="#monitoring-event-LINE"><code class="xref std std-monitoring-event docutils literal notranslate"><span class="pre">LINE</span></code></a>:</p>654<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">func</span><span class="p">(</span><span class="n">code</span><span class="p">:</span> <span class="n">CodeType</span><span class="p">,</span> <span class="n">line_number</span><span class="p">:</span> <span class="nb">int</span><span class="p">)</span> <span class="o">-></span> <span class="nb">object</span>655</pre></div>656</div>657</li>658<li><p><a class="reference internal" href="#monitoring-event-BRANCH_LEFT"><code class="xref std std-monitoring-event docutils literal notranslate"><span class="pre">BRANCH_LEFT</span></code></a>, <a class="reference internal" href="#monitoring-event-BRANCH_RIGHT"><code class="xref std std-monitoring-event docutils literal notranslate"><span class="pre">BRANCH_RIGHT</span></code></a> and <a class="reference internal" href="#monitoring-event-JUMP"><code class="xref std std-monitoring-event docutils literal notranslate"><span class="pre">JUMP</span></code></a>:</p>659<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">func</span><span class="p">(</span><span class="n">code</span><span class="p">:</span> <span class="n">CodeType</span><span class="p">,</span> <span class="n">instruction_offset</span><span class="p">:</span> <span class="nb">int</span><span class="p">,</span> <span class="n">destination_offset</span><span class="p">:</span> <span class="nb">int</span><span class="p">)</span> <span class="o">-></span> <span class="nb">object</span>660</pre></div>661</div>662<p>Note that the <em>destination_offset</em> is where the code will next execute.</p>663</li>664<li><p><a class="reference internal" href="#monitoring-event-INSTRUCTION"><code class="xref std std-monitoring-event docutils literal notranslate"><span class="pre">INSTRUCTION</span></code></a>:</p>665<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">func</span><span class="p">(</span><span class="n">code</span><span class="p">:</span> <span class="n">CodeType</span><span class="p">,</span> <span class="n">instruction_offset</span><span class="p">:</span> <span class="nb">int</span><span class="p">)</span> <span class="o">-></span> <span class="nb">object</span>666</pre></div>667</div>668</li>669</ul>670</section>671</section>672</section>673 674 675 <div class="clearer"></div>676 </div>677 </div>678 </div>679 <div class="sphinxsidebar" role="navigation" aria-label="Main">680 <div class="sphinxsidebarwrapper">681 <div>682 <h3><a href="../contents.html">Table of Contents</a></h3>683 <ul>684<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">sys.monitoring</span></code> — Execution event monitoring</a><ul>685<li><a class="reference internal" href="#tool-identifiers">Tool identifiers</a><ul>686<li><a class="reference internal" href="#registering-and-using-tools">Registering and using tools</a></li>687</ul>688</li>689<li><a class="reference internal" href="#events">Events</a><ul>690<li><a class="reference internal" href="#local-events">Local events</a></li>691<li><a class="reference internal" href="#deprecated-event">Deprecated event</a></li>692<li><a class="reference internal" href="#ancillary-events">Ancillary events</a></li>693<li><a class="reference internal" href="#other-events">Other events</a></li>694<li><a class="reference internal" href="#the-stop-iteration-event">The STOP_ITERATION event</a></li>695</ul>696</li>697<li><a class="reference internal" href="#turning-events-on-and-off">Turning events on and off</a><ul>698<li><a class="reference internal" href="#setting-events-globally">Setting events globally</a></li>699<li><a class="reference internal" href="#per-code-object-events">Per code object events</a></li>700<li><a class="reference internal" href="#disabling-events">Disabling events</a></li>701</ul>702</li>703<li><a class="reference internal" href="#registering-callback-functions">Registering callback functions</a><ul>704<li><a class="reference internal" href="#callback-function-arguments">Callback function arguments</a></li>705</ul>706</li>707</ul>708</li>709</ul>710 711 </div>712 <div>713 <h4>Previous topic</h4>714 <p class="topless"><a href="sys.html"715 title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">sys</span></code> — System-specific parameters and functions</a></p>716 </div>717 <div>718 <h4>Next topic</h4>719 <p class="topless"><a href="sysconfig.html"720 title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">sysconfig</span></code> — Provide access to Python’s configuration information</a></p>721 </div>722 <script>723 document.addEventListener('DOMContentLoaded', () => {724 const title = document.querySelector('meta[property="og:title"]').content;725 const elements = document.querySelectorAll('.improvepage');726 const pageurl = window.location.href.split('?')[0];727 elements.forEach(element => {728 const url = new URL(element.href.split('?')[0].replace("-nojs", ""));729 url.searchParams.set('pagetitle', title);730 url.searchParams.set('pageurl', pageurl);731 url.searchParams.set('pagesource', "library/sys.monitoring.rst");732 element.href = url.toString();733 });734 });735 </script>736 <div role="note" aria-label="source link">737 <h3>This page</h3>738 <ul class="this-page-menu">739 <li><a href="../bugs.html">Report a bug</a></li>740 <li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>741 <li>742 <a href="https://github.com/python/cpython/blob/main/Doc/library/sys.monitoring.rst?plain=1"743 rel="nofollow">Show source744 </a>745 </li>746 747 </ul>748 </div>749 </div>750<div id="sidebarbutton" title="Collapse sidebar">751<span>«</span>752</div>753 754 </div>755 <div class="clearer"></div>756 </div> 757 <div class="related" role="navigation" aria-label="Related">758 <h3>Navigation</h3>759 <ul>760 <li class="right" style="margin-right: 10px">761 <a href="../genindex.html" title="General Index"762 >index</a></li>763 <li class="right" >764 <a href="../py-modindex.html" title="Python Module Index"765 >modules</a> |</li>766 <li class="right" >767 <a href="sysconfig.html" title="sysconfig — Provide access to Python’s configuration information"768 >next</a> |</li>769 <li class="right" >770 <a href="sys.html" title="sys — System-specific parameters and functions"771 >previous</a> |</li>772 773 <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>774 <li><a href="https://www.python.org/">Python</a> »</li>775 <li class="switchers">776 <div class="language_switcher_placeholder"></div>777 <div class="version_switcher_placeholder"></div>778 </li>779 <li>780 781 </li>782 <li id="cpython-language-and-version">783 <a href="../index.html">3.15.0a6 Documentation</a> »784 </li>785 786 <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>787 <li class="nav-item nav-item-2"><a href="python.html" >Python Runtime Services</a> »</li>788 <li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">sys.monitoring</span></code> — Execution event monitoring</a></li>789 <li class="right">790 791 792 <div class="inline-search" role="search">793 <form class="inline-search" action="../search.html" method="get">794 <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box">795 <input type="submit" value="Go">796 </form>797 </div>798 |799 </li>800 <li class="right">801<label class="theme-selector-label">802 Theme803 <select class="theme-selector" oninput="activateTheme(this.value)">804 <option value="auto" selected>Auto</option>805 <option value="light">Light</option>806 <option value="dark">Dark</option>807 </select>808</label> |</li>809 810 </ul>811 </div> 812 <div class="footer">813 © <a href="../copyright.html">Copyright</a> 2001 Python Software Foundation.814 <br>815 This page is licensed under the Python Software Foundation License Version 2.816 <br>817 Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.818 <br>819 820 See <a href="/license.html">History and License</a> for more information.<br>821 822 823 <br>824 825 The Python Software Foundation is a non-profit corporation.826<a href="https://www.python.org/psf/donations/">Please donate.</a>827<br>828 <br>829 Last updated on Mar 10, 2026 (08:58 UTC).830 831 <a href="/bugs.html">Found a bug</a>?832 833 <br>834 835 Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 8.2.3.836 </div>837 838 </body>839</html>