orbit-oss/flask
4
4
Fork 2
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

[pre-commit.ci lite] apply automatic fixes

Browse source
This commit is contained in:
pre-commit-ci-lite[bot] 2025-04-11 03:04:22 +00:00 • committed by GitHub
parent b3ae3117f9
commit 3d83d8138c
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
102 changed files with 26790 additions and 26749 deletions
Download patch file Download diff file Expand all files Collapse all files

201
flask-docs/debugging.html
View file

@ -1,125 +1,111 @@
<!DOCTYPE html>
<html lang="en" data-content_root="./">
<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">
<title>Debugging Application Errors &#8212; Flask Documentation (3.2.x)</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=6625fa76" />
<link rel="stylesheet" type="text/css" href="_static/flask.css?v=b87c8d14" />
<script src="_static/documentation_options.js?v=56528222"></script>
<script src="_static/doctools.js?v=9bcbadda"></script>
<script src="_static/sphinx_highlight.js?v=dc90522c"></script>
<script data-project="flask" data-version="3.2.x" src="_static/describe_version.js?v=fa7f30d0"></script>
<link rel="icon" href="_static/shortcut-icon.png"/>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Logging" href="logging.html" />
<link rel="prev" title="Handling Application Errors" href="errorhandling.html" />
<title>eventlet &#8212; Flask Documentation (3.2.x)</title>
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=6625fa76" />
<link rel="stylesheet" type="text/css" href="../_static/flask.css?v=b87c8d14" />
<script src="../_static/documentation_options.js?v=56528222"></script>
<script src="../_static/doctools.js?v=9bcbadda"></script>
<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
<script data-project="flask" data-version="3.2.x" src="../_static/describe_version.js?v=fa7f30d0"></script>
<link rel="icon" href="../_static/shortcut-icon.png"/>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="ASGI" href="asgi.html" />
<link rel="prev" title="gevent" href="gevent.html" />
</head><body>
<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"
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="py-modindex.html" title="Python Module Index"
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="logging.html" title="Logging"
<a href="asgi.html" title="ASGI"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="errorhandling.html" title="Handling Application Errors"
<a href="gevent.html" title="gevent"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">Flask Documentation (3.2.x)</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Debugging Application Errors</a></li>
<li class="nav-item nav-item-0"><a href="../index.html">Flask Documentation (3.2.x)</a> &#187;</li>
<li class="nav-item nav-item-1"><a href="index.html" accesskey="U">Deploying to Production</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">eventlet</a></li>
</ul>
</div>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="debugging-application-errors">
<h1>Debugging Application Errors<a class="headerlink" href="#debugging-application-errors" title="Link to this heading"></a></h1>
<section id="in-production">
<h2>In Production<a class="headerlink" href="#in-production" title="Link to this heading"></a></h2>
<p><strong>Do not run the development server, or enable the built-in debugger, in
a production environment.</strong> The debugger allows executing arbitrary
Python code from the browser. It’s protected by a pin, but that should
not be relied on for security.</p>
<p>Use an error logging tool, such as Sentry, as described in
<a class="reference internal" href="errorhandling.html#error-logging-tools"><span class="std std-ref">Error Logging Tools</span></a>, or enable logging and notifications as
described in <a class="reference internal" href="logging.html"><span class="doc">Logging</span></a>.</p>
<p>If you have access to the server, you could add some code to start an
external debugger if <code class="docutils literal notranslate"><span class="pre">request.remote_addr</span></code> matches your IP. Some IDE
debuggers also have a remote mode so breakpoints on the server can be
interacted with locally. Only enable a debugger temporarily.</p>
<section id="eventlet">
<h1>eventlet<a class="headerlink" href="#eventlet" title="Link to this heading"></a></h1>
<p>Prefer using <a class="reference internal" href="gunicorn.html"><span class="doc">Gunicorn</span></a> with eventlet workers rather than using
<a class="reference external" href="https://eventlet.net/">eventlet</a> directly. Gunicorn provides a much more configurable and
production-tested server.</p>
<p><a class="reference external" href="https://eventlet.net/">eventlet</a> allows writing asynchronous, coroutine-based code that looks
like standard synchronous Python. It uses <a class="reference external" href="https://greenlet.readthedocs.io/en/latest/">greenlet</a> to enable task
switching without writing <code class="docutils literal notranslate"><span class="pre">async/await</span></code> or using <code class="docutils literal notranslate"><span class="pre">asyncio</span></code>.</p>
<p><a class="reference internal" href="gevent.html"><span class="doc">gevent</span></a> is another library that does the same thing. Certain
dependencies you have, or other considerations, may affect which of the
two you choose to use.</p>
<p>eventlet provides a WSGI server that can handle many connections at once
instead of one per worker process. You must actually use eventlet in
your own code to see any benefit to using the server.</p>
<section id="installing">
<h2>Installing<a class="headerlink" href="#installing" title="Link to this heading"></a></h2>
<p>When using eventlet, greenlet&gt;=1.0 is required, otherwise context locals
such as <code class="docutils literal notranslate"><span class="pre">request</span></code> will not work as expected. When using PyPy,
PyPy&gt;=7.3.7 is required.</p>
<p>Create a virtualenv, install your application, then install
<code class="docutils literal notranslate"><span class="pre">eventlet</span></code>.</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ cd hello-app
$ python -m venv .venv
$ . .venv/bin/activate
$ pip install . # install your application
$ pip install eventlet
</pre></div>
</div>
</section>
<section id="the-built-in-debugger">
<h2>The Built-In Debugger<a class="headerlink" href="#the-built-in-debugger" title="Link to this heading"></a></h2>
<p>The built-in Werkzeug development server provides a debugger which shows
an interactive traceback in the browser when an unhandled error occurs
during a request. This debugger should only be used during development.</p>
<img alt="screenshot of debugger in action" class="screenshot align-center" src="_images/debugger.png" />
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>The debugger allows executing arbitrary Python code from the
browser. It is protected by a pin, but still represents a major
security risk. Do not run the development server or debugger in a
production environment.</p>
</div>
<p>The debugger is enabled by default when the development server is run in debug mode.</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ flask --app hello run --debug
<section id="running">
<h2>Running<a class="headerlink" href="#running" title="Link to this heading"></a></h2>
<p>To use eventlet to serve your application, write a script that imports
its <code class="docutils literal notranslate"><span class="pre">wsgi.server</span></code>, as well as your app or app factory.</p>
<div class="literal-block-wrapper docutils container" id="id2">
<div class="code-block-caption"><span class="caption-text"><code class="docutils literal notranslate"><span class="pre">wsgi.py</span></code></span><a class="headerlink" href="#id2" title="Link to this code"></a></div>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">eventlet</span>
<span class="kn">from</span><span class="w"> </span><span class="nn">eventlet</span><span class="w"> </span><span class="kn">import</span> <span class="n">wsgi</span>
<span class="kn">from</span><span class="w"> </span><span class="nn">hello</span><span class="w"> </span><span class="kn">import</span> <span class="n">create_app</span>
<span class="n">app</span> <span class="o">=</span> <span class="n">create_app</span><span class="p">()</span>
<span class="n">wsgi</span><span class="o">.</span><span class="n">server</span><span class="p">(</span><span class="n">eventlet</span><span class="o">.</span><span class="n">listen</span><span class="p">((</span><span class="s2">&quot;127.0.0.1&quot;</span><span class="p">,</span> <span class="mi">8000</span><span class="p">)),</span> <span class="n">app</span><span class="p">)</span>
</pre></div>
</div>
<p>When running from Python code, passing <code class="docutils literal notranslate"><span class="pre">debug=True</span></code> enables debug mode, which is
mostly equivalent.</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">app</span><span class="o">.</span><span class="n">run</span><span class="p">(</span><span class="n">debug</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
</div>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ python wsgi.py
(x) wsgi starting up on http://127.0.0.1:8000
</pre></div>
</div>
<p><a class="reference internal" href="server.html"><span class="doc">Development Server</span></a> and <a class="reference internal" href="cli.html"><span class="doc">Command Line Interface</span></a> have more information about running the debugger and
debug mode. More information about the debugger can be found in the <a class="reference external" href="https://werkzeug.palletsprojects.com/debug/">Werkzeug
documentation</a>.</p>
</section>
<section id="external-debuggers">
<h2>External Debuggers<a class="headerlink" href="#external-debuggers" title="Link to this heading"></a></h2>
<p>External debuggers, such as those provided by IDEs, can offer a more
powerful debugging experience than the built-in debugger. They can also
be used to step through code during a request before an error is raised,
or if no error is raised. Some even have a remote mode so you can debug
code running on another machine.</p>
<p>When using an external debugger, the app should still be in debug mode, otherwise Flask
turns unhandled errors into generic 500 error pages. However, the built-in debugger and
reloader should be disabled so they don’t interfere with the external debugger.</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ flask --app hello run --debug --no-debugger --no-reload
</pre></div>
</div>
<p>When running from Python:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">app</span><span class="o">.</span><span class="n">run</span><span class="p">(</span><span class="n">debug</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">use_debugger</span><span class="o">=</span><span class="kc">False</span><span class="p">,</span> <span class="n">use_reloader</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span>
</pre></div>
</div>
<p>Disabling these isn’t required, an external debugger will continue to work with the
following caveats.</p>
<ul>
<li><p>If the built-in debugger is not disabled, it will catch unhandled exceptions before
the external debugger can.</p></li>
<li><p>If the reloader is not disabled, it could cause an unexpected reload if code changes
during a breakpoint.</p></li>
<li><p>The development server will still catch unhandled exceptions if the built-in
debugger is disabled, otherwise it would crash on any error. If you want that (and
usually you don’t) pass <code class="docutils literal notranslate"><span class="pre">passthrough_errors=True</span></code> to <code class="docutils literal notranslate"><span class="pre">app.run</span></code>.</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">app</span><span class="o">.</span><span class="n">run</span><span class="p">(</span>
<span class="n">debug</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">passthrough_errors</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span>
<span class="n">use_debugger</span><span class="o">=</span><span class="kc">False</span><span class="p">,</span> <span class="n">use_reloader</span><span class="o">=</span><span class="kc">False</span>
<span class="p">)</span>
</pre></div>
</div>
</li>
</ul>
<section id="binding-externally">
<h2>Binding Externally<a class="headerlink" href="#binding-externally" title="Link to this heading"></a></h2>
<p>eventlet should not be run as root because it would cause your
application code to run as root, which is not secure. However, this
means it will not be possible to bind to port 80 or 443. Instead, a
reverse proxy such as <a class="reference internal" href="nginx.html"><span class="doc">nginx</span></a> or <a class="reference internal" href="apache-httpd.html"><span class="doc">Apache httpd</span></a> should be used
in front of eventlet.</p>
<p>You can bind to all external IPs on a non-privileged port by using
<code class="docutils literal notranslate"><span class="pre">0.0.0.0</span></code> in the server arguments shown in the previous section.
Don’t do this when using a reverse proxy setup, otherwise it will be
possible to bypass the proxy.</p>
<p><code class="docutils literal notranslate"><span class="pre">0.0.0.0</span></code> is not a valid address to navigate to, you’d use a specific
IP address in your browser.</p>
</section>
</section>
@ -131,35 +117,38 @@ usually you don’t) pass <code class="docutils literal notranslate"><span class
<span id="sidebar-top"></span>
<div class="sphinxsidebar" role="navigation" aria-label="Main">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="index.html">
<img class="logo" src="_static/flask-vertical.png" alt="Logo of Flask"/>
<p class="logo"><a href="../index.html">
<img class="logo" src="../_static/flask-vertical.png" alt="Logo of Flask"/>
</a></p>
<h3>Contents</h3>
<ul>
<li><a class="reference internal" href="#">Debugging Application Errors</a><ul>
<li><a class="reference internal" href="#in-production">In Production</a></li>
<li><a class="reference internal" href="#the-built-in-debugger">The Built-In Debugger</a></li>
<li><a class="reference internal" href="#external-debuggers">External Debuggers</a></li>
<li><a class="reference internal" href="#">eventlet</a><ul>
<li><a class="reference internal" href="#installing">Installing</a></li>
<li><a class="reference internal" href="#running">Running</a></li>
<li><a class="reference internal" href="#binding-externally">Binding Externally</a></li>
</ul>
</li>
</ul>
<h3>Navigation</h3>
<ul>
<li><a href="index.html">Overview</a>
<li><a href="../index.html">Overview</a>
<ul>
<li>Previous: <a href="errorhandling.html" title="previous chapter">Handling Application Errors</a>
<li>Next: <a href="logging.html" title="next chapter">Logging</a>
<li><a href="index.html">Deploying to Production</a>
<ul>
<li>Previous: <a href="gevent.html" title="previous chapter">gevent</a>
<li>Next: <a href="asgi.html" title="next chapter">ASGI</a></ul>
</li>
</ul>
</li>
</ul>
<search id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="search.html" method="get">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
@ -175,4 +164,4 @@ usually you don’t) pass <code class="docutils literal notranslate"><span class
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 8.1.3.
</div>
</body>
</html>
</html>