bunny-lab/Borealis
bunny-lab/Borealis
2
0
Fork 0
Code Issues 10 Pull Requests Actions Packages Projects 1 Releases Wiki Activity
Borealis/Dependencies/Python/Doc/html/library/devmode.html

526 lines
35 KiB
HTML
Raw Blame History

<!DOCTYPE html>
<html lang="en" data-content_root="../">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<meta property="og:title" content="Python Development Mode" />
<meta property="og:type" content="website" />
<meta property="og:url" content="https://docs.python.org/3/library/devmode.html" />
<meta property="og:site_name" content="Python documentation" />
<meta property="og:description" content="The Python Development Mode introduces additional runtime checks that are too expensive to be enabled by default. It should not be more verbose than the default if the code is correct; new warnings..." />
<meta property="og:image" content="https://docs.python.org/3/_static/og-image.png" />
<meta property="og:image:alt" content="Python documentation" />
<meta name="description" content="The Python Development Mode introduces additional runtime checks that are too expensive to be enabled by default. It should not be more verbose than the default if the code is correct; new warnings..." />
<meta property="og:image:width" content="200">
<meta property="og:image:height" content="200">
<meta name="theme-color" content="#3776ab">
<title>Python Development Mode &#8212; Python 3.13.3 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=b86133f3" />
<link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=23252803" />
<link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=5349f25f" />
<script src="../_static/documentation_options.js?v=5d57ca2d"></script>
<script src="../_static/doctools.js?v=9bcbadda"></script>
<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 3.13.3 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="doctest — Test interactive Python examples" href="doctest.html" />
<link rel="prev" title="pydoc — Documentation generator and online help system" href="pydoc.html" />
<link rel="canonical" href="https://docs.python.org/3/library/devmode.html">
<style>
@media only screen {
table.full-width-table {
width: 100%;
}
}
</style>
<link rel="stylesheet" href="../_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css">
<link rel="shortcut icon" type="image/png" href="../_static/py.svg" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
<script type="text/javascript" src="../_static/menu.js"></script>
<script type="text/javascript" src="../_static/search-focus.js"></script>
<script type="text/javascript" src="../_static/themetoggle.js"></script>
<script type="text/javascript" src="../_static/rtd_switcher.js"></script>
<meta name="readthedocs-addons-api-version" content="1">
</head>
<body>
<div class="mobile-nav">
<input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"
aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu" />
<nav class="nav-content" role="navigation">
<label for="menuToggler" class="toggler__label">
<span></span>
</label>
<span class="nav-items-wrapper">
<a href="https://www.python.org/" class="nav-logo">
<img src="../_static/py.svg" alt="Python logo"/>
</a>
<span class="version_switcher_placeholder"></span>
<form role="search" class="search" action="../search.html" method="get">
<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">
<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>
</svg>
<input placeholder="Quick search" aria-label="Quick search" type="search" name="q" />
<input type="submit" value="Go"/>
</form>
</span>
</nav>
<div class="menu-wrapper">
<nav class="menu" role="navigation" aria-label="main navigation">
<div class="language_switcher_placeholder"></div>
<label class="theme-selector-label">
Theme
<select class="theme-selector" oninput="activateTheme(this.value)">
<option value="auto" selected>Auto</option>
<option value="light">Light</option>
<option value="dark">Dark</option>
</select>
</label>
<div>
<h3><a href="../contents.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Python Development Mode</a><ul>
<li><a class="reference internal" href="#effects-of-the-python-development-mode">Effects of the Python Development Mode</a></li>
<li><a class="reference internal" href="#resourcewarning-example">ResourceWarning Example</a></li>
<li><a class="reference internal" href="#bad-file-descriptor-error-example">Bad file descriptor error example</a></li>
</ul>
</li>
</ul>
</div>
<div>
<h4>Previous topic</h4>
<p class="topless"><a href="pydoc.html"
title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">pydoc</span></code> — Documentation generator and online help system</a></p>
</div>
<div>
<h4>Next topic</h4>
<p class="topless"><a href="doctest.html"
title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">doctest</span></code> — Test interactive Python examples</a></p>
</div>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../bugs.html">Report a Bug</a></li>
<li>
<a href="https://github.com/python/cpython/blob/main/Doc/library/devmode.rst"
rel="nofollow">Show Source
</a>
</li>
</ul>
</div>
</nav>
</div>
</div>
<div class="related" role="navigation" aria-label="Related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="doctest.html" title="doctest — Test interactive Python examples"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="pydoc.html" title="pydoc — Documentation generator and online help system"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> &#187;</li>
<li class="switchers">
<div class="language_switcher_placeholder"></div>
<div class="version_switcher_placeholder"></div>
</li>
<li>
</li>
<li id="cpython-language-and-version">
<a href="../index.html">3.13.3 Documentation</a> &#187;
</li>
<li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> &#187;</li>
<li class="nav-item nav-item-2"><a href="development.html" accesskey="U">Development Tools</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Python Development Mode</a></li>
<li class="right">
<div class="inline-search" role="search">
<form class="inline-search" action="../search.html" method="get">
<input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box" />
<input type="submit" value="Go" />
</form>
</div>
|
</li>
<li class="right">
<label class="theme-selector-label">
Theme
<select class="theme-selector" oninput="activateTheme(this.value)">
<option value="auto" selected>Auto</option>
<option value="light">Light</option>
<option value="dark">Dark</option>
</select>
</label> |</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="python-development-mode">
<span id="devmode"></span><h1>Python Development Mode<a class="headerlink" href="#python-development-mode" title="Link to this heading"></a></h1>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.7.</span></p>
</div>
<p>The Python Development Mode introduces additional runtime checks that are too
expensive to be enabled by default. It should not be more verbose than the
default if the code is correct; new warnings are only emitted when an issue is
detected.</p>
<p>It can be enabled using the <a class="reference internal" href="../using/cmdline.html#cmdoption-X"><code class="xref std std-option docutils literal notranslate"><span class="pre">-X</span> <span class="pre">dev</span></code></a> command line option or by
setting the <span class="target" id="index-0"></span><a class="reference internal" href="../using/cmdline.html#envvar-PYTHONDEVMODE"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PYTHONDEVMODE</span></code></a> environment variable to <code class="docutils literal notranslate"><span class="pre">1</span></code>.</p>
<p>See also <a class="reference internal" href="../using/configure.html#debug-build"><span class="std std-ref">Python debug build</span></a>.</p>
<section id="effects-of-the-python-development-mode">
<h2>Effects of the Python Development Mode<a class="headerlink" href="#effects-of-the-python-development-mode" title="Link to this heading"></a></h2>
<p>Enabling the Python Development Mode is similar to the following command, but
with additional effects described below:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">PYTHONMALLOC</span><span class="o">=</span><span class="n">debug</span> <span class="n">PYTHONASYNCIODEBUG</span><span class="o">=</span><span class="mi">1</span> <span class="n">python</span> <span class="o">-</span><span class="n">W</span> <span class="n">default</span> <span class="o">-</span><span class="n">X</span> <span class="n">faulthandler</span>
</pre></div>
</div>
<p>Effects of the Python Development Mode:</p>
<ul>
<li><p>Add <code class="docutils literal notranslate"><span class="pre">default</span></code> <a class="reference internal" href="warnings.html#describing-warning-filters"><span class="std std-ref">warning filter</span></a>. The
following warnings are shown:</p>
<ul class="simple">
<li><p><a class="reference internal" href="exceptions.html#DeprecationWarning" title="DeprecationWarning"><code class="xref py py-exc docutils literal notranslate"><span class="pre">DeprecationWarning</span></code></a></p></li>
<li><p><a class="reference internal" href="exceptions.html#ImportWarning" title="ImportWarning"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ImportWarning</span></code></a></p></li>
<li><p><a class="reference internal" href="exceptions.html#PendingDeprecationWarning" title="PendingDeprecationWarning"><code class="xref py py-exc docutils literal notranslate"><span class="pre">PendingDeprecationWarning</span></code></a></p></li>
<li><p><a class="reference internal" href="exceptions.html#ResourceWarning" title="ResourceWarning"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ResourceWarning</span></code></a></p></li>
</ul>
<p>Normally, the above warnings are filtered by the default <a class="reference internal" href="warnings.html#describing-warning-filters"><span class="std std-ref">warning
filters</span></a>.</p>
<p>It behaves as if the <a class="reference internal" href="../using/cmdline.html#cmdoption-W"><code class="xref std std-option docutils literal notranslate"><span class="pre">-W</span> <span class="pre">default</span></code></a> command line option is used.</p>
<p>Use the <a class="reference internal" href="../using/cmdline.html#cmdoption-W"><code class="xref std std-option docutils literal notranslate"><span class="pre">-W</span> <span class="pre">error</span></code></a> command line option or set the
<span class="target" id="index-1"></span><a class="reference internal" href="../using/cmdline.html#envvar-PYTHONWARNINGS"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PYTHONWARNINGS</span></code></a> environment variable to <code class="docutils literal notranslate"><span class="pre">error</span></code> to treat warnings
as errors.</p>
</li>
<li><p>Install debug hooks on memory allocators to check for:</p>
<ul class="simple">
<li><p>Buffer underflow</p></li>
<li><p>Buffer overflow</p></li>
<li><p>Memory allocator API violation</p></li>
<li><p>Unsafe usage of the GIL</p></li>
</ul>
<p>See the <a class="reference internal" href="../c-api/memory.html#c.PyMem_SetupDebugHooks" title="PyMem_SetupDebugHooks"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyMem_SetupDebugHooks()</span></code></a> C function.</p>
<p>It behaves as if the <span class="target" id="index-2"></span><a class="reference internal" href="../using/cmdline.html#envvar-PYTHONMALLOC"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PYTHONMALLOC</span></code></a> environment variable is set to
<code class="docutils literal notranslate"><span class="pre">debug</span></code>.</p>
<p>To enable the Python Development Mode without installing debug hooks on
memory allocators, set the <span class="target" id="index-3"></span><a class="reference internal" href="../using/cmdline.html#envvar-PYTHONMALLOC"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PYTHONMALLOC</span></code></a> environment variable to
<code class="docutils literal notranslate"><span class="pre">default</span></code>.</p>
</li>
<li><p>Call <a class="reference internal" href="faulthandler.html#faulthandler.enable" title="faulthandler.enable"><code class="xref py py-func docutils literal notranslate"><span class="pre">faulthandler.enable()</span></code></a> at Python startup to install handlers for
the <a class="reference internal" href="signal.html#signal.SIGSEGV" title="signal.SIGSEGV"><code class="xref py py-const docutils literal notranslate"><span class="pre">SIGSEGV</span></code></a>, <a class="reference internal" href="signal.html#signal.SIGFPE" title="signal.SIGFPE"><code class="xref py py-const docutils literal notranslate"><span class="pre">SIGFPE</span></code></a>,
<a class="reference internal" href="signal.html#signal.SIGABRT" title="signal.SIGABRT"><code class="xref py py-const docutils literal notranslate"><span class="pre">SIGABRT</span></code></a>, <a class="reference internal" href="signal.html#signal.SIGBUS" title="signal.SIGBUS"><code class="xref py py-const docutils literal notranslate"><span class="pre">SIGBUS</span></code></a> and
<a class="reference internal" href="signal.html#signal.SIGILL" title="signal.SIGILL"><code class="xref py py-const docutils literal notranslate"><span class="pre">SIGILL</span></code></a> signals to dump the Python traceback on a crash.</p>
<p>It behaves as if the <a class="reference internal" href="../using/cmdline.html#cmdoption-X"><code class="xref std std-option docutils literal notranslate"><span class="pre">-X</span> <span class="pre">faulthandler</span></code></a> command line option is
used or if the <span class="target" id="index-4"></span><a class="reference internal" href="../using/cmdline.html#envvar-PYTHONFAULTHANDLER"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PYTHONFAULTHANDLER</span></code></a> environment variable is set to
<code class="docutils literal notranslate"><span class="pre">1</span></code>.</p>
</li>
<li><p>Enable <a class="reference internal" href="asyncio-dev.html#asyncio-debug-mode"><span class="std std-ref">asyncio debug mode</span></a>. For example,
<a class="reference internal" href="asyncio.html#module-asyncio" title="asyncio: Asynchronous I/O."><code class="xref py py-mod docutils literal notranslate"><span class="pre">asyncio</span></code></a> checks for coroutines that were not awaited and logs them.</p>
<p>It behaves as if the <span class="target" id="index-5"></span><a class="reference internal" href="../using/cmdline.html#envvar-PYTHONASYNCIODEBUG"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PYTHONASYNCIODEBUG</span></code></a> environment variable is set
to <code class="docutils literal notranslate"><span class="pre">1</span></code>.</p>
</li>
<li><p>Check the <em>encoding</em> and <em>errors</em> arguments for string encoding and decoding
operations. Examples: <a class="reference internal" href="functions.html#open" title="open"><code class="xref py py-func docutils literal notranslate"><span class="pre">open()</span></code></a>, <a class="reference internal" href="stdtypes.html#str.encode" title="str.encode"><code class="xref py py-meth docutils literal notranslate"><span class="pre">str.encode()</span></code></a> and
<a class="reference internal" href="stdtypes.html#bytes.decode" title="bytes.decode"><code class="xref py py-meth docutils literal notranslate"><span class="pre">bytes.decode()</span></code></a>.</p>
<p>By default, for best performance, the <em>errors</em> argument is only checked at
the first encoding/decoding error and the <em>encoding</em> argument is sometimes
ignored for empty strings.</p>
</li>
<li><p>The <a class="reference internal" href="io.html#io.IOBase" title="io.IOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">io.IOBase</span></code></a> destructor logs <code class="docutils literal notranslate"><span class="pre">close()</span></code> exceptions.</p></li>
<li><p>Set the <a class="reference internal" href="sys.html#sys.flags.dev_mode" title="sys.flags.dev_mode"><code class="xref py py-attr docutils literal notranslate"><span class="pre">dev_mode</span></code></a> attribute of <a class="reference internal" href="sys.html#sys.flags" title="sys.flags"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.flags</span></code></a> to
<code class="docutils literal notranslate"><span class="pre">True</span></code>.</p></li>
</ul>
<p>The Python Development Mode does not enable the <a class="reference internal" href="tracemalloc.html#module-tracemalloc" title="tracemalloc: Trace memory allocations."><code class="xref py py-mod docutils literal notranslate"><span class="pre">tracemalloc</span></code></a> module by
default, because the overhead cost (to performance and memory) would be too
large. Enabling the <a class="reference internal" href="tracemalloc.html#module-tracemalloc" title="tracemalloc: Trace memory allocations."><code class="xref py py-mod docutils literal notranslate"><span class="pre">tracemalloc</span></code></a> module provides additional information
on the origin of some errors. For example, <a class="reference internal" href="exceptions.html#ResourceWarning" title="ResourceWarning"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ResourceWarning</span></code></a> logs the
traceback where the resource was allocated, and a buffer overflow error logs
the traceback where the memory block was allocated.</p>
<p>The Python Development Mode does not prevent the <a class="reference internal" href="../using/cmdline.html#cmdoption-O"><code class="xref std std-option docutils literal notranslate"><span class="pre">-O</span></code></a> command line
option from removing <a class="reference internal" href="../reference/simple_stmts.html#assert"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">assert</span></code></a> statements nor from setting
<a class="reference internal" href="constants.html#debug__" title="__debug__"><code class="xref py py-const docutils literal notranslate"><span class="pre">__debug__</span></code></a> to <code class="docutils literal notranslate"><span class="pre">False</span></code>.</p>
<p>The Python Development Mode can only be enabled at the Python startup. Its
value can be read from <a class="reference internal" href="sys.html#sys.flags" title="sys.flags"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.flags.dev_mode</span></code></a>.</p>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 3.8: </span>The <a class="reference internal" href="io.html#io.IOBase" title="io.IOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">io.IOBase</span></code></a> destructor now logs <code class="docutils literal notranslate"><span class="pre">close()</span></code> exceptions.</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 3.9: </span>The <em>encoding</em> and <em>errors</em> arguments are now checked for string encoding
and decoding operations.</p>
</div>
</section>
<section id="resourcewarning-example">
<h2>ResourceWarning Example<a class="headerlink" href="#resourcewarning-example" title="Link to this heading"></a></h2>
<p>Example of a script counting the number of lines of the text file specified in
the command line:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">sys</span>
<span class="k">def</span><span class="w"> </span><span class="nf">main</span><span class="p">():</span>
<span class="n">fp</span> <span class="o">=</span> <span class="nb">open</span><span class="p">(</span><span class="n">sys</span><span class="o">.</span><span class="n">argv</span><span class="p">[</span><span class="mi">1</span><span class="p">])</span>
<span class="n">nlines</span> <span class="o">=</span> <span class="nb">len</span><span class="p">(</span><span class="n">fp</span><span class="o">.</span><span class="n">readlines</span><span class="p">())</span>
<span class="nb">print</span><span class="p">(</span><span class="n">nlines</span><span class="p">)</span>
<span class="c1"># The file is closed implicitly</span>
<span class="k">if</span> <span class="vm">__name__</span> <span class="o">==</span> <span class="s2">&quot;__main__&quot;</span><span class="p">:</span>
<span class="n">main</span><span class="p">()</span>
</pre></div>
</div>
<p>The script does not close the file explicitly. By default, Python does not emit
any warning. Example using README.txt, which has 269 lines:</p>
<div class="highlight-shell-session notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>python<span class="w"> </span>script.py<span class="w"> </span>README.txt
<span class="go">269</span>
</pre></div>
</div>
<p>Enabling the Python Development Mode displays a <a class="reference internal" href="exceptions.html#ResourceWarning" title="ResourceWarning"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ResourceWarning</span></code></a> warning:</p>
<div class="highlight-shell-session notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>python<span class="w"> </span>-X<span class="w"> </span>dev<span class="w"> </span>script.py<span class="w"> </span>README.txt
<span class="go">269</span>
<span class="go">script.py:10: ResourceWarning: unclosed file &lt;_io.TextIOWrapper name=&#39;README.rst&#39; mode=&#39;r&#39; encoding=&#39;UTF-8&#39;&gt;</span>
<span class="go"> main()</span>
<span class="go">ResourceWarning: Enable tracemalloc to get the object allocation traceback</span>
</pre></div>
</div>
<p>In addition, enabling <a class="reference internal" href="tracemalloc.html#module-tracemalloc" title="tracemalloc: Trace memory allocations."><code class="xref py py-mod docutils literal notranslate"><span class="pre">tracemalloc</span></code></a> shows the line where the file was
opened:</p>
<div class="highlight-shell-session notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>python<span class="w"> </span>-X<span class="w"> </span>dev<span class="w"> </span>-X<span class="w"> </span><span class="nv">tracemalloc</span><span class="o">=</span><span class="m">5</span><span class="w"> </span>script.py<span class="w"> </span>README.rst
<span class="go">269</span>
<span class="go">script.py:10: ResourceWarning: unclosed file &lt;_io.TextIOWrapper name=&#39;README.rst&#39; mode=&#39;r&#39; encoding=&#39;UTF-8&#39;&gt;</span>
<span class="go"> main()</span>
<span class="go">Object allocated at (most recent call last):</span>
<span class="go"> File &quot;script.py&quot;, lineno 10</span>
<span class="go"> main()</span>
<span class="go"> File &quot;script.py&quot;, lineno 4</span>
<span class="go"> fp = open(sys.argv[1])</span>
</pre></div>
</div>
<p>The fix is to close explicitly the file. Example using a context manager:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span><span class="w"> </span><span class="nf">main</span><span class="p">():</span>
<span class="c1"># Close the file explicitly when exiting the with block</span>
<span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="n">sys</span><span class="o">.</span><span class="n">argv</span><span class="p">[</span><span class="mi">1</span><span class="p">])</span> <span class="k">as</span> <span class="n">fp</span><span class="p">:</span>
<span class="n">nlines</span> <span class="o">=</span> <span class="nb">len</span><span class="p">(</span><span class="n">fp</span><span class="o">.</span><span class="n">readlines</span><span class="p">())</span>
<span class="nb">print</span><span class="p">(</span><span class="n">nlines</span><span class="p">)</span>
</pre></div>
</div>
<p>Not closing a resource explicitly can leave a resource open for way longer than
expected; it can cause severe issues upon exiting Python. It is bad in
CPython, but it is even worse in PyPy. Closing resources explicitly makes an
application more deterministic and more reliable.</p>
</section>
<section id="bad-file-descriptor-error-example">
<h2>Bad file descriptor error example<a class="headerlink" href="#bad-file-descriptor-error-example" title="Link to this heading"></a></h2>
<p>Script displaying the first line of itself:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">os</span>
<span class="k">def</span><span class="w"> </span><span class="nf">main</span><span class="p">():</span>
<span class="n">fp</span> <span class="o">=</span> <span class="nb">open</span><span class="p">(</span><span class="vm">__file__</span><span class="p">)</span>
<span class="n">firstline</span> <span class="o">=</span> <span class="n">fp</span><span class="o">.</span><span class="n">readline</span><span class="p">()</span>
<span class="nb">print</span><span class="p">(</span><span class="n">firstline</span><span class="o">.</span><span class="n">rstrip</span><span class="p">())</span>
<span class="n">os</span><span class="o">.</span><span class="n">close</span><span class="p">(</span><span class="n">fp</span><span class="o">.</span><span class="n">fileno</span><span class="p">())</span>
<span class="c1"># The file is closed implicitly</span>
<span class="n">main</span><span class="p">()</span>
</pre></div>
</div>
<p>By default, Python does not emit any warning:</p>
<div class="highlight-shell-session notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>python<span class="w"> </span>script.py
<span class="go">import os</span>
</pre></div>
</div>
<p>The Python Development Mode shows a <a class="reference internal" href="exceptions.html#ResourceWarning" title="ResourceWarning"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ResourceWarning</span></code></a> and logs a “Bad file
descriptor” error when finalizing the file object:</p>
<div class="highlight-shell-session notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>python<span class="w"> </span>-X<span class="w"> </span>dev<span class="w"> </span>script.py
<span class="go">import os</span>
<span class="go">script.py:10: ResourceWarning: unclosed file &lt;_io.TextIOWrapper name=&#39;script.py&#39; mode=&#39;r&#39; encoding=&#39;UTF-8&#39;&gt;</span>
<span class="go"> main()</span>
<span class="go">ResourceWarning: Enable tracemalloc to get the object allocation traceback</span>
<span class="go">Exception ignored in: &lt;_io.TextIOWrapper name=&#39;script.py&#39; mode=&#39;r&#39; encoding=&#39;UTF-8&#39;&gt;</span>
<span class="go">Traceback (most recent call last):</span>
<span class="go"> File &quot;script.py&quot;, line 10, in &lt;module&gt;</span>
<span class="go"> main()</span>
<span class="go">OSError: [Errno 9] Bad file descriptor</span>
</pre></div>
</div>
<p><code class="docutils literal notranslate"><span class="pre">os.close(fp.fileno())</span></code> closes the file descriptor. When the file object
finalizer tries to close the file descriptor again, it fails with the <code class="docutils literal notranslate"><span class="pre">Bad</span>
<span class="pre">file</span> <span class="pre">descriptor</span></code> error. A file descriptor must be closed only once. In the
worst case scenario, closing it twice can lead to a crash (see <a class="reference external" href="https://bugs.python.org/issue?&#64;action=redirect&amp;bpo=18748">bpo-18748</a>
for an example).</p>
<p>The fix is to remove the <code class="docutils literal notranslate"><span class="pre">os.close(fp.fileno())</span></code> line, or open the file with
<code class="docutils literal notranslate"><span class="pre">closefd=False</span></code>.</p>
</section>
</section>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="Main">
<div class="sphinxsidebarwrapper">
<div>
<h3><a href="../contents.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Python Development Mode</a><ul>
<li><a class="reference internal" href="#effects-of-the-python-development-mode">Effects of the Python Development Mode</a></li>
<li><a class="reference internal" href="#resourcewarning-example">ResourceWarning Example</a></li>
<li><a class="reference internal" href="#bad-file-descriptor-error-example">Bad file descriptor error example</a></li>
</ul>
</li>
</ul>
</div>
<div>
<h4>Previous topic</h4>
<p class="topless"><a href="pydoc.html"
title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">pydoc</span></code> — Documentation generator and online help system</a></p>
</div>
<div>
<h4>Next topic</h4>
<p class="topless"><a href="doctest.html"
title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">doctest</span></code> — Test interactive Python examples</a></p>
</div>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../bugs.html">Report a Bug</a></li>
<li>
<a href="https://github.com/python/cpython/blob/main/Doc/library/devmode.rst"
rel="nofollow">Show Source
</a>
</li>
</ul>
</div>
</div>
<div id="sidebarbutton" title="Collapse sidebar">
<span>«</span>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="Related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="doctest.html" title="doctest — Test interactive Python examples"
>next</a> |</li>
<li class="right" >
<a href="pydoc.html" title="pydoc — Documentation generator and online help system"
>previous</a> |</li>
<li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> &#187;</li>
<li class="switchers">
<div class="language_switcher_placeholder"></div>
<div class="version_switcher_placeholder"></div>
</li>
<li>
</li>
<li id="cpython-language-and-version">
<a href="../index.html">3.13.3 Documentation</a> &#187;
</li>
<li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> &#187;</li>
<li class="nav-item nav-item-2"><a href="development.html" >Development Tools</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Python Development Mode</a></li>
<li class="right">
<div class="inline-search" role="search">
<form class="inline-search" action="../search.html" method="get">
<input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box" />
<input type="submit" value="Go" />
</form>
</div>
|
</li>
<li class="right">
<label class="theme-selector-label">
Theme
<select class="theme-selector" oninput="activateTheme(this.value)">
<option value="auto" selected>Auto</option>
<option value="light">Light</option>
<option value="dark">Dark</option>
</select>
</label> |</li>
</ul>
</div>
<div class="footer">
&copy;
<a href="../copyright.html">
Copyright
</a>
2001-2025, Python Software Foundation.
<br />
This page is licensed under the Python Software Foundation License Version 2.
<br />
Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.
<br />
See <a href="/license.html">History and License</a> for more information.<br />
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
<br />
Last updated on Apr 08, 2025 (14:33 UTC).
<a href="/bugs.html">Found a bug</a>?
<br />
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 8.2.3.
</div>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink