diff options
Diffstat (limited to 'app/static/doc/flask-docs/api.html')
-rw-r--r-- | app/static/doc/flask-docs/api.html | 3475 |
1 files changed, 0 insertions, 3475 deletions
diff --git a/app/static/doc/flask-docs/api.html b/app/static/doc/flask-docs/api.html deleted file mode 100644 index f130677..0000000 --- a/app/static/doc/flask-docs/api.html +++ /dev/null @@ -1,3475 +0,0 @@ - -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" - "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> - - -<html xmlns="http://www.w3.org/1999/xhtml"> - <head> - <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> - - <title>API — Flask 0.8 documentation</title> - - <link rel="stylesheet" href="_static/flasky.css" type="text/css" /> - <link rel="stylesheet" href="_static/pygments.css" type="text/css" /> - - <script type="text/javascript"> - var DOCUMENTATION_OPTIONS = { - URL_ROOT: '', - VERSION: '0.8', - COLLAPSE_INDEX: false, - FILE_SUFFIX: '.html', - HAS_SOURCE: true - }; - </script> - <script type="text/javascript" src="_static/jquery.js"></script> - <script type="text/javascript" src="_static/underscore.js"></script> - <script type="text/javascript" src="_static/doctools.js"></script> - <link rel="top" title="Flask 0.8 documentation" href="index.html" /> - <link rel="next" title="Design Decisions in Flask" href="design.html" /> - <link rel="prev" title="Becoming Big" href="becomingbig.html" /> - - - <link rel="apple-touch-icon" href="_static/touch-icon.png" /> - - <link media="only screen and (max-device-width: 480px)" href="_static/small_flask.css" type= "text/css" rel="stylesheet" /> - - </head> - <body> - <div class="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="design.html" title="Design Decisions in Flask" - accesskey="N">next</a> |</li> - <li class="right" > - <a href="becomingbig.html" title="Becoming Big" - accesskey="P">previous</a> |</li> - <li><a href="index.html">Flask 0.8 documentation</a> »</li> - </ul> - </div> - - <div class="document"> - <div class="documentwrapper"> - <div class="bodywrapper"> - <div class="body"> - - <div class="section" id="api"> -<span id="id1"></span><h1>API<a class="headerlink" href="#api" title="Permalink to this headline">¶</a></h1> -<span class="target" id="module-flask"></span><p>This part of the documentation covers all the interfaces of Flask. For -parts where Flask depends on external libraries, we document the most -important right here and provide links to the canonical documentation.</p> -<div class="section" id="application-object"> -<h2>Application Object<a class="headerlink" href="#application-object" title="Permalink to this headline">¶</a></h2> -<dl class="class"> -<dt id="flask.Flask"> -<em class="property">class </em><tt class="descclassname">flask.</tt><tt class="descname">Flask</tt><big>(</big><em>import_name</em>, <em>static_path=None</em>, <em>static_url_path=None</em>, <em>static_folder='static'</em>, <em>template_folder='templates'</em>, <em>instance_path=None</em>, <em>instance_relative_config=False</em><big>)</big><a class="headerlink" href="#flask.Flask" title="Permalink to this definition">¶</a></dt> -<dd><p>The flask object implements a WSGI application and acts as the central -object. It is passed the name of the module or package of the -application. Once it is created it will act as a central registry for -the view functions, the URL rules, template configuration and much more.</p> -<p>The name of the package is used to resolve resources from inside the -package or the folder the module is contained in depending on if the -package parameter resolves to an actual python package (a folder with -an <cite>__init__.py</cite> file inside) or a standard module (just a <cite>.py</cite> file).</p> -<p>For more information about resource loading, see <a class="reference internal" href="#flask.Flask.open_resource" title="flask.Flask.open_resource"><tt class="xref py py-func docutils literal"><span class="pre">open_resource()</span></tt></a>.</p> -<p>Usually you create a <a class="reference internal" href="#flask.Flask" title="flask.Flask"><tt class="xref py py-class docutils literal"><span class="pre">Flask</span></tt></a> instance in your main module or -in the <cite>__init__.py</cite> file of your package like this:</p> -<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">flask</span> <span class="kn">import</span> <span class="n">Flask</span> -<span class="n">app</span> <span class="o">=</span> <span class="n">Flask</span><span class="p">(</span><span class="n">__name__</span><span class="p">)</span> -</pre></div> -</div> -<div class="admonition-about-the-first-parameter admonition "> -<p class="first admonition-title">About the First Parameter</p> -<p>The idea of the first parameter is to give Flask an idea what -belongs to your application. This name is used to find resources -on the file system, can be used by extensions to improve debugging -information and a lot more.</p> -<p>So it’s important what you provide there. If you are using a single -module, <cite>__name__</cite> is always the correct value. If you however are -using a package, it’s usually recommended to hardcode the name of -your package there.</p> -<p>For example if your application is defined in <cite>yourapplication/app.py</cite> -you should create it with one of the two versions below:</p> -<div class="highlight-python"><div class="highlight"><pre><span class="n">app</span> <span class="o">=</span> <span class="n">Flask</span><span class="p">(</span><span class="s">'yourapplication'</span><span class="p">)</span> -<span class="n">app</span> <span class="o">=</span> <span class="n">Flask</span><span class="p">(</span><span class="n">__name__</span><span class="o">.</span><span class="n">split</span><span class="p">(</span><span class="s">'.'</span><span class="p">)[</span><span class="mi">0</span><span class="p">])</span> -</pre></div> -</div> -<p class="last">Why is that? The application will work even with <cite>__name__</cite>, thanks -to how resources are looked up. However it will make debugging more -painful. Certain extensions can make assumptions based on the -import name of your application. For example the Flask-SQLAlchemy -extension will look for the code in your application that triggered -an SQL query in debug mode. If the import name is not properly set -up, that debugging information is lost. (For example it would only -pick up SQL queries in <cite>yourapplication.app</cite> and not -<cite>yourapplication.views.frontend</cite>)</p> -</div> -<p class="versionadded"> -<span class="versionmodified">New in version 0.7: </span>The <cite>static_url_path</cite>, <cite>static_folder</cite>, and <cite>template_folder</cite> -parameters were added.</p> -<p class="versionadded"> -<span class="versionmodified">New in version 0.8: </span>The <cite>instance_path</cite> and <cite>instance_relative_config</cite> parameters were -added.</p> -<table class="docutils field-list" frame="void" rules="none"> -<col class="field-name" /> -<col class="field-body" /> -<tbody valign="top"> -<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple"> -<li><strong>import_name</strong> – the name of the application package</li> -<li><strong>static_url_path</strong> – can be used to specify a different path for the -static files on the web. Defaults to the name -of the <cite>static_folder</cite> folder.</li> -<li><strong>static_folder</strong> – the folder with static files that should be served -at <cite>static_url_path</cite>. Defaults to the <tt class="docutils literal"><span class="pre">'static'</span></tt> -folder in the root path of the application.</li> -<li><strong>template_folder</strong> – the folder that contains the templates that should -be used by the application. Defaults to -<tt class="docutils literal"><span class="pre">'templates'</span></tt> folder in the root path of the -application.</li> -<li><strong>instance_path</strong> – An alternative instance path for the application. -By default the folder <tt class="docutils literal"><span class="pre">'instance'</span></tt> next to the -package or module is assumed to be the instance -path.</li> -<li><strong>instance_relative_config</strong> – if set to <cite>True</cite> relative filenames -for loading the config are assumed to -be relative to the instance path instead -of the application root.</li> -</ul> -</td> -</tr> -</tbody> -</table> -<dl class="method"> -<dt id="flask.Flask.add_url_rule"> -<tt class="descname">add_url_rule</tt><big>(</big><em>*args</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#flask.Flask.add_url_rule" title="Permalink to this definition">¶</a></dt> -<dd><p>Connects a URL rule. Works exactly like the <a class="reference internal" href="#flask.Flask.route" title="flask.Flask.route"><tt class="xref py py-meth docutils literal"><span class="pre">route()</span></tt></a> -decorator. If a view_func is provided it will be registered with the -endpoint.</p> -<p>Basically this example:</p> -<div class="highlight-python"><div class="highlight"><pre><span class="nd">@app.route</span><span class="p">(</span><span class="s">'/'</span><span class="p">)</span> -<span class="k">def</span> <span class="nf">index</span><span class="p">():</span> - <span class="k">pass</span> -</pre></div> -</div> -<p>Is equivalent to the following:</p> -<div class="highlight-python"><div class="highlight"><pre><span class="k">def</span> <span class="nf">index</span><span class="p">():</span> - <span class="k">pass</span> -<span class="n">app</span><span class="o">.</span><span class="n">add_url_rule</span><span class="p">(</span><span class="s">'/'</span><span class="p">,</span> <span class="s">'index'</span><span class="p">,</span> <span class="n">index</span><span class="p">)</span> -</pre></div> -</div> -<p>If the view_func is not provided you will need to connect the endpoint -to a view function like so:</p> -<div class="highlight-python"><div class="highlight"><pre><span class="n">app</span><span class="o">.</span><span class="n">view_functions</span><span class="p">[</span><span class="s">'index'</span><span class="p">]</span> <span class="o">=</span> <span class="n">index</span> -</pre></div> -</div> -<p>Internally <a class="reference internal" href="#flask.Flask.route" title="flask.Flask.route"><tt class="xref py py-meth docutils literal"><span class="pre">route()</span></tt></a> invokes <a class="reference internal" href="#flask.Flask.add_url_rule" title="flask.Flask.add_url_rule"><tt class="xref py py-meth docutils literal"><span class="pre">add_url_rule()</span></tt></a> so if you want -to customize the behavior via subclassing you only need to change -this method.</p> -<p>For more information refer to <a class="reference internal" href="#url-route-registrations"><em>URL Route Registrations</em></a>.</p> -<p class="versionchanged"> -<span class="versionmodified">Changed in version 0.2: </span><cite>view_func</cite> parameter added.</p> -<p class="versionchanged"> -<span class="versionmodified">Changed in version 0.6: </span><cite>OPTIONS</cite> is added automatically as method.</p> -<table class="docutils field-list" frame="void" rules="none"> -<col class="field-name" /> -<col class="field-body" /> -<tbody valign="top"> -<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple"> -<li><strong>rule</strong> – the URL rule as string</li> -<li><strong>endpoint</strong> – the endpoint for the registered URL rule. Flask -itself assumes the name of the view function as -endpoint</li> -<li><strong>view_func</strong> – the function to call when serving a request to the -provided endpoint</li> -<li><strong>options</strong> – the options to be forwarded to the underlying -<a class="reference external" href="http://werkzeug.pocoo.org/docs/routing/#werkzeug.routing.Rule" title="(in Werkzeug v0.7)"><tt class="xref py py-class docutils literal"><span class="pre">Rule</span></tt></a> object. A change -to Werkzeug is handling of method options. methods -is a list of methods this rule should be limited -to (<cite>GET</cite>, <cite>POST</cite> etc.). By default a rule -just listens for <cite>GET</cite> (and implicitly <cite>HEAD</cite>). -Starting with Flask 0.6, <cite>OPTIONS</cite> is implicitly -added and handled by the standard request handling.</li> -</ul> -</td> -</tr> -</tbody> -</table> -</dd></dl> - -<dl class="method"> -<dt id="flask.Flask.after_request"> -<tt class="descname">after_request</tt><big>(</big><em>*args</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#flask.Flask.after_request" title="Permalink to this definition">¶</a></dt> -<dd><p>Register a function to be run after each request. Your function -must take one parameter, a <a class="reference internal" href="#flask.Flask.response_class" title="flask.Flask.response_class"><tt class="xref py py-attr docutils literal"><span class="pre">response_class</span></tt></a> object and return -a new response object or the same (see <a class="reference internal" href="#flask.Flask.process_response" title="flask.Flask.process_response"><tt class="xref py py-meth docutils literal"><span class="pre">process_response()</span></tt></a>).</p> -<p>As of Flask 0.7 this function might not be executed at the end of the -request in case an unhandled exception ocurred.</p> -</dd></dl> - -<dl class="attribute"> -<dt id="flask.Flask.after_request_funcs"> -<tt class="descname">after_request_funcs</tt><em class="property"> = None</em><a class="headerlink" href="#flask.Flask.after_request_funcs" title="Permalink to this definition">¶</a></dt> -<dd><p>A dictionary with lists of functions that should be called after -each request. The key of the dictionary is the name of the blueprint -this function is active for, <cite>None</cite> for all requests. This can for -example be used to open database connections or getting hold of the -currently logged in user. To register a function here, use the -<a class="reference internal" href="#flask.Flask.after_request" title="flask.Flask.after_request"><tt class="xref py py-meth docutils literal"><span class="pre">after_request()</span></tt></a> decorator.</p> -</dd></dl> - -<dl class="method"> -<dt id="flask.Flask.auto_find_instance_path"> -<tt class="descname">auto_find_instance_path</tt><big>(</big><big>)</big><a class="headerlink" href="#flask.Flask.auto_find_instance_path" title="Permalink to this definition">¶</a></dt> -<dd><p>Tries to locate the instance path if it was not provided to the -constructor of the application class. It will basically calculate -the path to a folder named <tt class="docutils literal"><span class="pre">instance</span></tt> next to your main file or -the package.</p> -<p class="versionadded"> -<span class="versionmodified">New in version 0.8.</span></p> -</dd></dl> - -<dl class="method"> -<dt id="flask.Flask.before_first_request"> -<tt class="descname">before_first_request</tt><big>(</big><em>*args</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#flask.Flask.before_first_request" title="Permalink to this definition">¶</a></dt> -<dd><p>Registers a function to be run before the first request to this -instance of the application.</p> -<p class="versionadded"> -<span class="versionmodified">New in version 0.8.</span></p> -</dd></dl> - -<dl class="attribute"> -<dt id="flask.Flask.before_first_request_funcs"> -<tt class="descname">before_first_request_funcs</tt><em class="property"> = None</em><a class="headerlink" href="#flask.Flask.before_first_request_funcs" title="Permalink to this definition">¶</a></dt> -<dd><p>A lists of functions that should be called at the beginning of the -first request to this instance. To register a function here, use -the <a class="reference internal" href="#flask.Flask.before_first_request" title="flask.Flask.before_first_request"><tt class="xref py py-meth docutils literal"><span class="pre">before_first_request()</span></tt></a> decorator.</p> -<p class="versionadded"> -<span class="versionmodified">New in version 0.8.</span></p> -</dd></dl> - -<dl class="method"> -<dt id="flask.Flask.before_request"> -<tt class="descname">before_request</tt><big>(</big><em>*args</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#flask.Flask.before_request" title="Permalink to this definition">¶</a></dt> -<dd><p>Registers a function to run before each request.</p> -</dd></dl> - -<dl class="attribute"> -<dt id="flask.Flask.before_request_funcs"> -<tt class="descname">before_request_funcs</tt><em class="property"> = None</em><a class="headerlink" href="#flask.Flask.before_request_funcs" title="Permalink to this definition">¶</a></dt> -<dd><p>A dictionary with lists of functions that should be called at the -beginning of the request. The key of the dictionary is the name of -the blueprint this function is active for, <cite>None</cite> for all requests. -This can for example be used to open database connections or -getting hold of the currently logged in user. To register a -function here, use the <a class="reference internal" href="#flask.Flask.before_request" title="flask.Flask.before_request"><tt class="xref py py-meth docutils literal"><span class="pre">before_request()</span></tt></a> decorator.</p> -</dd></dl> - -<dl class="attribute"> -<dt id="flask.Flask.blueprints"> -<tt class="descname">blueprints</tt><em class="property"> = None</em><a class="headerlink" href="#flask.Flask.blueprints" title="Permalink to this definition">¶</a></dt> -<dd><p>all the attached blueprints in a directory by name. Blueprints -can be attached multiple times so this dictionary does not tell -you how often they got attached.</p> -<p class="versionadded"> -<span class="versionmodified">New in version 0.7.</span></p> -</dd></dl> - -<dl class="attribute"> -<dt id="flask.Flask.config"> -<tt class="descname">config</tt><em class="property"> = None</em><a class="headerlink" href="#flask.Flask.config" title="Permalink to this definition">¶</a></dt> -<dd><p>The configuration dictionary as <a class="reference internal" href="#flask.Config" title="flask.Config"><tt class="xref py py-class docutils literal"><span class="pre">Config</span></tt></a>. This behaves -exactly like a regular dictionary but supports additional methods -to load a config from files.</p> -</dd></dl> - -<dl class="method"> -<dt id="flask.Flask.context_processor"> -<tt class="descname">context_processor</tt><big>(</big><em>*args</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#flask.Flask.context_processor" title="Permalink to this definition">¶</a></dt> -<dd><p>Registers a template context processor function.</p> -</dd></dl> - -<dl class="method"> -<dt id="flask.Flask.create_global_jinja_loader"> -<tt class="descname">create_global_jinja_loader</tt><big>(</big><big>)</big><a class="headerlink" href="#flask.Flask.create_global_jinja_loader" title="Permalink to this definition">¶</a></dt> -<dd><p>Creates the loader for the Jinja2 environment. Can be used to -override just the loader and keeping the rest unchanged. It’s -discouraged to override this function. Instead one should override -the <a class="reference internal" href="#flask.Flask.jinja_loader" title="flask.Flask.jinja_loader"><tt class="xref py py-meth docutils literal"><span class="pre">jinja_loader()</span></tt></a> function instead.</p> -<p>The global loader dispatches between the loaders of the application -and the individual blueprints.</p> -<p class="versionadded"> -<span class="versionmodified">New in version 0.7.</span></p> -</dd></dl> - -<dl class="method"> -<dt id="flask.Flask.create_jinja_environment"> -<tt class="descname">create_jinja_environment</tt><big>(</big><big>)</big><a class="headerlink" href="#flask.Flask.create_jinja_environment" title="Permalink to this definition">¶</a></dt> -<dd><p>Creates the Jinja2 environment based on <a class="reference internal" href="#flask.Flask.jinja_options" title="flask.Flask.jinja_options"><tt class="xref py py-attr docutils literal"><span class="pre">jinja_options</span></tt></a> -and <a class="reference internal" href="#flask.Flask.select_jinja_autoescape" title="flask.Flask.select_jinja_autoescape"><tt class="xref py py-meth docutils literal"><span class="pre">select_jinja_autoescape()</span></tt></a>. Since 0.7 this also adds -the Jinja2 globals and filters after initialization. Override -this function to customize the behavior.</p> -<p class="versionadded"> -<span class="versionmodified">New in version 0.5.</span></p> -</dd></dl> - -<dl class="method"> -<dt id="flask.Flask.create_url_adapter"> -<tt class="descname">create_url_adapter</tt><big>(</big><em>request</em><big>)</big><a class="headerlink" href="#flask.Flask.create_url_adapter" title="Permalink to this definition">¶</a></dt> -<dd><p>Creates a URL adapter for the given request. The URL adapter -is created at a point where the request context is not yet set up -so the request is passed explicitly.</p> -<p class="versionadded"> -<span class="versionmodified">New in version 0.6.</span></p> -</dd></dl> - -<dl class="attribute"> -<dt id="flask.Flask.debug"> -<tt class="descname">debug</tt><a class="headerlink" href="#flask.Flask.debug" title="Permalink to this definition">¶</a></dt> -<dd><p>The debug flag. Set this to <cite>True</cite> to enable debugging of the -application. In debug mode the debugger will kick in when an unhandled -exception ocurrs and the integrated server will automatically reload -the application if changes in the code are detected.</p> -<p>This attribute can also be configured from the config with the <cite>DEBUG</cite> -configuration key. Defaults to <cite>False</cite>.</p> -</dd></dl> - -<dl class="attribute"> -<dt id="flask.Flask.debug_log_format"> -<tt class="descname">debug_log_format</tt><em class="property"> = '--------------------------------------------------------------------------------\n%(levelname)s in %(module)s [%(pathname)s:%(lineno)d]:\n%(message)s\n--------------------------------------------------------------------------------'</em><a class="headerlink" href="#flask.Flask.debug_log_format" title="Permalink to this definition">¶</a></dt> -<dd><p>The logging format used for the debug logger. This is only used when -the application is in debug mode, otherwise the attached logging -handler does the formatting.</p> -<p class="versionadded"> -<span class="versionmodified">New in version 0.3.</span></p> -</dd></dl> - -<dl class="attribute"> -<dt id="flask.Flask.default_config"> -<tt class="descname">default_config</tt><em class="property"> = ImmutableDict({'USE_X_SENDFILE': False, 'SESSION_COOKIE_PATH': None, 'SESSION_COOKIE_DOMAIN': None, 'SESSION_COOKIE_NAME': 'session', 'LOGGER_NAME': None, 'DEBUG': False, 'SECRET_KEY': None, 'MAX_CONTENT_LENGTH': None, 'APPLICATION_ROOT': None, 'SERVER_NAME': None, 'TESTING': False, 'PERMANENT_SESSION_LIFETIME': datetime.timedelta(31), 'PROPAGATE_EXCEPTIONS': None, 'TRAP_BAD_REQUEST_ERRORS': False, 'TRAP_HTTP_EXCEPTIONS': False, 'PRESERVE_CONTEXT_ON_EXCEPTION': None, 'SESSION_COOKIE_SECURE': False, 'SESSION_COOKIE_HTTPONLY': True})</em><a class="headerlink" href="#flask.Flask.default_config" title="Permalink to this definition">¶</a></dt> -<dd><p>Default configuration parameters.</p> -</dd></dl> - -<dl class="method"> -<dt id="flask.Flask.dispatch_request"> -<tt class="descname">dispatch_request</tt><big>(</big><big>)</big><a class="headerlink" href="#flask.Flask.dispatch_request" title="Permalink to this definition">¶</a></dt> -<dd><p>Does the request dispatching. Matches the URL and returns the -return value of the view or error handler. This does not have to -be a response object. In order to convert the return value to a -proper response object, call <a class="reference internal" href="#flask.make_response" title="flask.make_response"><tt class="xref py py-func docutils literal"><span class="pre">make_response()</span></tt></a>.</p> -<p class="versionchanged"> -<span class="versionmodified">Changed in version 0.7: </span>This no longer does the exception handling, this code was -moved to the new <a class="reference internal" href="#flask.Flask.full_dispatch_request" title="flask.Flask.full_dispatch_request"><tt class="xref py py-meth docutils literal"><span class="pre">full_dispatch_request()</span></tt></a>.</p> -</dd></dl> - -<dl class="method"> -<dt id="flask.Flask.do_teardown_request"> -<tt class="descname">do_teardown_request</tt><big>(</big><big>)</big><a class="headerlink" href="#flask.Flask.do_teardown_request" title="Permalink to this definition">¶</a></dt> -<dd><p>Called after the actual request dispatching and will -call every as <a class="reference internal" href="#flask.Flask.teardown_request" title="flask.Flask.teardown_request"><tt class="xref py py-meth docutils literal"><span class="pre">teardown_request()</span></tt></a> decorated function. This is -not actually called by the <a class="reference internal" href="#flask.Flask" title="flask.Flask"><tt class="xref py py-class docutils literal"><span class="pre">Flask</span></tt></a> object itself but is always -triggered when the request context is popped. That way we have a -tighter control over certain resources under testing environments.</p> -</dd></dl> - -<dl class="attribute"> -<dt id="flask.Flask.enable_modules"> -<tt class="descname">enable_modules</tt><em class="property"> = True</em><a class="headerlink" href="#flask.Flask.enable_modules" title="Permalink to this definition">¶</a></dt> -<dd><p>Enable the deprecated module support? This is active by default -in 0.7 but will be changed to False in 0.8. With Flask 1.0 modules -will be removed in favor of Blueprints</p> -</dd></dl> - -<dl class="method"> -<dt id="flask.Flask.endpoint"> -<tt class="descname">endpoint</tt><big>(</big><em>*args</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#flask.Flask.endpoint" title="Permalink to this definition">¶</a></dt> -<dd><p>A decorator to register a function as an endpoint. -Example:</p> -<div class="highlight-python"><div class="highlight"><pre><span class="nd">@app.endpoint</span><span class="p">(</span><span class="s">'example.endpoint'</span><span class="p">)</span> -<span class="k">def</span> <span class="nf">example</span><span class="p">():</span> - <span class="k">return</span> <span class="s">"example"</span> -</pre></div> -</div> -<table class="docutils field-list" frame="void" rules="none"> -<col class="field-name" /> -<col class="field-body" /> -<tbody valign="top"> -<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>endpoint</strong> – the name of the endpoint</td> -</tr> -</tbody> -</table> -</dd></dl> - -<dl class="attribute"> -<dt id="flask.Flask.error_handler_spec"> -<tt class="descname">error_handler_spec</tt><em class="property"> = None</em><a class="headerlink" href="#flask.Flask.error_handler_spec" title="Permalink to this definition">¶</a></dt> -<dd><p>A dictionary of all registered error handlers. The key is <cite>None</cite> -for error handlers active on the application, otherwise the key is -the name of the blueprint. Each key points to another dictionary -where they key is the status code of the http exception. The -special key <cite>None</cite> points to a list of tuples where the first item -is the class for the instance check and the second the error handler -function.</p> -<p>To register a error handler, use the <a class="reference internal" href="#flask.Flask.errorhandler" title="flask.Flask.errorhandler"><tt class="xref py py-meth docutils literal"><span class="pre">errorhandler()</span></tt></a> -decorator.</p> -</dd></dl> - -<dl class="method"> -<dt id="flask.Flask.errorhandler"> -<tt class="descname">errorhandler</tt><big>(</big><em>*args</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#flask.Flask.errorhandler" title="Permalink to this definition">¶</a></dt> -<dd><p>A decorator that is used to register a function give a given -error code. Example:</p> -<div class="highlight-python"><div class="highlight"><pre><span class="nd">@app.errorhandler</span><span class="p">(</span><span class="mi">404</span><span class="p">)</span> -<span class="k">def</span> <span class="nf">page_not_found</span><span class="p">(</span><span class="n">error</span><span class="p">):</span> - <span class="k">return</span> <span class="s">'This page does not exist'</span><span class="p">,</span> <span class="mi">404</span> -</pre></div> -</div> -<p>You can also register handlers for arbitrary exceptions:</p> -<div class="highlight-python"><div class="highlight"><pre><span class="nd">@app.errorhandler</span><span class="p">(</span><span class="n">DatabaseError</span><span class="p">)</span> -<span class="k">def</span> <span class="nf">special_exception_handler</span><span class="p">(</span><span class="n">error</span><span class="p">):</span> - <span class="k">return</span> <span class="s">'Database connection failed'</span><span class="p">,</span> <span class="mi">500</span> -</pre></div> -</div> -<p>You can also register a function as error handler without using -the <a class="reference internal" href="#flask.Flask.errorhandler" title="flask.Flask.errorhandler"><tt class="xref py py-meth docutils literal"><span class="pre">errorhandler()</span></tt></a> decorator. The following example is -equivalent to the one above:</p> -<div class="highlight-python"><div class="highlight"><pre><span class="k">def</span> <span class="nf">page_not_found</span><span class="p">(</span><span class="n">error</span><span class="p">):</span> - <span class="k">return</span> <span class="s">'This page does not exist'</span><span class="p">,</span> <span class="mi">404</span> -<span class="n">app</span><span class="o">.</span><span class="n">error_handler_spec</span><span class="p">[</span><span class="bp">None</span><span class="p">][</span><span class="mi">404</span><span class="p">]</span> <span class="o">=</span> <span class="n">page_not_found</span> -</pre></div> -</div> -<p>Setting error handlers via assignments to <a class="reference internal" href="#flask.Flask.error_handler_spec" title="flask.Flask.error_handler_spec"><tt class="xref py py-attr docutils literal"><span class="pre">error_handler_spec</span></tt></a> -however is discouraged as it requires fidling with nested dictionaries -and the special case for arbitrary exception types.</p> -<p>The first <cite>None</cite> refers to the active blueprint. If the error -handler should be application wide <cite>None</cite> shall be used.</p> -<p class="versionadded"> -<span class="versionmodified">New in version 0.7: </span>One can now additionally also register custom exception types -that do not necessarily have to be a subclass of the -<tt class="xref py py-class docutils literal"><span class="pre">HTTPException</span></tt> class.</p> -<table class="docutils field-list" frame="void" rules="none"> -<col class="field-name" /> -<col class="field-body" /> -<tbody valign="top"> -<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>code</strong> – the code as integer for the handler</td> -</tr> -</tbody> -</table> -</dd></dl> - -<dl class="attribute"> -<dt id="flask.Flask.extensions"> -<tt class="descname">extensions</tt><em class="property"> = None</em><a class="headerlink" href="#flask.Flask.extensions" title="Permalink to this definition">¶</a></dt> -<dd><p>a place where extensions can store application specific state. For -example this is where an extension could store database engines and -similar things. For backwards compatibility extensions should register -themselves like this:</p> -<div class="highlight-python"><div class="highlight"><pre><span class="k">if</span> <span class="ow">not</span> <span class="nb">hasattr</span><span class="p">(</span><span class="n">app</span><span class="p">,</span> <span class="s">'extensions'</span><span class="p">):</span> - <span class="n">app</span><span class="o">.</span><span class="n">extensions</span> <span class="o">=</span> <span class="p">{}</span> -<span class="n">app</span><span class="o">.</span><span class="n">extensions</span><span class="p">[</span><span class="s">'extensionname'</span><span class="p">]</span> <span class="o">=</span> <span class="n">SomeObject</span><span class="p">()</span> -</pre></div> -</div> -<p>The key must match the name of the <cite>flaskext</cite> module. For example in -case of a “Flask-Foo” extension in <cite>flaskext.foo</cite>, the key would be -<tt class="docutils literal"><span class="pre">'foo'</span></tt>.</p> -<p class="versionadded"> -<span class="versionmodified">New in version 0.7.</span></p> -</dd></dl> - -<dl class="method"> -<dt id="flask.Flask.full_dispatch_request"> -<tt class="descname">full_dispatch_request</tt><big>(</big><big>)</big><a class="headerlink" href="#flask.Flask.full_dispatch_request" title="Permalink to this definition">¶</a></dt> -<dd><p>Dispatches the request and on top of that performs request -pre and postprocessing as well as HTTP exception catching and -error handling.</p> -<p class="versionadded"> -<span class="versionmodified">New in version 0.7.</span></p> -</dd></dl> - -<dl class="attribute"> -<dt id="flask.Flask.got_first_request"> -<tt class="descname">got_first_request</tt><a class="headerlink" href="#flask.Flask.got_first_request" title="Permalink to this definition">¶</a></dt> -<dd><p>This attribute is set to <cite>True</cite> if the application started -handling the first request.</p> -<p class="versionadded"> -<span class="versionmodified">New in version 0.8.</span></p> -</dd></dl> - -<dl class="method"> -<dt id="flask.Flask.handle_exception"> -<tt class="descname">handle_exception</tt><big>(</big><em>e</em><big>)</big><a class="headerlink" href="#flask.Flask.handle_exception" title="Permalink to this definition">¶</a></dt> -<dd><p>Default exception handling that kicks in when an exception -occours that is not caught. In debug mode the exception will -be re-raised immediately, otherwise it is logged and the handler -for a 500 internal server error is used. If no such handler -exists, a default 500 internal server error message is displayed.</p> -</dd></dl> - -<dl class="method"> -<dt id="flask.Flask.handle_http_exception"> -<tt class="descname">handle_http_exception</tt><big>(</big><em>e</em><big>)</big><a class="headerlink" href="#flask.Flask.handle_http_exception" title="Permalink to this definition">¶</a></dt> -<dd><p>Handles an HTTP exception. By default this will invoke the -registered error handlers and fall back to returning the -exception as response.</p> -</dd></dl> - -<dl class="method"> -<dt id="flask.Flask.handle_user_exception"> -<tt class="descname">handle_user_exception</tt><big>(</big><em>e</em><big>)</big><a class="headerlink" href="#flask.Flask.handle_user_exception" title="Permalink to this definition">¶</a></dt> -<dd><p>This method is called whenever an exception occurs that should be -handled. A special case are -<tt class="xref py py-class docutils literal"><span class="pre">HTTPException</span></tt>s which are forwarded by -this function to the <a class="reference internal" href="#flask.Flask.handle_http_exception" title="flask.Flask.handle_http_exception"><tt class="xref py py-meth docutils literal"><span class="pre">handle_http_exception()</span></tt></a> method. This -function will either return a response value or reraise the -exception with the same traceback.</p> -<p class="versionadded"> -<span class="versionmodified">New in version 0.7.</span></p> -</dd></dl> - -<dl class="attribute"> -<dt id="flask.Flask.has_static_folder"> -<tt class="descname">has_static_folder</tt><a class="headerlink" href="#flask.Flask.has_static_folder" title="Permalink to this definition">¶</a></dt> -<dd><p>This is <cite>True</cite> if the package bound object’s container has a -folder named <tt class="docutils literal"><span class="pre">'static'</span></tt>.</p> -<p class="versionadded"> -<span class="versionmodified">New in version 0.5.</span></p> -</dd></dl> - -<dl class="method"> -<dt id="flask.Flask.init_jinja_globals"> -<tt class="descname">init_jinja_globals</tt><big>(</big><big>)</big><a class="headerlink" href="#flask.Flask.init_jinja_globals" title="Permalink to this definition">¶</a></dt> -<dd><p>Deprecated. Used to initialize the Jinja2 globals.</p> -<p class="versionadded"> -<span class="versionmodified">New in version 0.5.</span></p> -<p class="versionchanged"> -<span class="versionmodified">Changed in version 0.7: </span>This method is deprecated with 0.7. Override -<a class="reference internal" href="#flask.Flask.create_jinja_environment" title="flask.Flask.create_jinja_environment"><tt class="xref py py-meth docutils literal"><span class="pre">create_jinja_environment()</span></tt></a> instead.</p> -</dd></dl> - -<dl class="method"> -<dt id="flask.Flask.inject_url_defaults"> -<tt class="descname">inject_url_defaults</tt><big>(</big><em>endpoint</em>, <em>values</em><big>)</big><a class="headerlink" href="#flask.Flask.inject_url_defaults" title="Permalink to this definition">¶</a></dt> -<dd><p>Injects the URL defaults for the given endpoint directly into -the values dictionary passed. This is used internally and -automatically called on URL building.</p> -<p class="versionadded"> -<span class="versionmodified">New in version 0.7.</span></p> -</dd></dl> - -<dl class="attribute"> -<dt id="flask.Flask.instance_path"> -<tt class="descname">instance_path</tt><em class="property"> = None</em><a class="headerlink" href="#flask.Flask.instance_path" title="Permalink to this definition">¶</a></dt> -<dd><p>Holds the path to the instance folder.</p> -<p class="versionadded"> -<span class="versionmodified">New in version 0.8.</span></p> -</dd></dl> - -<dl class="attribute"> -<dt id="flask.Flask.jinja_env"> -<tt class="descname">jinja_env</tt><a class="headerlink" href="#flask.Flask.jinja_env" title="Permalink to this definition">¶</a></dt> -<dd><p>The Jinja2 environment used to load templates.</p> -</dd></dl> - -<dl class="attribute"> -<dt id="flask.Flask.jinja_loader"> -<tt class="descname">jinja_loader</tt><a class="headerlink" href="#flask.Flask.jinja_loader" title="Permalink to this definition">¶</a></dt> -<dd><p>The Jinja loader for this package bound object.</p> -<p class="versionadded"> -<span class="versionmodified">New in version 0.5.</span></p> -</dd></dl> - -<dl class="attribute"> -<dt id="flask.Flask.jinja_options"> -<tt class="descname">jinja_options</tt><em class="property"> = ImmutableDict({'extensions': ['jinja2.ext.autoescape', 'jinja2.ext.with_']})</em><a class="headerlink" href="#flask.Flask.jinja_options" title="Permalink to this definition">¶</a></dt> -<dd><p>Options that are passed directly to the Jinja2 environment.</p> -</dd></dl> - -<dl class="method"> -<dt id="flask.Flask.log_exception"> -<tt class="descname">log_exception</tt><big>(</big><em>exc_info</em><big>)</big><a class="headerlink" href="#flask.Flask.log_exception" title="Permalink to this definition">¶</a></dt> -<dd><p>Logs an exception. This is called by <a class="reference internal" href="#flask.Flask.handle_exception" title="flask.Flask.handle_exception"><tt class="xref py py-meth docutils literal"><span class="pre">handle_exception()</span></tt></a> -if debugging is disabled and right before the handler is called. -The default implementation logs the exception as error on the -<a class="reference internal" href="#flask.Flask.logger" title="flask.Flask.logger"><tt class="xref py py-attr docutils literal"><span class="pre">logger</span></tt></a>.</p> -<p class="versionadded"> -<span class="versionmodified">New in version 0.8.</span></p> -</dd></dl> - -<dl class="attribute"> -<dt id="flask.Flask.logger"> -<tt class="descname">logger</tt><a class="headerlink" href="#flask.Flask.logger" title="Permalink to this definition">¶</a></dt> -<dd><p>A <a class="reference external" href="http://docs.python.org/dev/library/logging.html#logging.Logger" title="(in Python v3.3)"><tt class="xref py py-class docutils literal"><span class="pre">logging.Logger</span></tt></a> object for this application. The -default configuration is to log to stderr if the application is -in debug mode. This logger can be used to (surprise) log messages. -Here some examples:</p> -<div class="highlight-python"><div class="highlight"><pre><span class="n">app</span><span class="o">.</span><span class="n">logger</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="s">'A value for debugging'</span><span class="p">)</span> -<span class="n">app</span><span class="o">.</span><span class="n">logger</span><span class="o">.</span><span class="n">warning</span><span class="p">(</span><span class="s">'A warning ocurred (</span><span class="si">%d</span><span class="s"> apples)'</span><span class="p">,</span> <span class="mi">42</span><span class="p">)</span> -<span class="n">app</span><span class="o">.</span><span class="n">logger</span><span class="o">.</span><span class="n">error</span><span class="p">(</span><span class="s">'An error occoured'</span><span class="p">)</span> -</pre></div> -</div> -<p class="versionadded"> -<span class="versionmodified">New in version 0.3.</span></p> -</dd></dl> - -<dl class="attribute"> -<dt id="flask.Flask.logger_name"> -<tt class="descname">logger_name</tt><a class="headerlink" href="#flask.Flask.logger_name" title="Permalink to this definition">¶</a></dt> -<dd><p>The name of the logger to use. By default the logger name is the -package name passed to the constructor.</p> -<p class="versionadded"> -<span class="versionmodified">New in version 0.4.</span></p> -</dd></dl> - -<dl class="method"> -<dt id="flask.Flask.make_config"> -<tt class="descname">make_config</tt><big>(</big><em>instance_relative=False</em><big>)</big><a class="headerlink" href="#flask.Flask.make_config" title="Permalink to this definition">¶</a></dt> -<dd><p>Used to create the config attribute by the Flask constructor. -The <cite>instance_relative</cite> parameter is passed in from the constructor -of Flask (there named <cite>instance_relative_config</cite>) and indicates if -the config should be relative to the instance path or the root path -of the application.</p> -<p class="versionadded"> -<span class="versionmodified">New in version 0.8.</span></p> -</dd></dl> - -<dl class="method"> -<dt id="flask.Flask.make_default_options_response"> -<tt class="descname">make_default_options_response</tt><big>(</big><big>)</big><a class="headerlink" href="#flask.Flask.make_default_options_response" title="Permalink to this definition">¶</a></dt> -<dd><p>This method is called to create the default <cite>OPTIONS</cite> response. -This can be changed through subclassing to change the default -behaviour of <cite>OPTIONS</cite> responses.</p> -<p class="versionadded"> -<span class="versionmodified">New in version 0.7.</span></p> -</dd></dl> - -<dl class="method"> -<dt id="flask.Flask.make_null_session"> -<tt class="descname">make_null_session</tt><big>(</big><big>)</big><a class="headerlink" href="#flask.Flask.make_null_session" title="Permalink to this definition">¶</a></dt> -<dd><p>Creates a new instance of a missing session. Instead of overriding -this method we recommend replacing the <a class="reference internal" href="#flask.Flask.session_interface" title="flask.Flask.session_interface"><tt class="xref py py-class docutils literal"><span class="pre">session_interface</span></tt></a>.</p> -<p class="versionadded"> -<span class="versionmodified">New in version 0.7.</span></p> -</dd></dl> - -<dl class="method"> -<dt id="flask.Flask.make_response"> -<tt class="descname">make_response</tt><big>(</big><em>rv</em><big>)</big><a class="headerlink" href="#flask.Flask.make_response" title="Permalink to this definition">¶</a></dt> -<dd><p>Converts the return value from a view function to a real -response object that is an instance of <a class="reference internal" href="#flask.Flask.response_class" title="flask.Flask.response_class"><tt class="xref py py-attr docutils literal"><span class="pre">response_class</span></tt></a>.</p> -<p>The following types are allowed for <cite>rv</cite>:</p> -<table border="1" class="docutils"> -<colgroup> -<col width="35%" /> -<col width="65%" /> -</colgroup> -<tbody valign="top"> -<tr class="row-odd"><td><a class="reference internal" href="#flask.Flask.response_class" title="flask.Flask.response_class"><tt class="xref py py-attr docutils literal"><span class="pre">response_class</span></tt></a></td> -<td>the object is returned unchanged</td> -</tr> -<tr class="row-even"><td><tt class="xref py py-class docutils literal"><span class="pre">str</span></tt></td> -<td>a response object is created with the -string as body</td> -</tr> -<tr class="row-odd"><td><tt class="xref py py-class docutils literal"><span class="pre">unicode</span></tt></td> -<td>a response object is created with the -string encoded to utf-8 as body</td> -</tr> -<tr class="row-even"><td><tt class="xref py py-class docutils literal"><span class="pre">tuple</span></tt></td> -<td>the response object is created with the -contents of the tuple as arguments</td> -</tr> -<tr class="row-odd"><td>a WSGI function</td> -<td>the function is called as WSGI application -and buffered as response object</td> -</tr> -</tbody> -</table> -<table class="docutils field-list" frame="void" rules="none"> -<col class="field-name" /> -<col class="field-body" /> -<tbody valign="top"> -<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>rv</strong> – the return value from the view function</td> -</tr> -</tbody> -</table> -</dd></dl> - -<dl class="attribute"> -<dt id="flask.Flask.name"> -<tt class="descname">name</tt><a class="headerlink" href="#flask.Flask.name" title="Permalink to this definition">¶</a></dt> -<dd><p>The name of the application. This is usually the import name -with the difference that it’s guessed from the run file if the -import name is main. This name is used as a display name when -Flask needs the name of the application. It can be set and overriden -to change the value.</p> -<p class="versionadded"> -<span class="versionmodified">New in version 0.8.</span></p> -</dd></dl> - -<dl class="method"> -<dt id="flask.Flask.open_instance_resource"> -<tt class="descname">open_instance_resource</tt><big>(</big><em>resource</em>, <em>mode='rb'</em><big>)</big><a class="headerlink" href="#flask.Flask.open_instance_resource" title="Permalink to this definition">¶</a></dt> -<dd><p>Opens a resource from the application’s instance folder -(<a class="reference internal" href="#flask.Flask.instance_path" title="flask.Flask.instance_path"><tt class="xref py py-attr docutils literal"><span class="pre">instance_path</span></tt></a>). Otherwise works like -<a class="reference internal" href="#flask.Flask.open_resource" title="flask.Flask.open_resource"><tt class="xref py py-meth docutils literal"><span class="pre">open_resource()</span></tt></a>. Instance resources can also be opened for -writing.</p> -<table class="docutils field-list" frame="void" rules="none"> -<col class="field-name" /> -<col class="field-body" /> -<tbody valign="top"> -<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>resource</strong> – the name of the resource. To access resources within -subfolders use forward slashes as separator.</td> -</tr> -</tbody> -</table> -</dd></dl> - -<dl class="method"> -<dt id="flask.Flask.open_resource"> -<tt class="descname">open_resource</tt><big>(</big><em>resource</em>, <em>mode='rb'</em><big>)</big><a class="headerlink" href="#flask.Flask.open_resource" title="Permalink to this definition">¶</a></dt> -<dd><p>Opens a resource from the application’s resource folder. To see -how this works, consider the following folder structure:</p> -<div class="highlight-python"><pre>/myapplication.py -/schema.sql -/static - /style.css -/templates - /layout.html - /index.html</pre> -</div> -<p>If you want to open the <cite>schema.sql</cite> file you would do the -following:</p> -<div class="highlight-python"><div class="highlight"><pre><span class="k">with</span> <span class="n">app</span><span class="o">.</span><span class="n">open_resource</span><span class="p">(</span><span class="s">'schema.sql'</span><span class="p">)</span> <span class="k">as</span> <span class="n">f</span><span class="p">:</span> - <span class="n">contents</span> <span class="o">=</span> <span class="n">f</span><span class="o">.</span><span class="n">read</span><span class="p">()</span> - <span class="n">do_something_with</span><span class="p">(</span><span class="n">contents</span><span class="p">)</span> -</pre></div> -</div> -<table class="docutils field-list" frame="void" rules="none"> -<col class="field-name" /> -<col class="field-body" /> -<tbody valign="top"> -<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>resource</strong> – the name of the resource. To access resources within -subfolders use forward slashes as separator.</td> -</tr> -</tbody> -</table> -</dd></dl> - -<dl class="method"> -<dt id="flask.Flask.open_session"> -<tt class="descname">open_session</tt><big>(</big><em>request</em><big>)</big><a class="headerlink" href="#flask.Flask.open_session" title="Permalink to this definition">¶</a></dt> -<dd><p>Creates or opens a new session. Default implementation stores all -session data in a signed cookie. This requires that the -<a class="reference internal" href="#flask.Flask.secret_key" title="flask.Flask.secret_key"><tt class="xref py py-attr docutils literal"><span class="pre">secret_key</span></tt></a> is set. Instead of overriding this method -we recommend replacing the <a class="reference internal" href="#flask.Flask.session_interface" title="flask.Flask.session_interface"><tt class="xref py py-class docutils literal"><span class="pre">session_interface</span></tt></a>.</p> -<table class="docutils field-list" frame="void" rules="none"> -<col class="field-name" /> -<col class="field-body" /> -<tbody valign="top"> -<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>request</strong> – an instance of <a class="reference internal" href="#flask.Flask.request_class" title="flask.Flask.request_class"><tt class="xref py py-attr docutils literal"><span class="pre">request_class</span></tt></a>.</td> -</tr> -</tbody> -</table> -</dd></dl> - -<dl class="attribute"> -<dt id="flask.Flask.permanent_session_lifetime"> -<tt class="descname">permanent_session_lifetime</tt><a class="headerlink" href="#flask.Flask.permanent_session_lifetime" title="Permalink to this definition">¶</a></dt> -<dd><p>A <a class="reference external" href="http://docs.python.org/dev/library/datetime.html#datetime.timedelta" title="(in Python v3.3)"><tt class="xref py py-class docutils literal"><span class="pre">timedelta</span></tt></a> which is used to set the expiration -date of a permanent session. The default is 31 days which makes a -permanent session survive for roughly one month.</p> -<p>This attribute can also be configured from the config with the -<cite>PERMANENT_SESSION_LIFETIME</cite> configuration key. Defaults to -<tt class="docutils literal"><span class="pre">timedelta(days=31)</span></tt></p> -</dd></dl> - -<dl class="method"> -<dt id="flask.Flask.preprocess_request"> -<tt class="descname">preprocess_request</tt><big>(</big><big>)</big><a class="headerlink" href="#flask.Flask.preprocess_request" title="Permalink to this definition">¶</a></dt> -<dd><p>Called before the actual request dispatching and will -call every as <a class="reference internal" href="#flask.Flask.before_request" title="flask.Flask.before_request"><tt class="xref py py-meth docutils literal"><span class="pre">before_request()</span></tt></a> decorated function. -If any of these function returns a value it’s handled as -if it was the return value from the view and further -request handling is stopped.</p> -<p>This also triggers the <tt class="xref py py-meth docutils literal"><span class="pre">url_value_processor()</span></tt> functions before -the actualy <a class="reference internal" href="#flask.Flask.before_request" title="flask.Flask.before_request"><tt class="xref py py-meth docutils literal"><span class="pre">before_request()</span></tt></a> functions are called.</p> -</dd></dl> - -<dl class="attribute"> -<dt id="flask.Flask.preserve_context_on_exception"> -<tt class="descname">preserve_context_on_exception</tt><a class="headerlink" href="#flask.Flask.preserve_context_on_exception" title="Permalink to this definition">¶</a></dt> -<dd><p>Returns the value of the <cite>PRESERVE_CONTEXT_ON_EXCEPTION</cite> -configuration value in case it’s set, otherwise a sensible default -is returned.</p> -<p class="versionadded"> -<span class="versionmodified">New in version 0.7.</span></p> -</dd></dl> - -<dl class="method"> -<dt id="flask.Flask.process_response"> -<tt class="descname">process_response</tt><big>(</big><em>response</em><big>)</big><a class="headerlink" href="#flask.Flask.process_response" title="Permalink to this definition">¶</a></dt> -<dd><p>Can be overridden in order to modify the response object -before it’s sent to the WSGI server. By default this will -call all the <a class="reference internal" href="#flask.Flask.after_request" title="flask.Flask.after_request"><tt class="xref py py-meth docutils literal"><span class="pre">after_request()</span></tt></a> decorated functions.</p> -<p class="versionchanged"> -<span class="versionmodified">Changed in version 0.5: </span>As of Flask 0.5 the functions registered for after request -execution are called in reverse order of registration.</p> -<table class="docutils field-list" frame="void" rules="none"> -<col class="field-name" /> -<col class="field-body" /> -<tbody valign="top"> -<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>response</strong> – a <a class="reference internal" href="#flask.Flask.response_class" title="flask.Flask.response_class"><tt class="xref py py-attr docutils literal"><span class="pre">response_class</span></tt></a> object.</td> -</tr> -<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body">a new response object or the same, has to be an -instance of <a class="reference internal" href="#flask.Flask.response_class" title="flask.Flask.response_class"><tt class="xref py py-attr docutils literal"><span class="pre">response_class</span></tt></a>.</td> -</tr> -</tbody> -</table> -</dd></dl> - -<dl class="attribute"> -<dt id="flask.Flask.propagate_exceptions"> -<tt class="descname">propagate_exceptions</tt><a class="headerlink" href="#flask.Flask.propagate_exceptions" title="Permalink to this definition">¶</a></dt> -<dd><p>Returns the value of the <cite>PROPAGATE_EXCEPTIONS</cite> configuration -value in case it’s set, otherwise a sensible default is returned.</p> -<p class="versionadded"> -<span class="versionmodified">New in version 0.7.</span></p> -</dd></dl> - -<dl class="method"> -<dt id="flask.Flask.register_blueprint"> -<tt class="descname">register_blueprint</tt><big>(</big><em>*args</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#flask.Flask.register_blueprint" title="Permalink to this definition">¶</a></dt> -<dd><p>Registers a blueprint on the application.</p> -<p class="versionadded"> -<span class="versionmodified">New in version 0.7.</span></p> -</dd></dl> - -<dl class="method"> -<dt id="flask.Flask.register_error_handler"> -<tt class="descname">register_error_handler</tt><big>(</big><em>code_or_exception</em>, <em>f</em><big>)</big><a class="headerlink" href="#flask.Flask.register_error_handler" title="Permalink to this definition">¶</a></dt> -<dd><p>Alternative error attach function to the <a class="reference internal" href="#flask.Flask.errorhandler" title="flask.Flask.errorhandler"><tt class="xref py py-meth docutils literal"><span class="pre">errorhandler()</span></tt></a> -decorator that is more straightforward to use for non decorator -usage.</p> -<p class="versionadded"> -<span class="versionmodified">New in version 0.7.</span></p> -</dd></dl> - -<dl class="method"> -<dt id="flask.Flask.register_module"> -<tt class="descname">register_module</tt><big>(</big><em>module</em>, <em>**options</em><big>)</big><a class="headerlink" href="#flask.Flask.register_module" title="Permalink to this definition">¶</a></dt> -<dd><p>Registers a module with this application. The keyword argument -of this function are the same as the ones for the constructor of the -<tt class="xref py py-class docutils literal"><span class="pre">Module</span></tt> class and will override the values of the module if -provided.</p> -<p class="versionchanged"> -<span class="versionmodified">Changed in version 0.7: </span>The module system was deprecated in favor for the blueprint -system.</p> -</dd></dl> - -<dl class="attribute"> -<dt id="flask.Flask.request_class"> -<tt class="descname">request_class</tt><a class="headerlink" href="#flask.Flask.request_class" title="Permalink to this definition">¶</a></dt> -<dd><p>The class that is used for request objects. See <a class="reference internal" href="#flask.Request" title="flask.Request"><tt class="xref py py-class docutils literal"><span class="pre">Request</span></tt></a> -for more information.</p> -<p>alias of <a class="reference internal" href="#flask.Request" title="flask.Request"><tt class="xref py py-class docutils literal"><span class="pre">Request</span></tt></a></p> -</dd></dl> - -<dl class="method"> -<dt id="flask.Flask.request_context"> -<tt class="descname">request_context</tt><big>(</big><em>environ</em><big>)</big><a class="headerlink" href="#flask.Flask.request_context" title="Permalink to this definition">¶</a></dt> -<dd><p>Creates a <a class="reference internal" href="#flask.ctx.RequestContext" title="flask.ctx.RequestContext"><tt class="xref py py-class docutils literal"><span class="pre">RequestContext</span></tt></a> from the given -environment and binds it to the current context. This must be used in -combination with the <cite>with</cite> statement because the request is only bound -to the current context for the duration of the <cite>with</cite> block.</p> -<p>Example usage:</p> -<div class="highlight-python"><div class="highlight"><pre><span class="k">with</span> <span class="n">app</span><span class="o">.</span><span class="n">request_context</span><span class="p">(</span><span class="n">environ</span><span class="p">):</span> - <span class="n">do_something_with</span><span class="p">(</span><span class="n">request</span><span class="p">)</span> -</pre></div> -</div> -<p>The object returned can also be used without the <cite>with</cite> statement -which is useful for working in the shell. The example above is -doing exactly the same as this code:</p> -<div class="highlight-python"><div class="highlight"><pre><span class="n">ctx</span> <span class="o">=</span> <span class="n">app</span><span class="o">.</span><span class="n">request_context</span><span class="p">(</span><span class="n">environ</span><span class="p">)</span> -<span class="n">ctx</span><span class="o">.</span><span class="n">push</span><span class="p">()</span> -<span class="k">try</span><span class="p">:</span> - <span class="n">do_something_with</span><span class="p">(</span><span class="n">request</span><span class="p">)</span> -<span class="k">finally</span><span class="p">:</span> - <span class="n">ctx</span><span class="o">.</span><span class="n">pop</span><span class="p">()</span> -</pre></div> -</div> -<p class="versionchanged"> -<span class="versionmodified">Changed in version 0.3: </span>Added support for non-with statement usage and <cite>with</cite> statement -is now passed the ctx object.</p> -<table class="docutils field-list" frame="void" rules="none"> -<col class="field-name" /> -<col class="field-body" /> -<tbody valign="top"> -<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>environ</strong> – a WSGI environment</td> -</tr> -</tbody> -</table> -</dd></dl> - -<dl class="attribute"> -<dt id="flask.Flask.response_class"> -<tt class="descname">response_class</tt><a class="headerlink" href="#flask.Flask.response_class" title="Permalink to this definition">¶</a></dt> -<dd><p>The class that is used for response objects. See -<a class="reference internal" href="#flask.Response" title="flask.Response"><tt class="xref py py-class docutils literal"><span class="pre">Response</span></tt></a> for more information.</p> -<p>alias of <a class="reference internal" href="#flask.Response" title="flask.Response"><tt class="xref py py-class docutils literal"><span class="pre">Response</span></tt></a></p> -</dd></dl> - -<dl class="method"> -<dt id="flask.Flask.route"> -<tt class="descname">route</tt><big>(</big><em>rule</em>, <em>**options</em><big>)</big><a class="headerlink" href="#flask.Flask.route" title="Permalink to this definition">¶</a></dt> -<dd><p>A decorator that is used to register a view function for a -given URL rule. This does the same thing as <a class="reference internal" href="#flask.Flask.add_url_rule" title="flask.Flask.add_url_rule"><tt class="xref py py-meth docutils literal"><span class="pre">add_url_rule()</span></tt></a> -but is intended for decorator usage:</p> -<div class="highlight-python"><div class="highlight"><pre><span class="nd">@app.route</span><span class="p">(</span><span class="s">'/'</span><span class="p">)</span> -<span class="k">def</span> <span class="nf">index</span><span class="p">():</span> - <span class="k">return</span> <span class="s">'Hello World'</span> -</pre></div> -</div> -<p>For more information refer to <a class="reference internal" href="#url-route-registrations"><em>URL Route Registrations</em></a>.</p> -<table class="docutils field-list" frame="void" rules="none"> -<col class="field-name" /> -<col class="field-body" /> -<tbody valign="top"> -<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple"> -<li><strong>rule</strong> – the URL rule as string</li> -<li><strong>endpoint</strong> – the endpoint for the registered URL rule. Flask -itself assumes the name of the view function as -endpoint</li> -<li><strong>view_func</strong> – the function to call when serving a request to the -provided endpoint</li> -<li><strong>options</strong> – the options to be forwarded to the underlying -<a class="reference external" href="http://werkzeug.pocoo.org/docs/routing/#werkzeug.routing.Rule" title="(in Werkzeug v0.7)"><tt class="xref py py-class docutils literal"><span class="pre">Rule</span></tt></a> object. A change -to Werkzeug is handling of method options. methods -is a list of methods this rule should be limited -to (<cite>GET</cite>, <cite>POST</cite> etc.). By default a rule -just listens for <cite>GET</cite> (and implicitly <cite>HEAD</cite>). -Starting with Flask 0.6, <cite>OPTIONS</cite> is implicitly -added and handled by the standard request handling.</li> -</ul> -</td> -</tr> -</tbody> -</table> -</dd></dl> - -<dl class="method"> -<dt id="flask.Flask.run"> -<tt class="descname">run</tt><big>(</big><em>host='127.0.0.1'</em>, <em>port=5000</em>, <em>debug=None</em>, <em>**options</em><big>)</big><a class="headerlink" href="#flask.Flask.run" title="Permalink to this definition">¶</a></dt> -<dd><p>Runs the application on a local development server. If the -<a class="reference internal" href="#flask.Flask.debug" title="flask.Flask.debug"><tt class="xref py py-attr docutils literal"><span class="pre">debug</span></tt></a> flag is set the server will automatically reload -for code changes and show a debugger in case an exception happened.</p> -<p>If you want to run the application in debug mode, but disable the -code execution on the interactive debugger, you can pass -<tt class="docutils literal"><span class="pre">use_evalex=False</span></tt> as parameter. This will keep the debugger’s -traceback screen active, but disable code execution.</p> -<div class="admonition-keep-in-mind admonition "> -<p class="first admonition-title">Keep in Mind</p> -<p class="last">Flask will suppress any server error with a generic error page -unless it is in debug mode. As such to enable just the -interactive debugger without the code reloading, you have to -invoke <a class="reference internal" href="#flask.Flask.run" title="flask.Flask.run"><tt class="xref py py-meth docutils literal"><span class="pre">run()</span></tt></a> with <tt class="docutils literal"><span class="pre">debug=True</span></tt> and <tt class="docutils literal"><span class="pre">use_reloader=False</span></tt>. -Setting <tt class="docutils literal"><span class="pre">use_debugger</span></tt> to <cite>True</cite> without being in debug mode -won’t catch any exceptions because there won’t be any to -catch.</p> -</div> -<table class="docutils field-list" frame="void" rules="none"> -<col class="field-name" /> -<col class="field-body" /> -<tbody valign="top"> -<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple"> -<li><strong>host</strong> – the hostname to listen on. set this to <tt class="docutils literal"><span class="pre">'0.0.0.0'</span></tt> -to have the server available externally as well.</li> -<li><strong>port</strong> – the port of the webserver</li> -<li><strong>debug</strong> – if given, enable or disable debug mode. -See <a class="reference internal" href="#flask.Flask.debug" title="flask.Flask.debug"><tt class="xref py py-attr docutils literal"><span class="pre">debug</span></tt></a>.</li> -<li><strong>options</strong> – the options to be forwarded to the underlying -Werkzeug server. See -<a class="reference external" href="http://werkzeug.pocoo.org/docs/serving/#werkzeug.serving.run_simple" title="(in Werkzeug v0.7)"><tt class="xref py py-func docutils literal"><span class="pre">werkzeug.serving.run_simple()</span></tt></a> for more -information.</li> -</ul> -</td> -</tr> -</tbody> -</table> -</dd></dl> - -<dl class="method"> -<dt id="flask.Flask.save_session"> -<tt class="descname">save_session</tt><big>(</big><em>session</em>, <em>response</em><big>)</big><a class="headerlink" href="#flask.Flask.save_session" title="Permalink to this definition">¶</a></dt> -<dd><p>Saves the session if it needs updates. For the default -implementation, check <a class="reference internal" href="#flask.Flask.open_session" title="flask.Flask.open_session"><tt class="xref py py-meth docutils literal"><span class="pre">open_session()</span></tt></a>. Instead of overriding this -method we recommend replacing the <a class="reference internal" href="#flask.Flask.session_interface" title="flask.Flask.session_interface"><tt class="xref py py-class docutils literal"><span class="pre">session_interface</span></tt></a>.</p> -<table class="docutils field-list" frame="void" rules="none"> -<col class="field-name" /> -<col class="field-body" /> -<tbody valign="top"> -<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple"> -<li><strong>session</strong> – the session to be saved (a -<a class="reference external" href="http://werkzeug.pocoo.org/docs/contrib/securecookie/#werkzeug.contrib.securecookie.SecureCookie" title="(in Werkzeug v0.7)"><tt class="xref py py-class docutils literal"><span class="pre">SecureCookie</span></tt></a> -object)</li> -<li><strong>response</strong> – an instance of <a class="reference internal" href="#flask.Flask.response_class" title="flask.Flask.response_class"><tt class="xref py py-attr docutils literal"><span class="pre">response_class</span></tt></a></li> -</ul> -</td> -</tr> -</tbody> -</table> -</dd></dl> - -<dl class="attribute"> -<dt id="flask.Flask.secret_key"> -<tt class="descname">secret_key</tt><a class="headerlink" href="#flask.Flask.secret_key" title="Permalink to this definition">¶</a></dt> -<dd><p>If a secret key is set, cryptographic components can use this to -sign cookies and other things. Set this to a complex random value -when you want to use the secure cookie for instance.</p> -<p>This attribute can also be configured from the config with the -<cite>SECRET_KEY</cite> configuration key. Defaults to <cite>None</cite>.</p> -</dd></dl> - -<dl class="method"> -<dt id="flask.Flask.select_jinja_autoescape"> -<tt class="descname">select_jinja_autoescape</tt><big>(</big><em>filename</em><big>)</big><a class="headerlink" href="#flask.Flask.select_jinja_autoescape" title="Permalink to this definition">¶</a></dt> -<dd><p>Returns <cite>True</cite> if autoescaping should be active for the given -template name.</p> -<p class="versionadded"> -<span class="versionmodified">New in version 0.5.</span></p> -</dd></dl> - -<dl class="method"> -<dt id="flask.Flask.send_static_file"> -<tt class="descname">send_static_file</tt><big>(</big><em>filename</em><big>)</big><a class="headerlink" href="#flask.Flask.send_static_file" title="Permalink to this definition">¶</a></dt> -<dd><p>Function used internally to send static files from the static -folder to the browser.</p> -<p class="versionadded"> -<span class="versionmodified">New in version 0.5.</span></p> -</dd></dl> - -<dl class="attribute"> -<dt id="flask.Flask.session_cookie_name"> -<tt class="descname">session_cookie_name</tt><a class="headerlink" href="#flask.Flask.session_cookie_name" title="Permalink to this definition">¶</a></dt> -<dd><p>The secure cookie uses this for the name of the session cookie.</p> -<p>This attribute can also be configured from the config with the -<cite>SESSION_COOKIE_NAME</cite> configuration key. Defaults to <tt class="docutils literal"><span class="pre">'session'</span></tt></p> -</dd></dl> - -<dl class="attribute"> -<dt id="flask.Flask.session_interface"> -<tt class="descname">session_interface</tt><em class="property"> = <flask.sessions.SecureCookieSessionInterface object at 0x103dc8090></em><a class="headerlink" href="#flask.Flask.session_interface" title="Permalink to this definition">¶</a></dt> -<dd><p>the session interface to use. By default an instance of -<a class="reference internal" href="#flask.sessions.SecureCookieSessionInterface" title="flask.sessions.SecureCookieSessionInterface"><tt class="xref py py-class docutils literal"><span class="pre">SecureCookieSessionInterface</span></tt></a> is used here.</p> -<p class="versionadded"> -<span class="versionmodified">New in version 0.8.</span></p> -</dd></dl> - -<dl class="method"> -<dt id="flask.Flask.teardown_request"> -<tt class="descname">teardown_request</tt><big>(</big><em>*args</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#flask.Flask.teardown_request" title="Permalink to this definition">¶</a></dt> -<dd><p>Register a function to be run at the end of each request, -regardless of whether there was an exception or not. These functions -are executed when the request context is popped, even if not an -actual request was performed.</p> -<p>Example:</p> -<div class="highlight-python"><div class="highlight"><pre><span class="n">ctx</span> <span class="o">=</span> <span class="n">app</span><span class="o">.</span><span class="n">test_request_context</span><span class="p">()</span> -<span class="n">ctx</span><span class="o">.</span><span class="n">push</span><span class="p">()</span> -<span class="o">...</span> -<span class="n">ctx</span><span class="o">.</span><span class="n">pop</span><span class="p">()</span> -</pre></div> -</div> -<p>When <tt class="docutils literal"><span class="pre">ctx.pop()</span></tt> is executed in the above example, the teardown -functions are called just before the request context moves from the -stack of active contexts. This becomes relevant if you are using -such constructs in tests.</p> -<p>Generally teardown functions must take every necesary step to avoid -that they will fail. If they do execute code that might fail they -will have to surround the execution of these code by try/except -statements and log ocurring errors.</p> -</dd></dl> - -<dl class="attribute"> -<dt id="flask.Flask.teardown_request_funcs"> -<tt class="descname">teardown_request_funcs</tt><em class="property"> = None</em><a class="headerlink" href="#flask.Flask.teardown_request_funcs" title="Permalink to this definition">¶</a></dt> -<dd><p>A dictionary with lists of functions that are called after -each request, even if an exception has occurred. The key of the -dictionary is the name of the blueprint this function is active for, -<cite>None</cite> for all requests. These functions are not allowed to modify -the request, and their return values are ignored. If an exception -occurred while processing the request, it gets passed to each -teardown_request function. To register a function here, use the -<a class="reference internal" href="#flask.Flask.teardown_request" title="flask.Flask.teardown_request"><tt class="xref py py-meth docutils literal"><span class="pre">teardown_request()</span></tt></a> decorator.</p> -<p class="versionadded"> -<span class="versionmodified">New in version 0.7.</span></p> -</dd></dl> - -<dl class="attribute"> -<dt id="flask.Flask.template_context_processors"> -<tt class="descname">template_context_processors</tt><em class="property"> = None</em><a class="headerlink" href="#flask.Flask.template_context_processors" title="Permalink to this definition">¶</a></dt> -<dd><p>A dictionary with list of functions that are called without argument -to populate the template context. The key of the dictionary is the -name of the blueprint this function is active for, <cite>None</cite> for all -requests. Each returns a dictionary that the template context is -updated with. To register a function here, use the -<a class="reference internal" href="#flask.Flask.context_processor" title="flask.Flask.context_processor"><tt class="xref py py-meth docutils literal"><span class="pre">context_processor()</span></tt></a> decorator.</p> -</dd></dl> - -<dl class="method"> -<dt id="flask.Flask.template_filter"> -<tt class="descname">template_filter</tt><big>(</big><em>*args</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#flask.Flask.template_filter" title="Permalink to this definition">¶</a></dt> -<dd><p>A decorator that is used to register custom template filter. -You can specify a name for the filter, otherwise the function -name will be used. Example:</p> -<div class="highlight-python"><div class="highlight"><pre><span class="nd">@app.template_filter</span><span class="p">()</span> -<span class="k">def</span> <span class="nf">reverse</span><span class="p">(</span><span class="n">s</span><span class="p">):</span> - <span class="k">return</span> <span class="n">s</span><span class="p">[::</span><span class="o">-</span><span class="mi">1</span><span class="p">]</span> -</pre></div> -</div> -<table class="docutils field-list" frame="void" rules="none"> -<col class="field-name" /> -<col class="field-body" /> -<tbody valign="top"> -<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>name</strong> – the optional name of the filter, otherwise the -function name will be used.</td> -</tr> -</tbody> -</table> -</dd></dl> - -<dl class="method"> -<dt id="flask.Flask.test_client"> -<tt class="descname">test_client</tt><big>(</big><em>use_cookies=True</em><big>)</big><a class="headerlink" href="#flask.Flask.test_client" title="Permalink to this definition">¶</a></dt> -<dd><p>Creates a test client for this application. For information -about unit testing head over to <a class="reference internal" href="testing.html#testing"><em>Testing Flask Applications</em></a>.</p> -<p>The test client can be used in a <cite>with</cite> block to defer the closing down -of the context until the end of the <cite>with</cite> block. This is useful if -you want to access the context locals for testing:</p> -<div class="highlight-python"><div class="highlight"><pre><span class="k">with</span> <span class="n">app</span><span class="o">.</span><span class="n">test_client</span><span class="p">()</span> <span class="k">as</span> <span class="n">c</span><span class="p">:</span> - <span class="n">rv</span> <span class="o">=</span> <span class="n">c</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s">'/?vodka=42'</span><span class="p">)</span> - <span class="k">assert</span> <span class="n">request</span><span class="o">.</span><span class="n">args</span><span class="p">[</span><span class="s">'vodka'</span><span class="p">]</span> <span class="o">==</span> <span class="s">'42'</span> -</pre></div> -</div> -<p>See <a class="reference internal" href="#flask.testing.FlaskClient" title="flask.testing.FlaskClient"><tt class="xref py py-class docutils literal"><span class="pre">FlaskClient</span></tt></a> for more information.</p> -<p class="versionchanged"> -<span class="versionmodified">Changed in version 0.4: </span>added support for <cite>with</cite> block usage for the client.</p> -<p class="versionadded"> -<span class="versionmodified">New in version 0.7: </span>The <cite>use_cookies</cite> parameter was added as well as the ability -to override the client to be used by setting the -<a class="reference internal" href="#flask.Flask.test_client_class" title="flask.Flask.test_client_class"><tt class="xref py py-attr docutils literal"><span class="pre">test_client_class</span></tt></a> attribute.</p> -</dd></dl> - -<dl class="attribute"> -<dt id="flask.Flask.test_client_class"> -<tt class="descname">test_client_class</tt><em class="property"> = None</em><a class="headerlink" href="#flask.Flask.test_client_class" title="Permalink to this definition">¶</a></dt> -<dd><p>the test client that is used with when <cite>test_client</cite> is used.</p> -<p class="versionadded"> -<span class="versionmodified">New in version 0.7.</span></p> -</dd></dl> - -<dl class="method"> -<dt id="flask.Flask.test_request_context"> -<tt class="descname">test_request_context</tt><big>(</big><em>*args</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#flask.Flask.test_request_context" title="Permalink to this definition">¶</a></dt> -<dd><p>Creates a WSGI environment from the given values (see -<tt class="xref py py-func docutils literal"><span class="pre">werkzeug.test.EnvironBuilder()</span></tt> for more information, this -function accepts the same arguments).</p> -</dd></dl> - -<dl class="attribute"> -<dt id="flask.Flask.testing"> -<tt class="descname">testing</tt><a class="headerlink" href="#flask.Flask.testing" title="Permalink to this definition">¶</a></dt> -<dd><p>The testing flag. Set this to <cite>True</cite> to enable the test mode of -Flask extensions (and in the future probably also Flask itself). -For example this might activate unittest helpers that have an -additional runtime cost which should not be enabled by default.</p> -<p>If this is enabled and PROPAGATE_EXCEPTIONS is not changed from the -default it’s implicitly enabled.</p> -<p>This attribute can also be configured from the config with the -<cite>TESTING</cite> configuration key. Defaults to <cite>False</cite>.</p> -</dd></dl> - -<dl class="method"> -<dt id="flask.Flask.trap_http_exception"> -<tt class="descname">trap_http_exception</tt><big>(</big><em>e</em><big>)</big><a class="headerlink" href="#flask.Flask.trap_http_exception" title="Permalink to this definition">¶</a></dt> -<dd><p>Checks if an HTTP exception should be trapped or not. By default -this will return <cite>False</cite> for all exceptions except for a bad request -key error if <tt class="docutils literal"><span class="pre">TRAP_BAD_REQUEST_ERRORS</span></tt> is set to <cite>True</cite>. It -also returns <cite>True</cite> if <tt class="docutils literal"><span class="pre">TRAP_HTTP_EXCEPTIONS</span></tt> is set to <cite>True</cite>.</p> -<p>This is called for all HTTP exceptions raised by a view function. -If it returns <cite>True</cite> for any exception the error handler for this -exception is not called and it shows up as regular exception in the -traceback. This is helpful for debugging implicitly raised HTTP -exceptions.</p> -<p class="versionadded"> -<span class="versionmodified">New in version 0.8.</span></p> -</dd></dl> - -<dl class="method"> -<dt id="flask.Flask.update_template_context"> -<tt class="descname">update_template_context</tt><big>(</big><em>context</em><big>)</big><a class="headerlink" href="#flask.Flask.update_template_context" title="Permalink to this definition">¶</a></dt> -<dd><p>Update the template context with some commonly used variables. -This injects request, session, config and g into the template -context as well as everything template context processors want -to inject. Note that the as of Flask 0.6, the original values -in the context will not be overriden if a context processor -decides to return a value with the same key.</p> -<table class="docutils field-list" frame="void" rules="none"> -<col class="field-name" /> -<col class="field-body" /> -<tbody valign="top"> -<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>context</strong> – the context as a dictionary that is updated in place -to add extra variables.</td> -</tr> -</tbody> -</table> -</dd></dl> - -<dl class="attribute"> -<dt id="flask.Flask.url_default_functions"> -<tt class="descname">url_default_functions</tt><em class="property"> = None</em><a class="headerlink" href="#flask.Flask.url_default_functions" title="Permalink to this definition">¶</a></dt> -<dd><p>A dictionary with lists of functions that can be used as URL value -preprocessors. The key <cite>None</cite> here is used for application wide -callbacks, otherwise the key is the name of the blueprint. -Each of these functions has the chance to modify the dictionary -of URL values before they are used as the keyword arguments of the -view function. For each function registered this one should also -provide a <a class="reference internal" href="#flask.Flask.url_defaults" title="flask.Flask.url_defaults"><tt class="xref py py-meth docutils literal"><span class="pre">url_defaults()</span></tt></a> function that adds the parameters -automatically again that were removed that way.</p> -<p class="versionadded"> -<span class="versionmodified">New in version 0.7.</span></p> -</dd></dl> - -<dl class="method"> -<dt id="flask.Flask.url_defaults"> -<tt class="descname">url_defaults</tt><big>(</big><em>*args</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#flask.Flask.url_defaults" title="Permalink to this definition">¶</a></dt> -<dd><p>Callback function for URL defaults for all view functions of the -application. It’s called with the endpoint and values and should -update the values passed in place.</p> -</dd></dl> - -<dl class="attribute"> -<dt id="flask.Flask.url_map"> -<tt class="descname">url_map</tt><em class="property"> = None</em><a class="headerlink" href="#flask.Flask.url_map" title="Permalink to this definition">¶</a></dt> -<dd><p>The <a class="reference external" href="http://werkzeug.pocoo.org/docs/routing/#werkzeug.routing.Map" title="(in Werkzeug v0.7)"><tt class="xref py py-class docutils literal"><span class="pre">Map</span></tt></a> for this instance. You can use -this to change the routing converters after the class was created -but before any routes are connected. Example:</p> -<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">werkzeug.routing</span> <span class="kn">import</span> <span class="n">BaseConverter</span> - -<span class="k">class</span> <span class="nc">ListConverter</span><span class="p">(</span><span class="n">BaseConverter</span><span class="p">):</span> - <span class="k">def</span> <span class="nf">to_python</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">value</span><span class="p">):</span> - <span class="k">return</span> <span class="n">value</span><span class="o">.</span><span class="n">split</span><span class="p">(</span><span class="s">','</span><span class="p">)</span> - <span class="k">def</span> <span class="nf">to_url</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">values</span><span class="p">):</span> - <span class="k">return</span> <span class="s">','</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">BaseConverter</span><span class="o">.</span><span class="n">to_url</span><span class="p">(</span><span class="n">value</span><span class="p">)</span> - <span class="k">for</span> <span class="n">value</span> <span class="ow">in</span> <span class="n">values</span><span class="p">)</span> - -<span class="n">app</span> <span class="o">=</span> <span class="n">Flask</span><span class="p">(</span><span class="n">__name__</span><span class="p">)</span> -<span class="n">app</span><span class="o">.</span><span class="n">url_map</span><span class="o">.</span><span class="n">converters</span><span class="p">[</span><span class="s">'list'</span><span class="p">]</span> <span class="o">=</span> <span class="n">ListConverter</span> -</pre></div> -</div> -</dd></dl> - -<dl class="attribute"> -<dt id="flask.Flask.url_rule_class"> -<tt class="descname">url_rule_class</tt><a class="headerlink" href="#flask.Flask.url_rule_class" title="Permalink to this definition">¶</a></dt> -<dd><p>The rule object to use for URL rules created. This is used by -<a class="reference internal" href="#flask.Flask.add_url_rule" title="flask.Flask.add_url_rule"><tt class="xref py py-meth docutils literal"><span class="pre">add_url_rule()</span></tt></a>. Defaults to <a class="reference external" href="http://werkzeug.pocoo.org/docs/routing/#werkzeug.routing.Rule" title="(in Werkzeug v0.7)"><tt class="xref py py-class docutils literal"><span class="pre">werkzeug.routing.Rule</span></tt></a>.</p> -<p class="versionadded"> -<span class="versionmodified">New in version 0.7.</span></p> -<p>alias of <tt class="xref py py-class docutils literal"><span class="pre">Rule</span></tt></p> -</dd></dl> - -<dl class="method"> -<dt id="flask.Flask.url_value_preprocessor"> -<tt class="descname">url_value_preprocessor</tt><big>(</big><em>*args</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#flask.Flask.url_value_preprocessor" title="Permalink to this definition">¶</a></dt> -<dd><p>Registers a function as URL value preprocessor for all view -functions of the application. It’s called before the view functions -are called and can modify the url values provided.</p> -</dd></dl> - -<dl class="attribute"> -<dt id="flask.Flask.url_value_preprocessors"> -<tt class="descname">url_value_preprocessors</tt><em class="property"> = None</em><a class="headerlink" href="#flask.Flask.url_value_preprocessors" title="Permalink to this definition">¶</a></dt> -<dd><p>A dictionary with lists of functions that can be used as URL -value processor functions. Whenever a URL is built these functions -are called to modify the dictionary of values in place. The key -<cite>None</cite> here is used for application wide -callbacks, otherwise the key is the name of the blueprint. -Each of these functions has the chance to modify the dictionary</p> -<p class="versionadded"> -<span class="versionmodified">New in version 0.7.</span></p> -</dd></dl> - -<dl class="attribute"> -<dt id="flask.Flask.use_x_sendfile"> -<tt class="descname">use_x_sendfile</tt><a class="headerlink" href="#flask.Flask.use_x_sendfile" title="Permalink to this definition">¶</a></dt> -<dd><p>Enable this if you want to use the X-Sendfile feature. Keep in -mind that the server has to support this. This only affects files -sent with the <a class="reference internal" href="#flask.send_file" title="flask.send_file"><tt class="xref py py-func docutils literal"><span class="pre">send_file()</span></tt></a> method.</p> -<p class="versionadded"> -<span class="versionmodified">New in version 0.2.</span></p> -<p>This attribute can also be configured from the config with the -<cite>USE_X_SENDFILE</cite> configuration key. Defaults to <cite>False</cite>.</p> -</dd></dl> - -<dl class="attribute"> -<dt id="flask.Flask.view_functions"> -<tt class="descname">view_functions</tt><em class="property"> = None</em><a class="headerlink" href="#flask.Flask.view_functions" title="Permalink to this definition">¶</a></dt> -<dd><p>A dictionary of all view functions registered. The keys will -be function names which are also used to generate URLs and -the values are the function objects themselves. -To register a view function, use the <a class="reference internal" href="#flask.Flask.route" title="flask.Flask.route"><tt class="xref py py-meth docutils literal"><span class="pre">route()</span></tt></a> decorator.</p> -</dd></dl> - -<dl class="method"> -<dt id="flask.Flask.wsgi_app"> -<tt class="descname">wsgi_app</tt><big>(</big><em>environ</em>, <em>start_response</em><big>)</big><a class="headerlink" href="#flask.Flask.wsgi_app" title="Permalink to this definition">¶</a></dt> -<dd><p>The actual WSGI application. This is not implemented in -<cite>__call__</cite> so that middlewares can be applied without losing a -reference to the class. So instead of doing this:</p> -<div class="highlight-python"><div class="highlight"><pre><span class="n">app</span> <span class="o">=</span> <span class="n">MyMiddleware</span><span class="p">(</span><span class="n">app</span><span class="p">)</span> -</pre></div> -</div> -<p>It’s a better idea to do this instead:</p> -<div class="highlight-python"><div class="highlight"><pre><span class="n">app</span><span class="o">.</span><span class="n">wsgi_app</span> <span class="o">=</span> <span class="n">MyMiddleware</span><span class="p">(</span><span class="n">app</span><span class="o">.</span><span class="n">wsgi_app</span><span class="p">)</span> -</pre></div> -</div> -<p>Then you still have the original application object around and -can continue to call methods on it.</p> -<p class="versionchanged"> -<span class="versionmodified">Changed in version 0.7: </span>The behavior of the before and after request callbacks was changed -under error conditions and a new callback was added that will -always execute at the end of the request, independent on if an -error ocurred or not. See <a class="reference internal" href="reqcontext.html#callbacks-and-errors"><em>Callbacks and Errors</em></a>.</p> -<table class="docutils field-list" frame="void" rules="none"> -<col class="field-name" /> -<col class="field-body" /> -<tbody valign="top"> -<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple"> -<li><strong>environ</strong> – a WSGI environment</li> -<li><strong>start_response</strong> – a callable accepting a status code, -a list of headers and an optional -exception context to start the response</li> -</ul> -</td> -</tr> -</tbody> -</table> -</dd></dl> - -</dd></dl> - -</div> -<div class="section" id="blueprint-objects"> -<h2>Blueprint Objects<a class="headerlink" href="#blueprint-objects" title="Permalink to this headline">¶</a></h2> -<dl class="class"> -<dt id="flask.Blueprint"> -<em class="property">class </em><tt class="descclassname">flask.</tt><tt class="descname">Blueprint</tt><big>(</big><em>name</em>, <em>import_name</em>, <em>static_folder=None</em>, <em>static_url_path=None</em>, <em>template_folder=None</em>, <em>url_prefix=None</em>, <em>subdomain=None</em>, <em>url_defaults=None</em><big>)</big><a class="headerlink" href="#flask.Blueprint" title="Permalink to this definition">¶</a></dt> -<dd><p>Represents a blueprint. A blueprint is an object that records -functions that will be called with the -<tt class="xref py py-class docutils literal"><span class="pre">BlueprintSetupState</span></tt> later to register functions -or other things on the main application. See <a class="reference internal" href="blueprints.html#blueprints"><em>Modular Applications with Blueprints</em></a> for more -information.</p> -<p class="versionadded"> -<span class="versionmodified">New in version 0.7.</span></p> -<dl class="method"> -<dt id="flask.Blueprint.add_url_rule"> -<tt class="descname">add_url_rule</tt><big>(</big><em>rule</em>, <em>endpoint=None</em>, <em>view_func=None</em>, <em>**options</em><big>)</big><a class="headerlink" href="#flask.Blueprint.add_url_rule" title="Permalink to this definition">¶</a></dt> -<dd><p>Like <a class="reference internal" href="#flask.Flask.add_url_rule" title="flask.Flask.add_url_rule"><tt class="xref py py-meth docutils literal"><span class="pre">Flask.add_url_rule()</span></tt></a> but for a blueprint. The endpoint for -the <a class="reference internal" href="#flask.url_for" title="flask.url_for"><tt class="xref py py-func docutils literal"><span class="pre">url_for()</span></tt></a> function is prefixed with the name of the blueprint.</p> -</dd></dl> - -<dl class="method"> -<dt id="flask.Blueprint.after_app_request"> -<tt class="descname">after_app_request</tt><big>(</big><em>f</em><big>)</big><a class="headerlink" href="#flask.Blueprint.after_app_request" title="Permalink to this definition">¶</a></dt> -<dd><p>Like <a class="reference internal" href="#flask.Flask.after_request" title="flask.Flask.after_request"><tt class="xref py py-meth docutils literal"><span class="pre">Flask.after_request()</span></tt></a> but for a blueprint. Such a function -is executed after each request, even if outside of the blueprint.</p> -</dd></dl> - -<dl class="method"> -<dt id="flask.Blueprint.after_request"> -<tt class="descname">after_request</tt><big>(</big><em>f</em><big>)</big><a class="headerlink" href="#flask.Blueprint.after_request" title="Permalink to this definition">¶</a></dt> -<dd><p>Like <a class="reference internal" href="#flask.Flask.after_request" title="flask.Flask.after_request"><tt class="xref py py-meth docutils literal"><span class="pre">Flask.after_request()</span></tt></a> but for a blueprint. This function -is only executed after each request that is handled by a function of -that blueprint.</p> -</dd></dl> - -<dl class="method"> -<dt id="flask.Blueprint.app_context_processor"> -<tt class="descname">app_context_processor</tt><big>(</big><em>f</em><big>)</big><a class="headerlink" href="#flask.Blueprint.app_context_processor" title="Permalink to this definition">¶</a></dt> -<dd><p>Like <a class="reference internal" href="#flask.Flask.context_processor" title="flask.Flask.context_processor"><tt class="xref py py-meth docutils literal"><span class="pre">Flask.context_processor()</span></tt></a> but for a blueprint. Such a -function is executed each request, even if outside of the blueprint.</p> -</dd></dl> - -<dl class="method"> -<dt id="flask.Blueprint.app_errorhandler"> -<tt class="descname">app_errorhandler</tt><big>(</big><em>code</em><big>)</big><a class="headerlink" href="#flask.Blueprint.app_errorhandler" title="Permalink to this definition">¶</a></dt> -<dd><p>Like <a class="reference internal" href="#flask.Flask.errorhandler" title="flask.Flask.errorhandler"><tt class="xref py py-meth docutils literal"><span class="pre">Flask.errorhandler()</span></tt></a> but for a blueprint. This -handler is used for all requests, even if outside of the blueprint.</p> -</dd></dl> - -<dl class="method"> -<dt id="flask.Blueprint.app_url_defaults"> -<tt class="descname">app_url_defaults</tt><big>(</big><em>f</em><big>)</big><a class="headerlink" href="#flask.Blueprint.app_url_defaults" title="Permalink to this definition">¶</a></dt> -<dd><p>Same as <a class="reference internal" href="#flask.Blueprint.url_defaults" title="flask.Blueprint.url_defaults"><tt class="xref py py-meth docutils literal"><span class="pre">url_defaults()</span></tt></a> but application wide.</p> -</dd></dl> - -<dl class="method"> -<dt id="flask.Blueprint.app_url_value_preprocessor"> -<tt class="descname">app_url_value_preprocessor</tt><big>(</big><em>f</em><big>)</big><a class="headerlink" href="#flask.Blueprint.app_url_value_preprocessor" title="Permalink to this definition">¶</a></dt> -<dd><p>Same as <a class="reference internal" href="#flask.Blueprint.url_value_preprocessor" title="flask.Blueprint.url_value_preprocessor"><tt class="xref py py-meth docutils literal"><span class="pre">url_value_preprocessor()</span></tt></a> but application wide.</p> -</dd></dl> - -<dl class="method"> -<dt id="flask.Blueprint.before_app_first_request"> -<tt class="descname">before_app_first_request</tt><big>(</big><em>f</em><big>)</big><a class="headerlink" href="#flask.Blueprint.before_app_first_request" title="Permalink to this definition">¶</a></dt> -<dd><p>Like <a class="reference internal" href="#flask.Flask.before_first_request" title="flask.Flask.before_first_request"><tt class="xref py py-meth docutils literal"><span class="pre">Flask.before_first_request()</span></tt></a>. Such a function is -executed before the first request to the application.</p> -</dd></dl> - -<dl class="method"> -<dt id="flask.Blueprint.before_app_request"> -<tt class="descname">before_app_request</tt><big>(</big><em>f</em><big>)</big><a class="headerlink" href="#flask.Blueprint.before_app_request" title="Permalink to this definition">¶</a></dt> -<dd><p>Like <a class="reference internal" href="#flask.Flask.before_request" title="flask.Flask.before_request"><tt class="xref py py-meth docutils literal"><span class="pre">Flask.before_request()</span></tt></a>. Such a function is executed -before each request, even if outside of a blueprint.</p> -</dd></dl> - -<dl class="method"> -<dt id="flask.Blueprint.before_request"> -<tt class="descname">before_request</tt><big>(</big><em>f</em><big>)</big><a class="headerlink" href="#flask.Blueprint.before_request" title="Permalink to this definition">¶</a></dt> -<dd><p>Like <a class="reference internal" href="#flask.Flask.before_request" title="flask.Flask.before_request"><tt class="xref py py-meth docutils literal"><span class="pre">Flask.before_request()</span></tt></a> but for a blueprint. This function -is only executed before each request that is handled by a function of -that blueprint.</p> -</dd></dl> - -<dl class="method"> -<dt id="flask.Blueprint.context_processor"> -<tt class="descname">context_processor</tt><big>(</big><em>f</em><big>)</big><a class="headerlink" href="#flask.Blueprint.context_processor" title="Permalink to this definition">¶</a></dt> -<dd><p>Like <a class="reference internal" href="#flask.Flask.context_processor" title="flask.Flask.context_processor"><tt class="xref py py-meth docutils literal"><span class="pre">Flask.context_processor()</span></tt></a> but for a blueprint. This -function is only executed for requests handled by a blueprint.</p> -</dd></dl> - -<dl class="method"> -<dt id="flask.Blueprint.endpoint"> -<tt class="descname">endpoint</tt><big>(</big><em>endpoint</em><big>)</big><a class="headerlink" href="#flask.Blueprint.endpoint" title="Permalink to this definition">¶</a></dt> -<dd><p>Like <a class="reference internal" href="#flask.Flask.endpoint" title="flask.Flask.endpoint"><tt class="xref py py-meth docutils literal"><span class="pre">Flask.endpoint()</span></tt></a> but for a blueprint. This does not -prefix the endpoint with the blueprint name, this has to be done -explicitly by the user of this method. If the endpoint is prefixed -with a <cite>.</cite> it will be registered to the current blueprint, otherwise -it’s an application independent endpoint.</p> -</dd></dl> - -<dl class="method"> -<dt id="flask.Blueprint.errorhandler"> -<tt class="descname">errorhandler</tt><big>(</big><em>code_or_exception</em><big>)</big><a class="headerlink" href="#flask.Blueprint.errorhandler" title="Permalink to this definition">¶</a></dt> -<dd><p>Registers an error handler that becomes active for this blueprint -only. Please be aware that routing does not happen local to a -blueprint so an error handler for 404 usually is not handled by -a blueprint unless it is caused inside a view function. Another -special case is the 500 internal server error which is always looked -up from the application.</p> -<p>Otherwise works as the <a class="reference internal" href="#flask.Flask.errorhandler" title="flask.Flask.errorhandler"><tt class="xref py py-meth docutils literal"><span class="pre">errorhandler()</span></tt></a> decorator -of the <a class="reference internal" href="#flask.Flask" title="flask.Flask"><tt class="xref py py-class docutils literal"><span class="pre">Flask</span></tt></a> object.</p> -</dd></dl> - -<dl class="attribute"> -<dt id="flask.Blueprint.has_static_folder"> -<tt class="descname">has_static_folder</tt><a class="headerlink" href="#flask.Blueprint.has_static_folder" title="Permalink to this definition">¶</a></dt> -<dd><p>This is <cite>True</cite> if the package bound object’s container has a -folder named <tt class="docutils literal"><span class="pre">'static'</span></tt>.</p> -<p class="versionadded"> -<span class="versionmodified">New in version 0.5.</span></p> -</dd></dl> - -<dl class="attribute"> -<dt id="flask.Blueprint.jinja_loader"> -<tt class="descname">jinja_loader</tt><a class="headerlink" href="#flask.Blueprint.jinja_loader" title="Permalink to this definition">¶</a></dt> -<dd><p>The Jinja loader for this package bound object.</p> -<p class="versionadded"> -<span class="versionmodified">New in version 0.5.</span></p> -</dd></dl> - -<dl class="method"> -<dt id="flask.Blueprint.make_setup_state"> -<tt class="descname">make_setup_state</tt><big>(</big><em>app</em>, <em>options</em>, <em>first_registration=False</em><big>)</big><a class="headerlink" href="#flask.Blueprint.make_setup_state" title="Permalink to this definition">¶</a></dt> -<dd><p>Creates an instance of <a class="reference internal" href="#flask.blueprints.BlueprintSetupState" title="flask.blueprints.BlueprintSetupState"><tt class="xref py py-meth docutils literal"><span class="pre">BlueprintSetupState()</span></tt></a> -object that is later passed to the register callback functions. -Subclasses can override this to return a subclass of the setup state.</p> -</dd></dl> - -<dl class="method"> -<dt id="flask.Blueprint.open_resource"> -<tt class="descname">open_resource</tt><big>(</big><em>resource</em>, <em>mode='rb'</em><big>)</big><a class="headerlink" href="#flask.Blueprint.open_resource" title="Permalink to this definition">¶</a></dt> -<dd><p>Opens a resource from the application’s resource folder. To see -how this works, consider the following folder structure:</p> -<div class="highlight-python"><pre>/myapplication.py -/schema.sql -/static - /style.css -/templates - /layout.html - /index.html</pre> -</div> -<p>If you want to open the <cite>schema.sql</cite> file you would do the -following:</p> -<div class="highlight-python"><div class="highlight"><pre><span class="k">with</span> <span class="n">app</span><span class="o">.</span><span class="n">open_resource</span><span class="p">(</span><span class="s">'schema.sql'</span><span class="p">)</span> <span class="k">as</span> <span class="n">f</span><span class="p">:</span> - <span class="n">contents</span> <span class="o">=</span> <span class="n">f</span><span class="o">.</span><span class="n">read</span><span class="p">()</span> - <span class="n">do_something_with</span><span class="p">(</span><span class="n">contents</span><span class="p">)</span> -</pre></div> -</div> -<table class="docutils field-list" frame="void" rules="none"> -<col class="field-name" /> -<col class="field-body" /> -<tbody valign="top"> -<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>resource</strong> – the name of the resource. To access resources within -subfolders use forward slashes as separator.</td> -</tr> -</tbody> -</table> -</dd></dl> - -<dl class="method"> -<dt id="flask.Blueprint.record"> -<tt class="descname">record</tt><big>(</big><em>func</em><big>)</big><a class="headerlink" href="#flask.Blueprint.record" title="Permalink to this definition">¶</a></dt> -<dd><p>Registers a function that is called when the blueprint is -registered on the application. This function is called with the -state as argument as returned by the <a class="reference internal" href="#flask.Blueprint.make_setup_state" title="flask.Blueprint.make_setup_state"><tt class="xref py py-meth docutils literal"><span class="pre">make_setup_state()</span></tt></a> -method.</p> -</dd></dl> - -<dl class="method"> -<dt id="flask.Blueprint.record_once"> -<tt class="descname">record_once</tt><big>(</big><em>func</em><big>)</big><a class="headerlink" href="#flask.Blueprint.record_once" title="Permalink to this definition">¶</a></dt> -<dd><p>Works like <a class="reference internal" href="#flask.Blueprint.record" title="flask.Blueprint.record"><tt class="xref py py-meth docutils literal"><span class="pre">record()</span></tt></a> but wraps the function in another -function that will ensure the function is only called once. If the -blueprint is registered a second time on the application, the -function passed is not called.</p> -</dd></dl> - -<dl class="method"> -<dt id="flask.Blueprint.register"> -<tt class="descname">register</tt><big>(</big><em>app</em>, <em>options</em>, <em>first_registration=False</em><big>)</big><a class="headerlink" href="#flask.Blueprint.register" title="Permalink to this definition">¶</a></dt> -<dd><p>Called by <a class="reference internal" href="#flask.Flask.register_blueprint" title="flask.Flask.register_blueprint"><tt class="xref py py-meth docutils literal"><span class="pre">Flask.register_blueprint()</span></tt></a> to register a blueprint -on the application. This can be overridden to customize the register -behavior. Keyword arguments from -<a class="reference internal" href="#flask.Flask.register_blueprint" title="flask.Flask.register_blueprint"><tt class="xref py py-func docutils literal"><span class="pre">register_blueprint()</span></tt></a> are directly forwarded to this -method in the <cite>options</cite> dictionary.</p> -</dd></dl> - -<dl class="method"> -<dt id="flask.Blueprint.route"> -<tt class="descname">route</tt><big>(</big><em>rule</em>, <em>**options</em><big>)</big><a class="headerlink" href="#flask.Blueprint.route" title="Permalink to this definition">¶</a></dt> -<dd><p>Like <a class="reference internal" href="#flask.Flask.route" title="flask.Flask.route"><tt class="xref py py-meth docutils literal"><span class="pre">Flask.route()</span></tt></a> but for a blueprint. The endpoint for the -<a class="reference internal" href="#flask.url_for" title="flask.url_for"><tt class="xref py py-func docutils literal"><span class="pre">url_for()</span></tt></a> function is prefixed with the name of the blueprint.</p> -</dd></dl> - -<dl class="method"> -<dt id="flask.Blueprint.send_static_file"> -<tt class="descname">send_static_file</tt><big>(</big><em>filename</em><big>)</big><a class="headerlink" href="#flask.Blueprint.send_static_file" title="Permalink to this definition">¶</a></dt> -<dd><p>Function used internally to send static files from the static -folder to the browser.</p> -<p class="versionadded"> -<span class="versionmodified">New in version 0.5.</span></p> -</dd></dl> - -<dl class="method"> -<dt id="flask.Blueprint.teardown_app_request"> -<tt class="descname">teardown_app_request</tt><big>(</big><em>f</em><big>)</big><a class="headerlink" href="#flask.Blueprint.teardown_app_request" title="Permalink to this definition">¶</a></dt> -<dd><p>Like <a class="reference internal" href="#flask.Flask.teardown_request" title="flask.Flask.teardown_request"><tt class="xref py py-meth docutils literal"><span class="pre">Flask.teardown_request()</span></tt></a> but for a blueprint. Such a -function is executed when tearing down each request, even if outside of -the blueprint.</p> -</dd></dl> - -<dl class="method"> -<dt id="flask.Blueprint.teardown_request"> -<tt class="descname">teardown_request</tt><big>(</big><em>f</em><big>)</big><a class="headerlink" href="#flask.Blueprint.teardown_request" title="Permalink to this definition">¶</a></dt> -<dd><p>Like <a class="reference internal" href="#flask.Flask.teardown_request" title="flask.Flask.teardown_request"><tt class="xref py py-meth docutils literal"><span class="pre">Flask.teardown_request()</span></tt></a> but for a blueprint. This -function is only executed when tearing down requests handled by a -function of that blueprint. Teardown request functions are executed -when the request context is popped, even when no actual request was -performed.</p> -</dd></dl> - -<dl class="method"> -<dt id="flask.Blueprint.url_defaults"> -<tt class="descname">url_defaults</tt><big>(</big><em>f</em><big>)</big><a class="headerlink" href="#flask.Blueprint.url_defaults" title="Permalink to this definition">¶</a></dt> -<dd><p>Callback function for URL defaults for this blueprint. It’s called -with the endpoint and values and should update the values passed -in place.</p> -</dd></dl> - -<dl class="method"> -<dt id="flask.Blueprint.url_value_preprocessor"> -<tt class="descname">url_value_preprocessor</tt><big>(</big><em>f</em><big>)</big><a class="headerlink" href="#flask.Blueprint.url_value_preprocessor" title="Permalink to this definition">¶</a></dt> -<dd><p>Registers a function as URL value preprocessor for this -blueprint. It’s called before the view functions are called and -can modify the url values provided.</p> -</dd></dl> - -</dd></dl> - -</div> -<div class="section" id="incoming-request-data"> -<h2>Incoming Request Data<a class="headerlink" href="#incoming-request-data" title="Permalink to this headline">¶</a></h2> -<dl class="class"> -<dt id="flask.Request"> -<em class="property">class </em><tt class="descclassname">flask.</tt><tt class="descname">Request</tt><big>(</big><em>environ</em>, <em>populate_request=True</em>, <em>shallow=False</em><big>)</big><a class="headerlink" href="#flask.Request" title="Permalink to this definition">¶</a></dt> -<dd><p>The request object used by default in Flask. Remembers the -matched endpoint and view arguments.</p> -<p>It is what ends up as <a class="reference internal" href="#flask.request" title="flask.request"><tt class="xref py py-class docutils literal"><span class="pre">request</span></tt></a>. If you want to replace -the request object used you can subclass this and set -<a class="reference internal" href="#flask.Flask.request_class" title="flask.Flask.request_class"><tt class="xref py py-attr docutils literal"><span class="pre">request_class</span></tt></a> to your subclass.</p> -<p>The request object is a <a class="reference external" href="http://werkzeug.pocoo.org/docs/wrappers/#werkzeug.wrappers.Request" title="(in Werkzeug v0.7)"><tt class="xref py py-class docutils literal"><span class="pre">Request</span></tt></a> subclass and -provides all of the attributes Werkzeug defines plus a few Flask -specific ones.</p> -<dl class="attribute"> -<dt id="flask.Request.form"> -<tt class="descname">form</tt><a class="headerlink" href="#flask.Request.form" title="Permalink to this definition">¶</a></dt> -<dd><p>A <a class="reference external" href="http://werkzeug.pocoo.org/docs/datastructures/#werkzeug.datastructures.MultiDict" title="(in Werkzeug v0.7)"><tt class="xref py py-class docutils literal"><span class="pre">MultiDict</span></tt></a> with the parsed form data from <cite>POST</cite> -or <cite>PUT</cite> requests. Please keep in mind that file uploads will not -end up here, but instead in the <a class="reference internal" href="#flask.Request.files" title="flask.Request.files"><tt class="xref py py-attr docutils literal"><span class="pre">files</span></tt></a> attribute.</p> -</dd></dl> - -<dl class="attribute"> -<dt id="flask.Request.args"> -<tt class="descname">args</tt><a class="headerlink" href="#flask.Request.args" title="Permalink to this definition">¶</a></dt> -<dd><p>A <a class="reference external" href="http://werkzeug.pocoo.org/docs/datastructures/#werkzeug.datastructures.MultiDict" title="(in Werkzeug v0.7)"><tt class="xref py py-class docutils literal"><span class="pre">MultiDict</span></tt></a> with the parsed contents of the query -string. (The part in the URL after the question mark).</p> -</dd></dl> - -<dl class="attribute"> -<dt id="flask.Request.values"> -<tt class="descname">values</tt><a class="headerlink" href="#flask.Request.values" title="Permalink to this definition">¶</a></dt> -<dd><p>A <a class="reference external" href="http://werkzeug.pocoo.org/docs/datastructures/#werkzeug.datastructures.CombinedMultiDict" title="(in Werkzeug v0.7)"><tt class="xref py py-class docutils literal"><span class="pre">CombinedMultiDict</span></tt></a> with the contents of both -<a class="reference internal" href="#flask.Request.form" title="flask.Request.form"><tt class="xref py py-attr docutils literal"><span class="pre">form</span></tt></a> and <a class="reference internal" href="#flask.Request.args" title="flask.Request.args"><tt class="xref py py-attr docutils literal"><span class="pre">args</span></tt></a>.</p> -</dd></dl> - -<dl class="attribute"> -<dt id="flask.Request.cookies"> -<tt class="descname">cookies</tt><a class="headerlink" href="#flask.Request.cookies" title="Permalink to this definition">¶</a></dt> -<dd><p>A <a class="reference external" href="http://docs.python.org/dev/library/stdtypes.html#dict" title="(in Python v3.3)"><tt class="xref py py-class docutils literal"><span class="pre">dict</span></tt></a> with the contents of all cookies transmitted with -the request.</p> -</dd></dl> - -<dl class="attribute"> -<dt id="flask.Request.stream"> -<tt class="descname">stream</tt><a class="headerlink" href="#flask.Request.stream" title="Permalink to this definition">¶</a></dt> -<dd><p>If the incoming form data was not encoded with a known mimetype -the data is stored unmodified in this stream for consumption. Most -of the time it is a better idea to use <a class="reference internal" href="#flask.Request.data" title="flask.Request.data"><tt class="xref py py-attr docutils literal"><span class="pre">data</span></tt></a> which will give -you that data as a string. The stream only returns the data once.</p> -</dd></dl> - -<dl class="attribute"> -<dt id="flask.Request.headers"> -<tt class="descname">headers</tt><a class="headerlink" href="#flask.Request.headers" title="Permalink to this definition">¶</a></dt> -<dd><p>The incoming request headers as a dictionary like object.</p> -</dd></dl> - -<dl class="attribute"> -<dt id="flask.Request.data"> -<tt class="descname">data</tt><a class="headerlink" href="#flask.Request.data" title="Permalink to this definition">¶</a></dt> -<dd><p>Contains the incoming request data as string in case it came with -a mimetype Flask does not handle.</p> -</dd></dl> - -<dl class="attribute"> -<dt id="flask.Request.files"> -<tt class="descname">files</tt><a class="headerlink" href="#flask.Request.files" title="Permalink to this definition">¶</a></dt> -<dd><p>A <a class="reference external" href="http://werkzeug.pocoo.org/docs/datastructures/#werkzeug.datastructures.MultiDict" title="(in Werkzeug v0.7)"><tt class="xref py py-class docutils literal"><span class="pre">MultiDict</span></tt></a> with files uploaded as part of a -<cite>POST</cite> or <cite>PUT</cite> request. Each file is stored as -<a class="reference external" href="http://werkzeug.pocoo.org/docs/datastructures/#werkzeug.datastructures.FileStorage" title="(in Werkzeug v0.7)"><tt class="xref py py-class docutils literal"><span class="pre">FileStorage</span></tt></a> object. It basically behaves like a -standard file object you know from Python, with the difference that -it also has a <a class="reference external" href="http://werkzeug.pocoo.org/docs/datastructures/#werkzeug.datastructures.FileStorage.save" title="(in Werkzeug v0.7)"><tt class="xref py py-meth docutils literal"><span class="pre">save()</span></tt></a> function that can -store the file on the filesystem.</p> -</dd></dl> - -<dl class="attribute"> -<dt id="flask.Request.environ"> -<tt class="descname">environ</tt><a class="headerlink" href="#flask.Request.environ" title="Permalink to this definition">¶</a></dt> -<dd><p>The underlying WSGI environment.</p> -</dd></dl> - -<dl class="attribute"> -<dt id="flask.Request.method"> -<tt class="descname">method</tt><a class="headerlink" href="#flask.Request.method" title="Permalink to this definition">¶</a></dt> -<dd><p>The current request method (<tt class="docutils literal"><span class="pre">POST</span></tt>, <tt class="docutils literal"><span class="pre">GET</span></tt> etc.)</p> -</dd></dl> - -<dl class="attribute"> -<dt id="flask.Request.path"> -<tt class="descname">path</tt><a class="headerlink" href="#flask.Request.path" title="Permalink to this definition">¶</a></dt> -<dd></dd></dl> - -<dl class="attribute"> -<dt id="flask.Request.script_root"> -<tt class="descname">script_root</tt><a class="headerlink" href="#flask.Request.script_root" title="Permalink to this definition">¶</a></dt> -<dd></dd></dl> - -<dl class="attribute"> -<dt id="flask.Request.url"> -<tt class="descname">url</tt><a class="headerlink" href="#flask.Request.url" title="Permalink to this definition">¶</a></dt> -<dd></dd></dl> - -<dl class="attribute"> -<dt id="flask.Request.base_url"> -<tt class="descname">base_url</tt><a class="headerlink" href="#flask.Request.base_url" title="Permalink to this definition">¶</a></dt> -<dd></dd></dl> - -<dl class="attribute"> -<dt id="flask.Request.url_root"> -<tt class="descname">url_root</tt><a class="headerlink" href="#flask.Request.url_root" title="Permalink to this definition">¶</a></dt> -<dd><p>Provides different ways to look at the current URL. Imagine your -application is listening on the following URL:</p> -<div class="highlight-python"><pre>http://www.example.com/myapplication</pre> -</div> -<p>And a user requests the following URL:</p> -<div class="highlight-python"><pre>http://www.example.com/myapplication/page.html?x=y</pre> -</div> -<p>In this case the values of the above mentioned attributes would be -the following:</p> -<table border="1" class="docutils"> -<colgroup> -<col width="19%" /> -<col width="81%" /> -</colgroup> -<tbody valign="top"> -<tr class="row-odd"><td><cite>path</cite></td> -<td><tt class="docutils literal"><span class="pre">/page.html</span></tt></td> -</tr> -<tr class="row-even"><td><cite>script_root</cite></td> -<td><tt class="docutils literal"><span class="pre">/myapplication</span></tt></td> -</tr> -<tr class="row-odd"><td><cite>base_url</cite></td> -<td><tt class="docutils literal"><span class="pre">http://www.example.com/myapplication/page.html</span></tt></td> -</tr> -<tr class="row-even"><td><cite>url</cite></td> -<td><tt class="docutils literal"><span class="pre">http://www.example.com/myapplication/page.html?x=y</span></tt></td> -</tr> -<tr class="row-odd"><td><cite>url_root</cite></td> -<td><tt class="docutils literal"><span class="pre">http://www.example.com/myapplication/</span></tt></td> -</tr> -</tbody> -</table> -</dd></dl> - -<dl class="attribute"> -<dt id="flask.Request.is_xhr"> -<tt class="descname">is_xhr</tt><a class="headerlink" href="#flask.Request.is_xhr" title="Permalink to this definition">¶</a></dt> -<dd><p><cite>True</cite> if the request was triggered via a JavaScript -<cite>XMLHttpRequest</cite>. This only works with libraries that support the -<tt class="docutils literal"><span class="pre">X-Requested-With</span></tt> header and set it to <cite>XMLHttpRequest</cite>. -Libraries that do that are prototype, jQuery and Mochikit and -probably some more.</p> -</dd></dl> - -<dl class="attribute"> -<dt id="flask.Request.blueprint"> -<tt class="descname">blueprint</tt><a class="headerlink" href="#flask.Request.blueprint" title="Permalink to this definition">¶</a></dt> -<dd><p>The name of the current blueprint</p> -</dd></dl> - -<dl class="attribute"> -<dt id="flask.Request.endpoint"> -<tt class="descname">endpoint</tt><a class="headerlink" href="#flask.Request.endpoint" title="Permalink to this definition">¶</a></dt> -<dd><p>The endpoint that matched the request. This in combination with -<a class="reference internal" href="#flask.Request.view_args" title="flask.Request.view_args"><tt class="xref py py-attr docutils literal"><span class="pre">view_args</span></tt></a> can be used to reconstruct the same or a -modified URL. If an exception happened when matching, this will -be <cite>None</cite>.</p> -</dd></dl> - -<dl class="attribute"> -<dt id="flask.Request.json"> -<tt class="descname">json</tt><a class="headerlink" href="#flask.Request.json" title="Permalink to this definition">¶</a></dt> -<dd><p>If the mimetype is <cite>application/json</cite> this will contain the -parsed JSON data. Otherwise this will be <cite>None</cite>.</p> -<p>This requires Python 2.6 or an installed version of simplejson.</p> -</dd></dl> - -<dl class="attribute"> -<dt id="flask.Request.max_content_length"> -<tt class="descname">max_content_length</tt><a class="headerlink" href="#flask.Request.max_content_length" title="Permalink to this definition">¶</a></dt> -<dd><p>Read-only view of the <cite>MAX_CONTENT_LENGTH</cite> config key.</p> -</dd></dl> - -<dl class="attribute"> -<dt id="flask.Request.module"> -<tt class="descname">module</tt><a class="headerlink" href="#flask.Request.module" title="Permalink to this definition">¶</a></dt> -<dd><p>The name of the current module if the request was dispatched -to an actual module. This is deprecated functionality, use blueprints -instead.</p> -</dd></dl> - -<dl class="method"> -<dt id="flask.Request.on_json_loading_failed"> -<tt class="descname">on_json_loading_failed</tt><big>(</big><em>e</em><big>)</big><a class="headerlink" href="#flask.Request.on_json_loading_failed" title="Permalink to this definition">¶</a></dt> -<dd><p>Called if decoding of the JSON data failed. The return value of -this method is used by <a class="reference internal" href="#flask.json" title="flask.json"><tt class="xref py py-attr docutils literal"><span class="pre">json</span></tt></a> when an error ocurred. The -default implementation raises a <tt class="xref py py-class docutils literal"><span class="pre">BadRequest</span></tt>.</p> -<p class="versionadded"> -<span class="versionmodified">New in version 0.8.</span></p> -</dd></dl> - -<dl class="attribute"> -<dt id="flask.Request.routing_exception"> -<tt class="descname">routing_exception</tt><em class="property"> = None</em><a class="headerlink" href="#flask.Request.routing_exception" title="Permalink to this definition">¶</a></dt> -<dd><p>if matching the URL failed, this is the exception that will be -raised / was raised as part of the request handling. This is -usually a <a class="reference external" href="http://werkzeug.pocoo.org/docs/exceptions/#werkzeug.exceptions.NotFound" title="(in Werkzeug v0.7)"><tt class="xref py py-exc docutils literal"><span class="pre">NotFound</span></tt></a> exception or -something similar.</p> -</dd></dl> - -<dl class="attribute"> -<dt id="flask.Request.url_rule"> -<tt class="descname">url_rule</tt><em class="property"> = None</em><a class="headerlink" href="#flask.Request.url_rule" title="Permalink to this definition">¶</a></dt> -<dd><p>the internal URL rule that matched the request. This can be -useful to inspect which methods are allowed for the URL from -a before/after handler (<tt class="docutils literal"><span class="pre">request.url_rule.methods</span></tt>) etc.</p> -<p class="versionadded"> -<span class="versionmodified">New in version 0.6.</span></p> -</dd></dl> - -<dl class="attribute"> -<dt id="flask.Request.view_args"> -<tt class="descname">view_args</tt><em class="property"> = None</em><a class="headerlink" href="#flask.Request.view_args" title="Permalink to this definition">¶</a></dt> -<dd><p>a dict of view arguments that matched the request. If an exception -happened when matching, this will be <cite>None</cite>.</p> -</dd></dl> - -</dd></dl> - -<dl class="class"> -<dt id="flask.request"> -<em class="property">class </em><tt class="descclassname">flask.</tt><tt class="descname">request</tt><a class="headerlink" href="#flask.request" title="Permalink to this definition">¶</a></dt> -<dd><p>To access incoming request data, you can use the global <cite>request</cite> -object. Flask parses incoming request data for you and gives you -access to it through that global object. Internally Flask makes -sure that you always get the correct data for the active thread if you -are in a multithreaded environment.</p> -<p>This is a proxy. See <a class="reference internal" href="reqcontext.html#notes-on-proxies"><em>Notes On Proxies</em></a> for more information.</p> -<p>The request object is an instance of a <a class="reference external" href="http://werkzeug.pocoo.org/docs/wrappers/#werkzeug.wrappers.Request" title="(in Werkzeug v0.7)"><tt class="xref py py-class docutils literal"><span class="pre">Request</span></tt></a> -subclass and provides all of the attributes Werkzeug defines. This -just shows a quick overview of the most important ones.</p> -</dd></dl> - -</div> -<div class="section" id="response-objects"> -<h2>Response Objects<a class="headerlink" href="#response-objects" title="Permalink to this headline">¶</a></h2> -<dl class="class"> -<dt id="flask.Response"> -<em class="property">class </em><tt class="descclassname">flask.</tt><tt class="descname">Response</tt><big>(</big><em>response=None</em>, <em>status=None</em>, <em>headers=None</em>, <em>mimetype=None</em>, <em>content_type=None</em>, <em>direct_passthrough=False</em><big>)</big><a class="headerlink" href="#flask.Response" title="Permalink to this definition">¶</a></dt> -<dd><p>The response object that is used by default in Flask. Works like the -response object from Werkzeug but is set to have an HTML mimetype by -default. Quite often you don’t have to create this object yourself because -<a class="reference internal" href="#flask.Flask.make_response" title="flask.Flask.make_response"><tt class="xref py py-meth docutils literal"><span class="pre">make_response()</span></tt></a> will take care of that for you.</p> -<p>If you want to replace the response object used you can subclass this and -set <a class="reference internal" href="#flask.Flask.response_class" title="flask.Flask.response_class"><tt class="xref py py-attr docutils literal"><span class="pre">response_class</span></tt></a> to your subclass.</p> -<dl class="attribute"> -<dt id="flask.Response.headers"> -<tt class="descname">headers</tt><a class="headerlink" href="#flask.Response.headers" title="Permalink to this definition">¶</a></dt> -<dd><p>A <tt class="xref py py-class docutils literal"><span class="pre">Headers</span></tt> object representing the response headers.</p> -</dd></dl> - -<dl class="attribute"> -<dt id="flask.Response.status_code"> -<tt class="descname">status_code</tt><a class="headerlink" href="#flask.Response.status_code" title="Permalink to this definition">¶</a></dt> -<dd><p>The response status as integer.</p> -</dd></dl> - -<dl class="method"> -<dt id="flask.Response.set_cookie"> -<tt class="descname">set_cookie</tt><big>(</big><em>key</em>, <em>value=''</em>, <em>max_age=None</em>, <em>expires=None</em>, <em>path='/'</em>, <em>domain=None</em>, <em>secure=None</em>, <em>httponly=False</em><big>)</big><a class="headerlink" href="#flask.Response.set_cookie" title="Permalink to this definition">¶</a></dt> -<dd><p>Sets a cookie. The parameters are the same as in the cookie <cite>Morsel</cite> -object in the Python standard library but it accepts unicode data, too.</p> -<table class="docutils field-list" frame="void" rules="none"> -<col class="field-name" /> -<col class="field-body" /> -<tbody valign="top"> -<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple"> -<li><strong>key</strong> – the key (name) of the cookie to be set.</li> -<li><strong>value</strong> – the value of the cookie.</li> -<li><strong>max_age</strong> – should be a number of seconds, or <cite>None</cite> (default) if -the cookie should last only as long as the client’s -browser session.</li> -<li><strong>expires</strong> – should be a <cite>datetime</cite> object or UNIX timestamp.</li> -<li><strong>domain</strong> – if you want to set a cross-domain cookie. For example, -<tt class="docutils literal"><span class="pre">domain=".example.com"</span></tt> will set a cookie that is -readable by the domain <tt class="docutils literal"><span class="pre">www.example.com</span></tt>, -<tt class="docutils literal"><span class="pre">foo.example.com</span></tt> etc. Otherwise, a cookie will only -be readable by the domain that set it.</li> -<li><strong>path</strong> – limits the cookie to a given path, per default it will -span the whole domain.</li> -</ul> -</td> -</tr> -</tbody> -</table> -</dd></dl> - -<dl class="attribute"> -<dt id="flask.Response.data"> -<tt class="descname">data</tt><a class="headerlink" href="#flask.Response.data" title="Permalink to this definition">¶</a></dt> -<dd><p>The string representation of the request body. Whenever you access -this property the request iterable is encoded and flattened. This -can lead to unwanted behavior if you stream big data.</p> -<p>This behavior can be disabled by setting -<tt class="xref py py-attr docutils literal"><span class="pre">implicit_sequence_conversion</span></tt> to <cite>False</cite>.</p> -</dd></dl> - -<dl class="attribute"> -<dt id="flask.Response.mimetype"> -<tt class="descname">mimetype</tt><a class="headerlink" href="#flask.Response.mimetype" title="Permalink to this definition">¶</a></dt> -<dd><p>The mimetype (content type without charset etc.)</p> -</dd></dl> - -</dd></dl> - -</div> -<div class="section" id="sessions"> -<h2>Sessions<a class="headerlink" href="#sessions" title="Permalink to this headline">¶</a></h2> -<p>If you have the <a class="reference internal" href="#flask.Flask.secret_key" title="flask.Flask.secret_key"><tt class="xref py py-attr docutils literal"><span class="pre">Flask.secret_key</span></tt></a> set you can use sessions in Flask -applications. A session basically makes it possible to remember -information from one request to another. The way Flask does this is by -using a signed cookie. So the user can look at the session contents, but -not modify it unless they know the secret key, so make sure to set that -to something complex and unguessable.</p> -<p>To access the current session you can use the <a class="reference internal" href="#flask.session" title="flask.session"><tt class="xref py py-class docutils literal"><span class="pre">session</span></tt></a> object:</p> -<dl class="class"> -<dt id="flask.session"> -<em class="property">class </em><tt class="descclassname">flask.</tt><tt class="descname">session</tt><a class="headerlink" href="#flask.session" title="Permalink to this definition">¶</a></dt> -<dd><p>The session object works pretty much like an ordinary dict, with the -difference that it keeps track on modifications.</p> -<p>This is a proxy. See <a class="reference internal" href="reqcontext.html#notes-on-proxies"><em>Notes On Proxies</em></a> for more information.</p> -<p>The following attributes are interesting:</p> -<dl class="attribute"> -<dt id="flask.session.new"> -<tt class="descname">new</tt><a class="headerlink" href="#flask.session.new" title="Permalink to this definition">¶</a></dt> -<dd><p><cite>True</cite> if the session is new, <cite>False</cite> otherwise.</p> -</dd></dl> - -<dl class="attribute"> -<dt id="flask.session.modified"> -<tt class="descname">modified</tt><a class="headerlink" href="#flask.session.modified" title="Permalink to this definition">¶</a></dt> -<dd><p><cite>True</cite> if the session object detected a modification. Be advised -that modifications on mutable structures are not picked up -automatically, in that situation you have to explicitly set the -attribute to <cite>True</cite> yourself. Here an example:</p> -<div class="highlight-python"><div class="highlight"><pre><span class="c"># this change is not picked up because a mutable object (here</span> -<span class="c"># a list) is changed.</span> -<span class="n">session</span><span class="p">[</span><span class="s">'objects'</span><span class="p">]</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="mi">42</span><span class="p">)</span> -<span class="c"># so mark it as modified yourself</span> -<span class="n">session</span><span class="o">.</span><span class="n">modified</span> <span class="o">=</span> <span class="bp">True</span> -</pre></div> -</div> -</dd></dl> - -<dl class="attribute"> -<dt id="flask.session.permanent"> -<tt class="descname">permanent</tt><a class="headerlink" href="#flask.session.permanent" title="Permalink to this definition">¶</a></dt> -<dd><p>If set to <cite>True</cite> the session lives for -<a class="reference internal" href="#flask.Flask.permanent_session_lifetime" title="flask.Flask.permanent_session_lifetime"><tt class="xref py py-attr docutils literal"><span class="pre">permanent_session_lifetime</span></tt></a> seconds. The -default is 31 days. If set to <cite>False</cite> (which is the default) the -session will be deleted when the user closes the browser.</p> -</dd></dl> - -</dd></dl> - -</div> -<div class="section" id="session-interface"> -<h2>Session Interface<a class="headerlink" href="#session-interface" title="Permalink to this headline">¶</a></h2> -<p class="versionadded"> -<span class="versionmodified">New in version 0.8.</span></p> -<p>The session interface provides a simple way to replace the session -implementation that Flask is using.</p> -<dl class="class"> -<dt id="flask.sessions.SessionInterface"> -<em class="property">class </em><tt class="descclassname">flask.sessions.</tt><tt class="descname">SessionInterface</tt><a class="headerlink" href="#flask.sessions.SessionInterface" title="Permalink to this definition">¶</a></dt> -<dd><p>The basic interface you have to implement in order to replace the -default session interface which uses werkzeug’s securecookie -implementation. The only methods you have to implement are -<a class="reference internal" href="#flask.sessions.SessionInterface.open_session" title="flask.sessions.SessionInterface.open_session"><tt class="xref py py-meth docutils literal"><span class="pre">open_session()</span></tt></a> and <a class="reference internal" href="#flask.sessions.SessionInterface.save_session" title="flask.sessions.SessionInterface.save_session"><tt class="xref py py-meth docutils literal"><span class="pre">save_session()</span></tt></a>, the others have -useful defaults which you don’t need to change.</p> -<p>The session object returned by the <a class="reference internal" href="#flask.sessions.SessionInterface.open_session" title="flask.sessions.SessionInterface.open_session"><tt class="xref py py-meth docutils literal"><span class="pre">open_session()</span></tt></a> method has to -provide a dictionary like interface plus the properties and methods -from the <a class="reference internal" href="#flask.sessions.SessionMixin" title="flask.sessions.SessionMixin"><tt class="xref py py-class docutils literal"><span class="pre">SessionMixin</span></tt></a>. We recommend just subclassing a dict -and adding that mixin:</p> -<div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">Session</span><span class="p">(</span><span class="nb">dict</span><span class="p">,</span> <span class="n">SessionMixin</span><span class="p">):</span> - <span class="k">pass</span> -</pre></div> -</div> -<p>If <a class="reference internal" href="#flask.sessions.SessionInterface.open_session" title="flask.sessions.SessionInterface.open_session"><tt class="xref py py-meth docutils literal"><span class="pre">open_session()</span></tt></a> returns <cite>None</cite> Flask will call into -<a class="reference internal" href="#flask.sessions.SessionInterface.make_null_session" title="flask.sessions.SessionInterface.make_null_session"><tt class="xref py py-meth docutils literal"><span class="pre">make_null_session()</span></tt></a> to create a session that acts as replacement -if the session support cannot work because some requirement is not -fulfilled. The default <a class="reference internal" href="#flask.sessions.NullSession" title="flask.sessions.NullSession"><tt class="xref py py-class docutils literal"><span class="pre">NullSession</span></tt></a> class that is created -will complain that the secret key was not set.</p> -<p>To replace the session interface on an application all you have to do -is to assign <a class="reference internal" href="#flask.Flask.session_interface" title="flask.Flask.session_interface"><tt class="xref py py-attr docutils literal"><span class="pre">flask.Flask.session_interface</span></tt></a>:</p> -<div class="highlight-python"><div class="highlight"><pre><span class="n">app</span> <span class="o">=</span> <span class="n">Flask</span><span class="p">(</span><span class="n">__name__</span><span class="p">)</span> -<span class="n">app</span><span class="o">.</span><span class="n">session_interface</span> <span class="o">=</span> <span class="n">MySessionInterface</span><span class="p">()</span> -</pre></div> -</div> -<p class="versionadded"> -<span class="versionmodified">New in version 0.8.</span></p> -<dl class="method"> -<dt id="flask.sessions.SessionInterface.get_cookie_domain"> -<tt class="descname">get_cookie_domain</tt><big>(</big><em>app</em><big>)</big><a class="headerlink" href="#flask.sessions.SessionInterface.get_cookie_domain" title="Permalink to this definition">¶</a></dt> -<dd><p>Helpful helper method that returns the cookie domain that should -be used for the session cookie if session cookies are used.</p> -</dd></dl> - -<dl class="method"> -<dt id="flask.sessions.SessionInterface.get_cookie_httponly"> -<tt class="descname">get_cookie_httponly</tt><big>(</big><em>app</em><big>)</big><a class="headerlink" href="#flask.sessions.SessionInterface.get_cookie_httponly" title="Permalink to this definition">¶</a></dt> -<dd><p>Returns True if the session cookie should be httponly. This -currently just returns the value of the <tt class="docutils literal"><span class="pre">SESSION_COOKIE_HTTPONLY</span></tt> -config var.</p> -</dd></dl> - -<dl class="method"> -<dt id="flask.sessions.SessionInterface.get_cookie_path"> -<tt class="descname">get_cookie_path</tt><big>(</big><em>app</em><big>)</big><a class="headerlink" href="#flask.sessions.SessionInterface.get_cookie_path" title="Permalink to this definition">¶</a></dt> -<dd><p>Returns the path for which the cookie should be valid. The -default implementation uses the value from the SESSION_COOKIE_PATH`` -config var if it’s set, and falls back to <tt class="docutils literal"><span class="pre">APPLICATION_ROOT</span></tt> or -uses <tt class="docutils literal"><span class="pre">/</span></tt> if it’s <cite>None</cite>.</p> -</dd></dl> - -<dl class="method"> -<dt id="flask.sessions.SessionInterface.get_cookie_secure"> -<tt class="descname">get_cookie_secure</tt><big>(</big><em>app</em><big>)</big><a class="headerlink" href="#flask.sessions.SessionInterface.get_cookie_secure" title="Permalink to this definition">¶</a></dt> -<dd><p>Returns True if the cookie should be secure. This currently -just returns the value of the <tt class="docutils literal"><span class="pre">SESSION_COOKIE_SECURE</span></tt> setting.</p> -</dd></dl> - -<dl class="method"> -<dt id="flask.sessions.SessionInterface.get_expiration_time"> -<tt class="descname">get_expiration_time</tt><big>(</big><em>app</em>, <em>session</em><big>)</big><a class="headerlink" href="#flask.sessions.SessionInterface.get_expiration_time" title="Permalink to this definition">¶</a></dt> -<dd><p>A helper method that returns an expiration date for the session -or <cite>None</cite> if the session is linked to the browser session. The -default implementation returns now + the permanent session -lifetime configured on the application.</p> -</dd></dl> - -<dl class="method"> -<dt id="flask.sessions.SessionInterface.is_null_session"> -<tt class="descname">is_null_session</tt><big>(</big><em>obj</em><big>)</big><a class="headerlink" href="#flask.sessions.SessionInterface.is_null_session" title="Permalink to this definition">¶</a></dt> -<dd><p>Checks if a given object is a null session. Null sessions are -not asked to be saved.</p> -<p>This checks if the object is an instance of <a class="reference internal" href="#flask.sessions.SessionInterface.null_session_class" title="flask.sessions.SessionInterface.null_session_class"><tt class="xref py py-attr docutils literal"><span class="pre">null_session_class</span></tt></a> -by default.</p> -</dd></dl> - -<dl class="method"> -<dt id="flask.sessions.SessionInterface.make_null_session"> -<tt class="descname">make_null_session</tt><big>(</big><em>app</em><big>)</big><a class="headerlink" href="#flask.sessions.SessionInterface.make_null_session" title="Permalink to this definition">¶</a></dt> -<dd><p>Creates a null session which acts as a replacement object if the -real session support could not be loaded due to a configuration -error. This mainly aids the user experience because the job of the -null session is to still support lookup without complaining but -modifications are answered with a helpful error message of what -failed.</p> -<p>This creates an instance of <a class="reference internal" href="#flask.sessions.SessionInterface.null_session_class" title="flask.sessions.SessionInterface.null_session_class"><tt class="xref py py-attr docutils literal"><span class="pre">null_session_class</span></tt></a> by default.</p> -</dd></dl> - -<dl class="attribute"> -<dt id="flask.sessions.SessionInterface.null_session_class"> -<tt class="descname">null_session_class</tt><a class="headerlink" href="#flask.sessions.SessionInterface.null_session_class" title="Permalink to this definition">¶</a></dt> -<dd><p><a class="reference internal" href="#flask.sessions.SessionInterface.make_null_session" title="flask.sessions.SessionInterface.make_null_session"><tt class="xref py py-meth docutils literal"><span class="pre">make_null_session()</span></tt></a> will look here for the class that should -be created when a null session is requested. Likewise the -<a class="reference internal" href="#flask.sessions.SessionInterface.is_null_session" title="flask.sessions.SessionInterface.is_null_session"><tt class="xref py py-meth docutils literal"><span class="pre">is_null_session()</span></tt></a> method will perform a typecheck against -this type.</p> -<p>alias of <a class="reference internal" href="#flask.sessions.NullSession" title="flask.sessions.NullSession"><tt class="xref py py-class docutils literal"><span class="pre">NullSession</span></tt></a></p> -</dd></dl> - -<dl class="method"> -<dt id="flask.sessions.SessionInterface.open_session"> -<tt class="descname">open_session</tt><big>(</big><em>app</em>, <em>request</em><big>)</big><a class="headerlink" href="#flask.sessions.SessionInterface.open_session" title="Permalink to this definition">¶</a></dt> -<dd><p>This method has to be implemented and must either return <cite>None</cite> -in case the loading failed because of a configuration error or an -instance of a session object which implements a dictionary like -interface + the methods and attributes on <a class="reference internal" href="#flask.sessions.SessionMixin" title="flask.sessions.SessionMixin"><tt class="xref py py-class docutils literal"><span class="pre">SessionMixin</span></tt></a>.</p> -</dd></dl> - -<dl class="method"> -<dt id="flask.sessions.SessionInterface.save_session"> -<tt class="descname">save_session</tt><big>(</big><em>app</em>, <em>session</em>, <em>response</em><big>)</big><a class="headerlink" href="#flask.sessions.SessionInterface.save_session" title="Permalink to this definition">¶</a></dt> -<dd><p>This is called for actual sessions returned by <a class="reference internal" href="#flask.sessions.SessionInterface.open_session" title="flask.sessions.SessionInterface.open_session"><tt class="xref py py-meth docutils literal"><span class="pre">open_session()</span></tt></a> -at the end of the request. This is still called during a request -context so if you absolutely need access to the request you can do -that.</p> -</dd></dl> - -</dd></dl> - -<dl class="class"> -<dt id="flask.sessions.SecureCookieSessionInterface"> -<em class="property">class </em><tt class="descclassname">flask.sessions.</tt><tt class="descname">SecureCookieSessionInterface</tt><a class="headerlink" href="#flask.sessions.SecureCookieSessionInterface" title="Permalink to this definition">¶</a></dt> -<dd><p>The cookie session interface that uses the Werkzeug securecookie -as client side session backend.</p> -<dl class="attribute"> -<dt id="flask.sessions.SecureCookieSessionInterface.session_class"> -<tt class="descname">session_class</tt><a class="headerlink" href="#flask.sessions.SecureCookieSessionInterface.session_class" title="Permalink to this definition">¶</a></dt> -<dd><p>alias of <tt class="xref py py-class docutils literal"><span class="pre">SecureCookieSession</span></tt></p> -</dd></dl> - -</dd></dl> - -<dl class="class"> -<dt id="flask.sessions.NullSession"> -<em class="property">class </em><tt class="descclassname">flask.sessions.</tt><tt class="descname">NullSession</tt><big>(</big><em>data=None</em>, <em>secret_key=None</em>, <em>new=True</em><big>)</big><a class="headerlink" href="#flask.sessions.NullSession" title="Permalink to this definition">¶</a></dt> -<dd><p>Class used to generate nicer error messages if sessions are not -available. Will still allow read-only access to the empty session -but fail on setting.</p> -</dd></dl> - -<dl class="class"> -<dt id="flask.sessions.SessionMixin"> -<em class="property">class </em><tt class="descclassname">flask.sessions.</tt><tt class="descname">SessionMixin</tt><a class="headerlink" href="#flask.sessions.SessionMixin" title="Permalink to this definition">¶</a></dt> -<dd><p>Expands a basic dictionary with an accessors that are expected -by Flask extensions and users for the session.</p> -<dl class="attribute"> -<dt id="flask.sessions.SessionMixin.modified"> -<tt class="descname">modified</tt><em class="property"> = True</em><a class="headerlink" href="#flask.sessions.SessionMixin.modified" title="Permalink to this definition">¶</a></dt> -<dd><p>for some backends this will always be <cite>True</cite>, but some backends will -default this to false and detect changes in the dictionary for as -long as changes do not happen on mutable structures in the session. -The default mixin implementation just hardcodes <cite>True</cite> in.</p> -</dd></dl> - -<dl class="attribute"> -<dt id="flask.sessions.SessionMixin.new"> -<tt class="descname">new</tt><em class="property"> = False</em><a class="headerlink" href="#flask.sessions.SessionMixin.new" title="Permalink to this definition">¶</a></dt> -<dd><p>some session backends can tell you if a session is new, but that is -not necessarily guaranteed. Use with caution. The default mixin -implementation just hardcodes <cite>False</cite> in.</p> -</dd></dl> - -<dl class="attribute"> -<dt id="flask.sessions.SessionMixin.permanent"> -<tt class="descname">permanent</tt><a class="headerlink" href="#flask.sessions.SessionMixin.permanent" title="Permalink to this definition">¶</a></dt> -<dd><p>this reflects the <tt class="docutils literal"><span class="pre">'_permanent'</span></tt> key in the dict.</p> -</dd></dl> - -</dd></dl> - -<div class="admonition-notice admonition "> -<p class="first admonition-title">Notice</p> -<p class="last">The <tt class="docutils literal"><span class="pre">PERMANENT_SESSION_LIFETIME</span></tt> config key can also be an integer -starting with Flask 0.8. Either catch this down yourself or use -the <a class="reference internal" href="#flask.Flask.permanent_session_lifetime" title="flask.Flask.permanent_session_lifetime"><tt class="xref py py-attr docutils literal"><span class="pre">permanent_session_lifetime</span></tt></a> attribute on the -app which converts the result to an integer automatically.</p> -</div> -</div> -<div class="section" id="test-client"> -<h2>Test Client<a class="headerlink" href="#test-client" title="Permalink to this headline">¶</a></h2> -<dl class="class"> -<dt id="flask.testing.FlaskClient"> -<em class="property">class </em><tt class="descclassname">flask.testing.</tt><tt class="descname">FlaskClient</tt><big>(</big><em>application</em>, <em>response_wrapper=None</em>, <em>use_cookies=True</em>, <em>allow_subdomain_redirects=False</em><big>)</big><a class="headerlink" href="#flask.testing.FlaskClient" title="Permalink to this definition">¶</a></dt> -<dd><p>Works like a regular Werkzeug test client but has some knowledge about -how Flask works to defer the cleanup of the request context stack to the -end of a with body when used in a with statement. For general information -about how to use this class refer to <a class="reference external" href="http://werkzeug.pocoo.org/docs/test/#werkzeug.test.Client" title="(in Werkzeug v0.7)"><tt class="xref py py-class docutils literal"><span class="pre">werkzeug.test.Client</span></tt></a>.</p> -<p>Basic usage is outlined in the <a class="reference internal" href="testing.html#testing"><em>Testing Flask Applications</em></a> chapter.</p> -<dl class="method"> -<dt id="flask.testing.FlaskClient.session_transaction"> -<tt class="descname">session_transaction</tt><big>(</big><em>*args</em>, <em>**kwds</em><big>)</big><a class="headerlink" href="#flask.testing.FlaskClient.session_transaction" title="Permalink to this definition">¶</a></dt> -<dd><p>When used in combination with a with statement this opens a -session transaction. This can be used to modify the session that -the test client uses. Once the with block is left the session is -stored back.</p> -<blockquote> -<div><dl class="docutils"> -<dt>with client.session_transaction() as session:</dt> -<dd>session[‘value’] = 42</dd> -</dl> -</div></blockquote> -<p>Internally this is implemented by going through a temporary test -request context and since session handling could depend on -request variables this function accepts the same arguments as -<a class="reference internal" href="#flask.Flask.test_request_context" title="flask.Flask.test_request_context"><tt class="xref py py-meth docutils literal"><span class="pre">test_request_context()</span></tt></a> which are directly -passed through.</p> -</dd></dl> - -</dd></dl> - -</div> -<div class="section" id="application-globals"> -<h2>Application Globals<a class="headerlink" href="#application-globals" title="Permalink to this headline">¶</a></h2> -<p>To share data that is valid for one request only from one function to -another, a global variable is not good enough because it would break in -threaded environments. Flask provides you with a special object that -ensures it is only valid for the active request and that will return -different values for each request. In a nutshell: it does the right -thing, like it does for <a class="reference internal" href="#flask.request" title="flask.request"><tt class="xref py py-class docutils literal"><span class="pre">request</span></tt></a> and <a class="reference internal" href="#flask.session" title="flask.session"><tt class="xref py py-class docutils literal"><span class="pre">session</span></tt></a>.</p> -<dl class="data"> -<dt id="flask.g"> -<tt class="descclassname">flask.</tt><tt class="descname">g</tt><a class="headerlink" href="#flask.g" title="Permalink to this definition">¶</a></dt> -<dd><p>Just store on this whatever you want. For example a database -connection or the user that is currently logged in.</p> -<p>This is a proxy. See <a class="reference internal" href="reqcontext.html#notes-on-proxies"><em>Notes On Proxies</em></a> for more information.</p> -</dd></dl> - -</div> -<div class="section" id="useful-functions-and-classes"> -<h2>Useful Functions and Classes<a class="headerlink" href="#useful-functions-and-classes" title="Permalink to this headline">¶</a></h2> -<dl class="data"> -<dt id="flask.current_app"> -<tt class="descclassname">flask.</tt><tt class="descname">current_app</tt><a class="headerlink" href="#flask.current_app" title="Permalink to this definition">¶</a></dt> -<dd><p>Points to the application handling the request. This is useful for -extensions that want to support multiple applications running side -by side.</p> -<p>This is a proxy. See <a class="reference internal" href="reqcontext.html#notes-on-proxies"><em>Notes On Proxies</em></a> for more information.</p> -</dd></dl> - -<dl class="function"> -<dt id="flask.has_request_context"> -<tt class="descclassname">flask.</tt><tt class="descname">has_request_context</tt><big>(</big><big>)</big><a class="headerlink" href="#flask.has_request_context" title="Permalink to this definition">¶</a></dt> -<dd><p>If you have code that wants to test if a request context is there or -not this function can be used. For instance if you want to take advantage -of request information is it’s available but fail silently if the request -object is unavailable.</p> -<div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">User</span><span class="p">(</span><span class="n">db</span><span class="o">.</span><span class="n">Model</span><span class="p">):</span> - - <span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">username</span><span class="p">,</span> <span class="n">remote_addr</span><span class="o">=</span><span class="bp">None</span><span class="p">):</span> - <span class="bp">self</span><span class="o">.</span><span class="n">username</span> <span class="o">=</span> <span class="n">username</span> - <span class="k">if</span> <span class="n">remote_addr</span> <span class="ow">is</span> <span class="bp">None</span> <span class="ow">and</span> <span class="n">has_request_context</span><span class="p">():</span> - <span class="n">remote_addr</span> <span class="o">=</span> <span class="n">request</span><span class="o">.</span><span class="n">remote_addr</span> - <span class="bp">self</span><span class="o">.</span><span class="n">remote_addr</span> <span class="o">=</span> <span class="n">remote_addr</span> -</pre></div> -</div> -<p>Alternatively you can also just test any of the context bound objects -(such as <a class="reference internal" href="#flask.request" title="flask.request"><tt class="xref py py-class docutils literal"><span class="pre">request</span></tt></a> or <a class="reference internal" href="#flask.g" title="flask.g"><tt class="xref py py-class docutils literal"><span class="pre">g</span></tt></a> for truthness):</p> -<div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">User</span><span class="p">(</span><span class="n">db</span><span class="o">.</span><span class="n">Model</span><span class="p">):</span> - - <span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">username</span><span class="p">,</span> <span class="n">remote_addr</span><span class="o">=</span><span class="bp">None</span><span class="p">):</span> - <span class="bp">self</span><span class="o">.</span><span class="n">username</span> <span class="o">=</span> <span class="n">username</span> - <span class="k">if</span> <span class="n">remote_addr</span> <span class="ow">is</span> <span class="bp">None</span> <span class="ow">and</span> <span class="n">request</span><span class="p">:</span> - <span class="n">remote_addr</span> <span class="o">=</span> <span class="n">request</span><span class="o">.</span><span class="n">remote_addr</span> - <span class="bp">self</span><span class="o">.</span><span class="n">remote_addr</span> <span class="o">=</span> <span class="n">remote_addr</span> -</pre></div> -</div> -<p class="versionadded"> -<span class="versionmodified">New in version 0.7.</span></p> -</dd></dl> - -<dl class="function"> -<dt id="flask.url_for"> -<tt class="descclassname">flask.</tt><tt class="descname">url_for</tt><big>(</big><em>endpoint</em>, <em>**values</em><big>)</big><a class="headerlink" href="#flask.url_for" title="Permalink to this definition">¶</a></dt> -<dd><p>Generates a URL to the given endpoint with the method provided.</p> -<p>Variable arguments that are unknown to the target endpoint are appended -to the generated URL as query arguments. If the value of a query argument -is <cite>None</cite>, the whole pair is skipped. In case blueprints are active -you can shortcut references to the same blueprint by prefixing the -local endpoint with a dot (<tt class="docutils literal"><span class="pre">.</span></tt>).</p> -<p>This will reference the index function local to the current blueprint:</p> -<div class="highlight-python"><div class="highlight"><pre><span class="n">url_for</span><span class="p">(</span><span class="s">'.index'</span><span class="p">)</span> -</pre></div> -</div> -<p>For more information, head over to the <a class="reference internal" href="quickstart.html#url-building"><em>Quickstart</em></a>.</p> -<table class="docutils field-list" frame="void" rules="none"> -<col class="field-name" /> -<col class="field-body" /> -<tbody valign="top"> -<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple"> -<li><strong>endpoint</strong> – the endpoint of the URL (name of the function)</li> -<li><strong>values</strong> – the variable arguments of the URL rule</li> -<li><strong>_external</strong> – if set to <cite>True</cite>, an absolute URL is generated.</li> -</ul> -</td> -</tr> -</tbody> -</table> -</dd></dl> - -<dl class="function"> -<dt id="flask.abort"> -<tt class="descclassname">flask.</tt><tt class="descname">abort</tt><big>(</big><em>code</em><big>)</big><a class="headerlink" href="#flask.abort" title="Permalink to this definition">¶</a></dt> -<dd><p>Raises an <a class="reference external" href="http://werkzeug.pocoo.org/docs/exceptions/#werkzeug.exceptions.HTTPException" title="(in Werkzeug v0.7)"><tt class="xref py py-exc docutils literal"><span class="pre">HTTPException</span></tt></a> for the given -status code. For example to abort request handling with a page not -found exception, you would call <tt class="docutils literal"><span class="pre">abort(404)</span></tt>.</p> -<table class="docutils field-list" frame="void" rules="none"> -<col class="field-name" /> -<col class="field-body" /> -<tbody valign="top"> -<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>code</strong> – the HTTP error code.</td> -</tr> -</tbody> -</table> -</dd></dl> - -<dl class="function"> -<dt id="flask.redirect"> -<tt class="descclassname">flask.</tt><tt class="descname">redirect</tt><big>(</big><em>location</em>, <em>code=302</em><big>)</big><a class="headerlink" href="#flask.redirect" title="Permalink to this definition">¶</a></dt> -<dd><p>Return a response object (a WSGI application) that, if called, -redirects the client to the target location. Supported codes are 301, -302, 303, 305, and 307. 300 is not supported because it’s not a real -redirect and 304 because it’s the answer for a request with a request -with defined If-Modified-Since headers.</p> -<p class="versionadded"> -<span class="versionmodified">New in version 0.6: </span>The location can now be a unicode string that is encoded using -the <tt class="xref py py-func docutils literal"><span class="pre">iri_to_uri()</span></tt> function.</p> -<table class="docutils field-list" frame="void" rules="none"> -<col class="field-name" /> -<col class="field-body" /> -<tbody valign="top"> -<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple"> -<li><strong>location</strong> – the location the response should redirect to.</li> -<li><strong>code</strong> – the redirect status code. defaults to 302.</li> -</ul> -</td> -</tr> -</tbody> -</table> -</dd></dl> - -<dl class="function"> -<dt id="flask.make_response"> -<tt class="descclassname">flask.</tt><tt class="descname">make_response</tt><big>(</big><em>*args</em><big>)</big><a class="headerlink" href="#flask.make_response" title="Permalink to this definition">¶</a></dt> -<dd><p>Sometimes it is necessary to set additional headers in a view. Because -views do not have to return response objects but can return a value that -is converted into a response object by Flask itself, it becomes tricky to -add headers to it. This function can be called instead of using a return -and you will get a response object which you can use to attach headers.</p> -<p>If view looked like this and you want to add a new header:</p> -<div class="highlight-python"><div class="highlight"><pre><span class="k">def</span> <span class="nf">index</span><span class="p">():</span> - <span class="k">return</span> <span class="n">render_template</span><span class="p">(</span><span class="s">'index.html'</span><span class="p">,</span> <span class="n">foo</span><span class="o">=</span><span class="mi">42</span><span class="p">)</span> -</pre></div> -</div> -<p>You can now do something like this:</p> -<div class="highlight-python"><div class="highlight"><pre><span class="k">def</span> <span class="nf">index</span><span class="p">():</span> - <span class="n">response</span> <span class="o">=</span> <span class="n">make_response</span><span class="p">(</span><span class="n">render_template</span><span class="p">(</span><span class="s">'index.html'</span><span class="p">,</span> <span class="n">foo</span><span class="o">=</span><span class="mi">42</span><span class="p">))</span> - <span class="n">response</span><span class="o">.</span><span class="n">headers</span><span class="p">[</span><span class="s">'X-Parachutes'</span><span class="p">]</span> <span class="o">=</span> <span class="s">'parachutes are cool'</span> - <span class="k">return</span> <span class="n">response</span> -</pre></div> -</div> -<p>This function accepts the very same arguments you can return from a -view function. This for example creates a response with a 404 error -code:</p> -<div class="highlight-python"><div class="highlight"><pre><span class="n">response</span> <span class="o">=</span> <span class="n">make_response</span><span class="p">(</span><span class="n">render_template</span><span class="p">(</span><span class="s">'not_found.html'</span><span class="p">),</span> <span class="mi">404</span><span class="p">)</span> -</pre></div> -</div> -<p>The other use case of this function is to force the return value of a -view function into a response which is helpful with view -decorators:</p> -<div class="highlight-python"><div class="highlight"><pre><span class="n">response</span> <span class="o">=</span> <span class="n">make_response</span><span class="p">(</span><span class="n">view_function</span><span class="p">())</span> -<span class="n">response</span><span class="o">.</span><span class="n">headers</span><span class="p">[</span><span class="s">'X-Parachutes'</span><span class="p">]</span> <span class="o">=</span> <span class="s">'parachutes are cool'</span> -</pre></div> -</div> -<p>Internally this function does the following things:</p> -<ul class="simple"> -<li>if no arguments are passed, it creates a new response argument</li> -<li>if one argument is passed, <a class="reference internal" href="#flask.Flask.make_response" title="flask.Flask.make_response"><tt class="xref py py-meth docutils literal"><span class="pre">flask.Flask.make_response()</span></tt></a> -is invoked with it.</li> -<li>if more than one argument is passed, the arguments are passed -to the <a class="reference internal" href="#flask.Flask.make_response" title="flask.Flask.make_response"><tt class="xref py py-meth docutils literal"><span class="pre">flask.Flask.make_response()</span></tt></a> function as tuple.</li> -</ul> -<p class="versionadded"> -<span class="versionmodified">New in version 0.6.</span></p> -</dd></dl> - -<dl class="function"> -<dt id="flask.send_file"> -<tt class="descclassname">flask.</tt><tt class="descname">send_file</tt><big>(</big><em>filename_or_fp</em>, <em>mimetype=None</em>, <em>as_attachment=False</em>, <em>attachment_filename=None</em>, <em>add_etags=True</em>, <em>cache_timeout=43200</em>, <em>conditional=False</em><big>)</big><a class="headerlink" href="#flask.send_file" title="Permalink to this definition">¶</a></dt> -<dd><p>Sends the contents of a file to the client. This will use the -most efficient method available and configured. By default it will -try to use the WSGI server’s file_wrapper support. Alternatively -you can set the application’s <a class="reference internal" href="#flask.Flask.use_x_sendfile" title="flask.Flask.use_x_sendfile"><tt class="xref py py-attr docutils literal"><span class="pre">use_x_sendfile</span></tt></a> attribute -to <tt class="docutils literal"><span class="pre">True</span></tt> to directly emit an <cite>X-Sendfile</cite> header. This however -requires support of the underlying webserver for <cite>X-Sendfile</cite>.</p> -<p>By default it will try to guess the mimetype for you, but you can -also explicitly provide one. For extra security you probably want -to send certain files as attachment (HTML for instance). The mimetype -guessing requires a <cite>filename</cite> or an <cite>attachment_filename</cite> to be -provided.</p> -<p>Please never pass filenames to this function from user sources without -checking them first. Something like this is usually sufficient to -avoid security problems:</p> -<div class="highlight-python"><div class="highlight"><pre><span class="k">if</span> <span class="s">'..'</span> <span class="ow">in</span> <span class="n">filename</span> <span class="ow">or</span> <span class="n">filename</span><span class="o">.</span><span class="n">startswith</span><span class="p">(</span><span class="s">'/'</span><span class="p">):</span> - <span class="n">abort</span><span class="p">(</span><span class="mi">404</span><span class="p">)</span> -</pre></div> -</div> -<p class="versionadded"> -<span class="versionmodified">New in version 0.2.</span></p> -<p class="versionadded"> -<span class="versionmodified">New in version 0.5: </span>The <cite>add_etags</cite>, <cite>cache_timeout</cite> and <cite>conditional</cite> parameters were -added. The default behaviour is now to attach etags.</p> -<p class="versionchanged"> -<span class="versionmodified">Changed in version 0.7: </span>mimetype guessing and etag support for file objects was -deprecated because it was unreliable. Pass a filename if you are -able to, otherwise attach an etag yourself. This functionality -will be removed in Flask 1.0</p> -<table class="docutils field-list" frame="void" rules="none"> -<col class="field-name" /> -<col class="field-body" /> -<tbody valign="top"> -<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple"> -<li><strong>filename_or_fp</strong> – the filename of the file to send. This is -relative to the <tt class="xref py py-attr docutils literal"><span class="pre">root_path</span></tt> if a -relative path is specified. -Alternatively a file object might be provided -in which case <cite>X-Sendfile</cite> might not work and -fall back to the traditional method. Make sure -that the file pointer is positioned at the start -of data to send before calling <a class="reference internal" href="#flask.send_file" title="flask.send_file"><tt class="xref py py-func docutils literal"><span class="pre">send_file()</span></tt></a>.</li> -<li><strong>mimetype</strong> – the mimetype of the file if provided, otherwise -auto detection happens.</li> -<li><strong>as_attachment</strong> – set to <cite>True</cite> if you want to send this file with -a <tt class="docutils literal"><span class="pre">Content-Disposition:</span> <span class="pre">attachment</span></tt> header.</li> -<li><strong>attachment_filename</strong> – the filename for the attachment if it -differs from the file’s filename.</li> -<li><strong>add_etags</strong> – set to <cite>False</cite> to disable attaching of etags.</li> -<li><strong>conditional</strong> – set to <cite>True</cite> to enable conditional responses.</li> -<li><strong>cache_timeout</strong> – the timeout in seconds for the headers.</li> -</ul> -</td> -</tr> -</tbody> -</table> -</dd></dl> - -<dl class="function"> -<dt id="flask.send_from_directory"> -<tt class="descclassname">flask.</tt><tt class="descname">send_from_directory</tt><big>(</big><em>directory</em>, <em>filename</em>, <em>**options</em><big>)</big><a class="headerlink" href="#flask.send_from_directory" title="Permalink to this definition">¶</a></dt> -<dd><p>Send a file from a given directory with <a class="reference internal" href="#flask.send_file" title="flask.send_file"><tt class="xref py py-func docutils literal"><span class="pre">send_file()</span></tt></a>. This -is a secure way to quickly expose static files from an upload folder -or something similar.</p> -<p>Example usage:</p> -<div class="highlight-python"><div class="highlight"><pre><span class="nd">@app.route</span><span class="p">(</span><span class="s">'/uploads/<path:filename>'</span><span class="p">)</span> -<span class="k">def</span> <span class="nf">download_file</span><span class="p">(</span><span class="n">filename</span><span class="p">):</span> - <span class="k">return</span> <span class="n">send_from_directory</span><span class="p">(</span><span class="n">app</span><span class="o">.</span><span class="n">config</span><span class="p">[</span><span class="s">'UPLOAD_FOLDER'</span><span class="p">],</span> - <span class="n">filename</span><span class="p">,</span> <span class="n">as_attachment</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span> -</pre></div> -</div> -<div class="admonition-sending-files-and-performance admonition "> -<p class="first admonition-title">Sending files and Performance</p> -<p class="last">It is strongly recommended to activate either <cite>X-Sendfile</cite> support in -your webserver or (if no authentication happens) to tell the webserver -to serve files for the given path on its own without calling into the -web application for improved performance.</p> -</div> -<p class="versionadded"> -<span class="versionmodified">New in version 0.5.</span></p> -<table class="docutils field-list" frame="void" rules="none"> -<col class="field-name" /> -<col class="field-body" /> -<tbody valign="top"> -<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple"> -<li><strong>directory</strong> – the directory where all the files are stored.</li> -<li><strong>filename</strong> – the filename relative to that directory to -download.</li> -<li><strong>options</strong> – optional keyword arguments that are directly -forwarded to <a class="reference internal" href="#flask.send_file" title="flask.send_file"><tt class="xref py py-func docutils literal"><span class="pre">send_file()</span></tt></a>.</li> -</ul> -</td> -</tr> -</tbody> -</table> -</dd></dl> - -<dl class="function"> -<dt id="flask.safe_join"> -<tt class="descclassname">flask.</tt><tt class="descname">safe_join</tt><big>(</big><em>directory</em>, <em>filename</em><big>)</big><a class="headerlink" href="#flask.safe_join" title="Permalink to this definition">¶</a></dt> -<dd><p>Safely join <cite>directory</cite> and <cite>filename</cite>.</p> -<p>Example usage:</p> -<div class="highlight-python"><div class="highlight"><pre><span class="nd">@app.route</span><span class="p">(</span><span class="s">'/wiki/<path:filename>'</span><span class="p">)</span> -<span class="k">def</span> <span class="nf">wiki_page</span><span class="p">(</span><span class="n">filename</span><span class="p">):</span> - <span class="n">filename</span> <span class="o">=</span> <span class="n">safe_join</span><span class="p">(</span><span class="n">app</span><span class="o">.</span><span class="n">config</span><span class="p">[</span><span class="s">'WIKI_FOLDER'</span><span class="p">],</span> <span class="n">filename</span><span class="p">)</span> - <span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="n">filename</span><span class="p">,</span> <span class="s">'rb'</span><span class="p">)</span> <span class="k">as</span> <span class="n">fd</span><span class="p">:</span> - <span class="n">content</span> <span class="o">=</span> <span class="n">fd</span><span class="o">.</span><span class="n">read</span><span class="p">()</span> <span class="c"># Read and process the file content...</span> -</pre></div> -</div> -<table class="docutils field-list" frame="void" rules="none"> -<col class="field-name" /> -<col class="field-body" /> -<tbody valign="top"> -<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> -<li><strong>directory</strong> – the base directory.</li> -<li><strong>filename</strong> – the untrusted filename relative to that directory.</li> -</ul> -</td> -</tr> -<tr class="field-even field"><th class="field-name">Raises :</th><td class="field-body"><p class="first last"><tt class="xref py py-class docutils literal"><span class="pre">NotFound</span></tt> if the resulting path -would fall out of <cite>directory</cite>.</p> -</td> -</tr> -</tbody> -</table> -</dd></dl> - -<dl class="function"> -<dt id="flask.escape"> -<tt class="descclassname">flask.</tt><tt class="descname">escape</tt><big>(</big><em>s</em><big>)</big> → markup<a class="headerlink" href="#flask.escape" title="Permalink to this definition">¶</a></dt> -<dd><p>Convert the characters &, <, >, ‘, and ” in string s to HTML-safe -sequences. Use this if you need to display text that might contain -such characters in HTML. Marks return value as markup string.</p> -</dd></dl> - -<dl class="class"> -<dt id="flask.Markup"> -<em class="property">class </em><tt class="descclassname">flask.</tt><tt class="descname">Markup</tt><a class="headerlink" href="#flask.Markup" title="Permalink to this definition">¶</a></dt> -<dd><p>Marks a string as being safe for inclusion in HTML/XML output without -needing to be escaped. This implements the <cite>__html__</cite> interface a couple -of frameworks and web applications use. <a class="reference internal" href="#flask.Markup" title="flask.Markup"><tt class="xref py py-class docutils literal"><span class="pre">Markup</span></tt></a> is a direct -subclass of <cite>unicode</cite> and provides all the methods of <cite>unicode</cite> just that -it escapes arguments passed and always returns <cite>Markup</cite>.</p> -<p>The <cite>escape</cite> function returns markup objects so that double escaping can’t -happen.</p> -<p>The constructor of the <a class="reference internal" href="#flask.Markup" title="flask.Markup"><tt class="xref py py-class docutils literal"><span class="pre">Markup</span></tt></a> class can be used for three -different things: When passed an unicode object it’s assumed to be safe, -when passed an object with an HTML representation (has an <cite>__html__</cite> -method) that representation is used, otherwise the object passed is -converted into a unicode string and then assumed to be safe:</p> -<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">Markup</span><span class="p">(</span><span class="s">"Hello <em>World</em>!"</span><span class="p">)</span> -<span class="go">Markup(u'Hello <em>World</em>!')</span> -<span class="gp">>>> </span><span class="k">class</span> <span class="nc">Foo</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span> -<span class="gp">... </span> <span class="k">def</span> <span class="nf">__html__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> -<span class="gp">... </span> <span class="k">return</span> <span class="s">'<a href="#">foo</a>'</span> -<span class="gp">... </span> -<span class="gp">>>> </span><span class="n">Markup</span><span class="p">(</span><span class="n">Foo</span><span class="p">())</span> -<span class="go">Markup(u'<a href="#">foo</a>')</span> -</pre></div> -</div> -<p>If you want object passed being always treated as unsafe you can use the -<a class="reference internal" href="#flask.escape" title="flask.escape"><tt class="xref py py-meth docutils literal"><span class="pre">escape()</span></tt></a> classmethod to create a <a class="reference internal" href="#flask.Markup" title="flask.Markup"><tt class="xref py py-class docutils literal"><span class="pre">Markup</span></tt></a> object:</p> -<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">Markup</span><span class="o">.</span><span class="n">escape</span><span class="p">(</span><span class="s">"Hello <em>World</em>!"</span><span class="p">)</span> -<span class="go">Markup(u'Hello &lt;em&gt;World&lt;/em&gt;!')</span> -</pre></div> -</div> -<p>Operations on a markup string are markup aware which means that all -arguments are passed through the <a class="reference internal" href="#flask.escape" title="flask.escape"><tt class="xref py py-func docutils literal"><span class="pre">escape()</span></tt></a> function:</p> -<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">em</span> <span class="o">=</span> <span class="n">Markup</span><span class="p">(</span><span class="s">"<em></span><span class="si">%s</span><span class="s"></em>"</span><span class="p">)</span> -<span class="gp">>>> </span><span class="n">em</span> <span class="o">%</span> <span class="s">"foo & bar"</span> -<span class="go">Markup(u'<em>foo &amp; bar</em>')</span> -<span class="gp">>>> </span><span class="n">strong</span> <span class="o">=</span> <span class="n">Markup</span><span class="p">(</span><span class="s">"<strong></span><span class="si">%(text)s</span><span class="s"></strong>"</span><span class="p">)</span> -<span class="gp">>>> </span><span class="n">strong</span> <span class="o">%</span> <span class="p">{</span><span class="s">'text'</span><span class="p">:</span> <span class="s">'<blink>hacker here</blink>'</span><span class="p">}</span> -<span class="go">Markup(u'<strong>&lt;blink&gt;hacker here&lt;/blink&gt;</strong>')</span> -<span class="gp">>>> </span><span class="n">Markup</span><span class="p">(</span><span class="s">"<em>Hello</em> "</span><span class="p">)</span> <span class="o">+</span> <span class="s">"<foo>"</span> -<span class="go">Markup(u'<em>Hello</em> &lt;foo&gt;')</span> -</pre></div> -</div> -<dl class="classmethod"> -<dt id="flask.Markup.escape"> -<em class="property">classmethod </em><tt class="descname">escape</tt><big>(</big><em>s</em><big>)</big><a class="headerlink" href="#flask.Markup.escape" title="Permalink to this definition">¶</a></dt> -<dd><p>Escape the string. Works like <a class="reference internal" href="#flask.escape" title="flask.escape"><tt class="xref py py-func docutils literal"><span class="pre">escape()</span></tt></a> with the difference -that for subclasses of <a class="reference internal" href="#flask.Markup" title="flask.Markup"><tt class="xref py py-class docutils literal"><span class="pre">Markup</span></tt></a> this function would return the -correct subclass.</p> -</dd></dl> - -<dl class="method"> -<dt id="flask.Markup.unescape"> -<tt class="descname">unescape</tt><big>(</big><big>)</big><a class="headerlink" href="#flask.Markup.unescape" title="Permalink to this definition">¶</a></dt> -<dd><p>Unescape markup again into an unicode string. This also resolves -known HTML4 and XHTML entities:</p> -<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">Markup</span><span class="p">(</span><span class="s">"Main &raquo; <em>About</em>"</span><span class="p">)</span><span class="o">.</span><span class="n">unescape</span><span class="p">()</span> -<span class="go">u'Main \xbb <em>About</em>'</span> -</pre></div> -</div> -</dd></dl> - -<dl class="method"> -<dt id="flask.Markup.striptags"> -<tt class="descname">striptags</tt><big>(</big><big>)</big><a class="headerlink" href="#flask.Markup.striptags" title="Permalink to this definition">¶</a></dt> -<dd><p>Unescape markup into an unicode string and strip all tags. This -also resolves known HTML4 and XHTML entities. Whitespace is -normalized to one:</p> -<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">Markup</span><span class="p">(</span><span class="s">"Main &raquo; <em>About</em>"</span><span class="p">)</span><span class="o">.</span><span class="n">striptags</span><span class="p">()</span> -<span class="go">u'Main \xbb About'</span> -</pre></div> -</div> -</dd></dl> - -</dd></dl> - -</div> -<div class="section" id="message-flashing"> -<h2>Message Flashing<a class="headerlink" href="#message-flashing" title="Permalink to this headline">¶</a></h2> -<dl class="function"> -<dt id="flask.flash"> -<tt class="descclassname">flask.</tt><tt class="descname">flash</tt><big>(</big><em>message</em>, <em>category='message'</em><big>)</big><a class="headerlink" href="#flask.flash" title="Permalink to this definition">¶</a></dt> -<dd><p>Flashes a message to the next request. In order to remove the -flashed message from the session and to display it to the user, -the template has to call <a class="reference internal" href="#flask.get_flashed_messages" title="flask.get_flashed_messages"><tt class="xref py py-func docutils literal"><span class="pre">get_flashed_messages()</span></tt></a>.</p> -<table class="docutils field-list" frame="void" rules="none"> -<col class="field-name" /> -<col class="field-body" /> -<tbody valign="top"> -<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple"> -<li><strong>message</strong> – the message to be flashed.</li> -<li><strong>category</strong> – the category for the message. The following values -are recommended: <tt class="docutils literal"><span class="pre">'message'</span></tt> for any kind of message, -<tt class="docutils literal"><span class="pre">'error'</span></tt> for errors, <tt class="docutils literal"><span class="pre">'info'</span></tt> for information -messages and <tt class="docutils literal"><span class="pre">'warning'</span></tt> for warnings. However any -kind of string can be used as category.</li> -</ul> -</td> -</tr> -</tbody> -</table> -</dd></dl> - -<dl class="function"> -<dt id="flask.get_flashed_messages"> -<tt class="descclassname">flask.</tt><tt class="descname">get_flashed_messages</tt><big>(</big><em>with_categories=False</em><big>)</big><a class="headerlink" href="#flask.get_flashed_messages" title="Permalink to this definition">¶</a></dt> -<dd><p>Pulls all flashed messages from the session and returns them. -Further calls in the same request to the function will return -the same messages. By default just the messages are returned, -but when <cite>with_categories</cite> is set to <cite>True</cite>, the return value will -be a list of tuples in the form <tt class="docutils literal"><span class="pre">(category,</span> <span class="pre">message)</span></tt> instead.</p> -<p>Example usage:</p> -<div class="highlight-html+jinja"><div class="highlight"><pre><span class="cp">{%</span> <span class="k">for</span> <span class="nv">category</span><span class="o">,</span> <span class="nv">msg</span> <span class="k">in</span> <span class="nv">get_flashed_messages</span><span class="o">(</span><span class="nv">with_categories</span><span class="o">=</span><span class="kp">true</span><span class="o">)</span> <span class="cp">%}</span> - <span class="nt"><p</span> <span class="na">class=</span><span class="s">flash-</span><span class="cp">{{</span> <span class="nv">category</span> <span class="cp">}}</span><span class="nt">></span><span class="cp">{{</span> <span class="nv">msg</span> <span class="cp">}}</span> -<span class="cp">{%</span> <span class="k">endfor</span> <span class="cp">%}</span> -</pre></div> -</div> -<p class="versionchanged"> -<span class="versionmodified">Changed in version 0.3: </span><cite>with_categories</cite> parameter added.</p> -<table class="docutils field-list" frame="void" rules="none"> -<col class="field-name" /> -<col class="field-body" /> -<tbody valign="top"> -<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>with_categories</strong> – set to <cite>True</cite> to also receive categories.</td> -</tr> -</tbody> -</table> -</dd></dl> - -</div> -<div class="section" id="returning-json"> -<h2>Returning JSON<a class="headerlink" href="#returning-json" title="Permalink to this headline">¶</a></h2> -<dl class="function"> -<dt id="flask.jsonify"> -<tt class="descclassname">flask.</tt><tt class="descname">jsonify</tt><big>(</big><em>*args</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#flask.jsonify" title="Permalink to this definition">¶</a></dt> -<dd><p>Creates a <a class="reference internal" href="#flask.Response" title="flask.Response"><tt class="xref py py-class docutils literal"><span class="pre">Response</span></tt></a> with the JSON representation of -the given arguments with an <cite>application/json</cite> mimetype. The arguments -to this function are the same as to the <a class="reference external" href="http://docs.python.org/dev/library/stdtypes.html#dict" title="(in Python v3.3)"><tt class="xref py py-class docutils literal"><span class="pre">dict</span></tt></a> constructor.</p> -<p>Example usage:</p> -<div class="highlight-python"><div class="highlight"><pre><span class="nd">@app.route</span><span class="p">(</span><span class="s">'/_get_current_user'</span><span class="p">)</span> -<span class="k">def</span> <span class="nf">get_current_user</span><span class="p">():</span> - <span class="k">return</span> <span class="n">jsonify</span><span class="p">(</span><span class="n">username</span><span class="o">=</span><span class="n">g</span><span class="o">.</span><span class="n">user</span><span class="o">.</span><span class="n">username</span><span class="p">,</span> - <span class="n">email</span><span class="o">=</span><span class="n">g</span><span class="o">.</span><span class="n">user</span><span class="o">.</span><span class="n">email</span><span class="p">,</span> - <span class="nb">id</span><span class="o">=</span><span class="n">g</span><span class="o">.</span><span class="n">user</span><span class="o">.</span><span class="n">id</span><span class="p">)</span> -</pre></div> -</div> -<p>This will send a JSON response like this to the browser:</p> -<div class="highlight-python"><div class="highlight"><pre><span class="p">{</span> - <span class="s">"username"</span><span class="p">:</span> <span class="s">"admin"</span><span class="p">,</span> - <span class="s">"email"</span><span class="p">:</span> <span class="s">"admin@localhost"</span><span class="p">,</span> - <span class="s">"id"</span><span class="p">:</span> <span class="mi">42</span> -<span class="p">}</span> -</pre></div> -</div> -<p>This requires Python 2.6 or an installed version of simplejson. For -security reasons only objects are supported toplevel. For more -information about this, have a look at <a class="reference internal" href="security.html#json-security"><em>JSON Security</em></a>.</p> -<p class="versionadded"> -<span class="versionmodified">New in version 0.2.</span></p> -</dd></dl> - -<dl class="data"> -<dt id="flask.json"> -<tt class="descclassname">flask.</tt><tt class="descname">json</tt><a class="headerlink" href="#flask.json" title="Permalink to this definition">¶</a></dt> -<dd><p>If JSON support is picked up, this will be the module that Flask is -using to parse and serialize JSON. So instead of doing this yourself:</p> -<div class="highlight-python"><div class="highlight"><pre><span class="k">try</span><span class="p">:</span> - <span class="kn">import</span> <span class="nn">simplejson</span> <span class="kn">as</span> <span class="nn">json</span> -<span class="k">except</span> <span class="ne">ImportError</span><span class="p">:</span> - <span class="kn">import</span> <span class="nn">json</span> -</pre></div> -</div> -<p>You can instead just do this:</p> -<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">flask</span> <span class="kn">import</span> <span class="n">json</span> -</pre></div> -</div> -<p>For usage examples, read the <a class="reference external" href="http://docs.python.org/dev/library/json.html#json" title="(in Python v3.3)"><tt class="xref py py-mod docutils literal"><span class="pre">json</span></tt></a> documentation.</p> -<p>The <a class="reference external" href="http://docs.python.org/dev/library/json.html#json.dumps" title="(in Python v3.3)"><tt class="xref py py-func docutils literal"><span class="pre">dumps()</span></tt></a> function of this json module is also available -as filter called <tt class="docutils literal"><span class="pre">|tojson</span></tt> in Jinja2. Note that inside <cite>script</cite> -tags no escaping must take place, so make sure to disable escaping -with <tt class="docutils literal"><span class="pre">|safe</span></tt> if you intend to use it inside <cite>script</cite> tags:</p> -<div class="highlight-html+jinja"><div class="highlight"><pre><span class="nt"><script </span><span class="na">type=</span><span class="s">text/javascript</span><span class="nt">></span> - <span class="nx">doSomethingWith</span><span class="p">(</span><span class="cp">{{</span> <span class="nv">user.username</span><span class="o">|</span><span class="nf">tojson</span><span class="o">|</span><span class="nf">safe</span> <span class="cp">}}</span><span class="p">);</span> -<span class="nt"></script></span> -</pre></div> -</div> -<p>Note that the <tt class="docutils literal"><span class="pre">|tojson</span></tt> filter escapes forward slashes properly.</p> -</dd></dl> - -</div> -<div class="section" id="template-rendering"> -<h2>Template Rendering<a class="headerlink" href="#template-rendering" title="Permalink to this headline">¶</a></h2> -<dl class="function"> -<dt id="flask.render_template"> -<tt class="descclassname">flask.</tt><tt class="descname">render_template</tt><big>(</big><em>template_name</em>, <em>**context</em><big>)</big><a class="headerlink" href="#flask.render_template" title="Permalink to this definition">¶</a></dt> -<dd><p>Renders a template from the template folder with the given -context.</p> -<table class="docutils field-list" frame="void" rules="none"> -<col class="field-name" /> -<col class="field-body" /> -<tbody valign="top"> -<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple"> -<li><strong>template_name</strong> – the name of the template to be rendered</li> -<li><strong>context</strong> – the variables that should be available in the -context of the template.</li> -</ul> -</td> -</tr> -</tbody> -</table> -</dd></dl> - -<dl class="function"> -<dt id="flask.render_template_string"> -<tt class="descclassname">flask.</tt><tt class="descname">render_template_string</tt><big>(</big><em>source</em>, <em>**context</em><big>)</big><a class="headerlink" href="#flask.render_template_string" title="Permalink to this definition">¶</a></dt> -<dd><p>Renders a template from the given template source string -with the given context.</p> -<table class="docutils field-list" frame="void" rules="none"> -<col class="field-name" /> -<col class="field-body" /> -<tbody valign="top"> -<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple"> -<li><strong>template_name</strong> – the sourcecode of the template to be -rendered</li> -<li><strong>context</strong> – the variables that should be available in the -context of the template.</li> -</ul> -</td> -</tr> -</tbody> -</table> -</dd></dl> - -<dl class="function"> -<dt id="flask.get_template_attribute"> -<tt class="descclassname">flask.</tt><tt class="descname">get_template_attribute</tt><big>(</big><em>template_name</em>, <em>attribute</em><big>)</big><a class="headerlink" href="#flask.get_template_attribute" title="Permalink to this definition">¶</a></dt> -<dd><p>Loads a macro (or variable) a template exports. This can be used to -invoke a macro from within Python code. If you for example have a -template named <cite>_cider.html</cite> with the following contents:</p> -<div class="highlight-html+jinja"><div class="highlight"><pre><span class="cp">{%</span> <span class="k">macro</span> <span class="nv">hello</span><span class="o">(</span><span class="nv">name</span><span class="o">)</span> <span class="cp">%}</span>Hello <span class="cp">{{</span> <span class="nv">name</span> <span class="cp">}}</span>!<span class="cp">{%</span> <span class="k">endmacro</span> <span class="cp">%}</span> -</pre></div> -</div> -<p>You can access this from Python code like this:</p> -<div class="highlight-python"><div class="highlight"><pre><span class="n">hello</span> <span class="o">=</span> <span class="n">get_template_attribute</span><span class="p">(</span><span class="s">'_cider.html'</span><span class="p">,</span> <span class="s">'hello'</span><span class="p">)</span> -<span class="k">return</span> <span class="n">hello</span><span class="p">(</span><span class="s">'World'</span><span class="p">)</span> -</pre></div> -</div> -<p class="versionadded"> -<span class="versionmodified">New in version 0.2.</span></p> -<table class="docutils field-list" frame="void" rules="none"> -<col class="field-name" /> -<col class="field-body" /> -<tbody valign="top"> -<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple"> -<li><strong>template_name</strong> – the name of the template</li> -<li><strong>attribute</strong> – the name of the variable of macro to acccess</li> -</ul> -</td> -</tr> -</tbody> -</table> -</dd></dl> - -</div> -<div class="section" id="configuration"> -<h2>Configuration<a class="headerlink" href="#configuration" title="Permalink to this headline">¶</a></h2> -<dl class="class"> -<dt id="flask.Config"> -<em class="property">class </em><tt class="descclassname">flask.</tt><tt class="descname">Config</tt><big>(</big><em>root_path</em>, <em>defaults=None</em><big>)</big><a class="headerlink" href="#flask.Config" title="Permalink to this definition">¶</a></dt> -<dd><p>Works exactly like a dict but provides ways to fill it from files -or special dictionaries. There are two common patterns to populate the -config.</p> -<p>Either you can fill the config from a config file:</p> -<div class="highlight-python"><div class="highlight"><pre><span class="n">app</span><span class="o">.</span><span class="n">config</span><span class="o">.</span><span class="n">from_pyfile</span><span class="p">(</span><span class="s">'yourconfig.cfg'</span><span class="p">)</span> -</pre></div> -</div> -<p>Or alternatively you can define the configuration options in the -module that calls <a class="reference internal" href="#flask.Config.from_object" title="flask.Config.from_object"><tt class="xref py py-meth docutils literal"><span class="pre">from_object()</span></tt></a> or provide an import path to -a module that should be loaded. It is also possible to tell it to -use the same module and with that provide the configuration values -just before the call:</p> -<div class="highlight-python"><div class="highlight"><pre><span class="n">DEBUG</span> <span class="o">=</span> <span class="bp">True</span> -<span class="n">SECRET_KEY</span> <span class="o">=</span> <span class="s">'development key'</span> -<span class="n">app</span><span class="o">.</span><span class="n">config</span><span class="o">.</span><span class="n">from_object</span><span class="p">(</span><span class="n">__name__</span><span class="p">)</span> -</pre></div> -</div> -<p>In both cases (loading from any Python file or loading from modules), -only uppercase keys are added to the config. This makes it possible to use -lowercase values in the config file for temporary values that are not added -to the config or to define the config keys in the same file that implements -the application.</p> -<p>Probably the most interesting way to load configurations is from an -environment variable pointing to a file:</p> -<div class="highlight-python"><div class="highlight"><pre><span class="n">app</span><span class="o">.</span><span class="n">config</span><span class="o">.</span><span class="n">from_envvar</span><span class="p">(</span><span class="s">'YOURAPPLICATION_SETTINGS'</span><span class="p">)</span> -</pre></div> -</div> -<p>In this case before launching the application you have to set this -environment variable to the file you want to use. On Linux and OS X -use the export statement:</p> -<div class="highlight-python"><pre>export YOURAPPLICATION_SETTINGS='/path/to/config/file'</pre> -</div> -<p>On windows use <cite>set</cite> instead.</p> -<table class="docutils field-list" frame="void" rules="none"> -<col class="field-name" /> -<col class="field-body" /> -<tbody valign="top"> -<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple"> -<li><strong>root_path</strong> – path to which files are read relative from. When the -config object is created by the application, this is -the application’s <tt class="xref py py-attr docutils literal"><span class="pre">root_path</span></tt>.</li> -<li><strong>defaults</strong> – an optional dictionary of default values</li> -</ul> -</td> -</tr> -</tbody> -</table> -<dl class="method"> -<dt id="flask.Config.from_envvar"> -<tt class="descname">from_envvar</tt><big>(</big><em>variable_name</em>, <em>silent=False</em><big>)</big><a class="headerlink" href="#flask.Config.from_envvar" title="Permalink to this definition">¶</a></dt> -<dd><p>Loads a configuration from an environment variable pointing to -a configuration file. This is basically just a shortcut with nicer -error messages for this line of code:</p> -<div class="highlight-python"><div class="highlight"><pre><span class="n">app</span><span class="o">.</span><span class="n">config</span><span class="o">.</span><span class="n">from_pyfile</span><span class="p">(</span><span class="n">os</span><span class="o">.</span><span class="n">environ</span><span class="p">[</span><span class="s">'YOURAPPLICATION_SETTINGS'</span><span class="p">])</span> -</pre></div> -</div> -<table class="docutils field-list" frame="void" rules="none"> -<col class="field-name" /> -<col class="field-body" /> -<tbody valign="top"> -<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> -<li><strong>variable_name</strong> – name of the environment variable</li> -<li><strong>silent</strong> – set to <cite>True</cite> if you want silent failure for missing -files.</li> -</ul> -</td> -</tr> -<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">bool. <cite>True</cite> if able to load config, <cite>False</cite> otherwise.</p> -</td> -</tr> -</tbody> -</table> -</dd></dl> - -<dl class="method"> -<dt id="flask.Config.from_object"> -<tt class="descname">from_object</tt><big>(</big><em>obj</em><big>)</big><a class="headerlink" href="#flask.Config.from_object" title="Permalink to this definition">¶</a></dt> -<dd><p>Updates the values from the given object. An object can be of one -of the following two types:</p> -<ul class="simple"> -<li>a string: in this case the object with that name will be imported</li> -<li>an actual object reference: that object is used directly</li> -</ul> -<p>Objects are usually either modules or classes.</p> -<p>Just the uppercase variables in that object are stored in the config. -Example usage:</p> -<div class="highlight-python"><div class="highlight"><pre><span class="n">app</span><span class="o">.</span><span class="n">config</span><span class="o">.</span><span class="n">from_object</span><span class="p">(</span><span class="s">'yourapplication.default_config'</span><span class="p">)</span> -<span class="kn">from</span> <span class="nn">yourapplication</span> <span class="kn">import</span> <span class="n">default_config</span> -<span class="n">app</span><span class="o">.</span><span class="n">config</span><span class="o">.</span><span class="n">from_object</span><span class="p">(</span><span class="n">default_config</span><span class="p">)</span> -</pre></div> -</div> -<p>You should not use this function to load the actual configuration but -rather configuration defaults. The actual config should be loaded -with <a class="reference internal" href="#flask.Config.from_pyfile" title="flask.Config.from_pyfile"><tt class="xref py py-meth docutils literal"><span class="pre">from_pyfile()</span></tt></a> and ideally from a location not within the -package because the package might be installed system wide.</p> -<table class="docutils field-list" frame="void" rules="none"> -<col class="field-name" /> -<col class="field-body" /> -<tbody valign="top"> -<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>obj</strong> – an import name or object</td> -</tr> -</tbody> -</table> -</dd></dl> - -<dl class="method"> -<dt id="flask.Config.from_pyfile"> -<tt class="descname">from_pyfile</tt><big>(</big><em>filename</em>, <em>silent=False</em><big>)</big><a class="headerlink" href="#flask.Config.from_pyfile" title="Permalink to this definition">¶</a></dt> -<dd><p>Updates the values in the config from a Python file. This function -behaves as if the file was imported as module with the -<a class="reference internal" href="#flask.Config.from_object" title="flask.Config.from_object"><tt class="xref py py-meth docutils literal"><span class="pre">from_object()</span></tt></a> function.</p> -<table class="docutils field-list" frame="void" rules="none"> -<col class="field-name" /> -<col class="field-body" /> -<tbody valign="top"> -<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple"> -<li><strong>filename</strong> – the filename of the config. This can either be an -absolute filename or a filename relative to the -root path.</li> -<li><strong>silent</strong> – set to <cite>True</cite> if you want silent failure for missing -files.</li> -</ul> -</td> -</tr> -</tbody> -</table> -<p class="versionadded"> -<span class="versionmodified">New in version 0.7: </span><cite>silent</cite> parameter.</p> -</dd></dl> - -</dd></dl> - -</div> -<div class="section" id="extensions"> -<h2>Extensions<a class="headerlink" href="#extensions" title="Permalink to this headline">¶</a></h2> -<dl class="data"> -<dt id="flask.flask.ext"> -<tt class="descclassname">flask.</tt><tt class="descname">ext</tt><a class="headerlink" href="#flask.flask.ext" title="Permalink to this definition">¶</a></dt> -<dd><p>This module acts as redirect import module to Flask extensions. It was -added in 0.8 as the canonical way to import Flask extensions and makes -it possible for us to have more flexibility in how we distribute -extensions.</p> -<p>If you want to use an extension named “Flask-Foo” you would import it -from <a class="reference internal" href="#flask.flask.ext" title="flask.flask.ext"><tt class="xref py py-data docutils literal"><span class="pre">ext</span></tt></a> as follows:</p> -<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">flask.ext</span> <span class="kn">import</span> <span class="n">foo</span> -</pre></div> -</div> -<p class="versionadded"> -<span class="versionmodified">New in version 0.8.</span></p> -</dd></dl> - -</div> -<div class="section" id="useful-internals"> -<h2>Useful Internals<a class="headerlink" href="#useful-internals" title="Permalink to this headline">¶</a></h2> -<dl class="class"> -<dt id="flask.ctx.RequestContext"> -<em class="property">class </em><tt class="descclassname">flask.ctx.</tt><tt class="descname">RequestContext</tt><big>(</big><em>app</em>, <em>environ</em><big>)</big><a class="headerlink" href="#flask.ctx.RequestContext" title="Permalink to this definition">¶</a></dt> -<dd><p>The request context contains all request relevant information. It is -created at the beginning of the request and pushed to the -<cite>_request_ctx_stack</cite> and removed at the end of it. It will create the -URL adapter and request object for the WSGI environment provided.</p> -<p>Do not attempt to use this class directly, instead use -<a class="reference internal" href="#flask.Flask.test_request_context" title="flask.Flask.test_request_context"><tt class="xref py py-meth docutils literal"><span class="pre">test_request_context()</span></tt></a> and -<a class="reference internal" href="#flask.Flask.request_context" title="flask.Flask.request_context"><tt class="xref py py-meth docutils literal"><span class="pre">request_context()</span></tt></a> to create this object.</p> -<p>When the request context is popped, it will evaluate all the -functions registered on the application for teardown execution -(<a class="reference internal" href="#flask.Flask.teardown_request" title="flask.Flask.teardown_request"><tt class="xref py py-meth docutils literal"><span class="pre">teardown_request()</span></tt></a>).</p> -<p>The request context is automatically popped at the end of the request -for you. In debug mode the request context is kept around if -exceptions happen so that interactive debuggers have a chance to -introspect the data. With 0.4 this can also be forced for requests -that did not fail and outside of <cite>DEBUG</cite> mode. By setting -<tt class="docutils literal"><span class="pre">'flask._preserve_context'</span></tt> to <cite>True</cite> on the WSGI environment the -context will not pop itself at the end of the request. This is used by -the <a class="reference internal" href="#flask.Flask.test_client" title="flask.Flask.test_client"><tt class="xref py py-meth docutils literal"><span class="pre">test_client()</span></tt></a> for example to implement the -deferred cleanup functionality.</p> -<p>You might find this helpful for unittests where you need the -information from the context local around for a little longer. Make -sure to properly <tt class="xref py py-meth docutils literal"><span class="pre">pop()</span></tt> the stack yourself in -that situation, otherwise your unittests will leak memory.</p> -<dl class="method"> -<dt id="flask.ctx.RequestContext.match_request"> -<tt class="descname">match_request</tt><big>(</big><big>)</big><a class="headerlink" href="#flask.ctx.RequestContext.match_request" title="Permalink to this definition">¶</a></dt> -<dd><p>Can be overridden by a subclass to hook into the matching -of the request.</p> -</dd></dl> - -<dl class="method"> -<dt id="flask.ctx.RequestContext.pop"> -<tt class="descname">pop</tt><big>(</big><big>)</big><a class="headerlink" href="#flask.ctx.RequestContext.pop" title="Permalink to this definition">¶</a></dt> -<dd><p>Pops the request context and unbinds it by doing that. This will -also trigger the execution of functions registered by the -<a class="reference internal" href="#flask.Flask.teardown_request" title="flask.Flask.teardown_request"><tt class="xref py py-meth docutils literal"><span class="pre">teardown_request()</span></tt></a> decorator.</p> -</dd></dl> - -<dl class="method"> -<dt id="flask.ctx.RequestContext.push"> -<tt class="descname">push</tt><big>(</big><big>)</big><a class="headerlink" href="#flask.ctx.RequestContext.push" title="Permalink to this definition">¶</a></dt> -<dd><p>Binds the request context to the current context.</p> -</dd></dl> - -</dd></dl> - -<dl class="data"> -<dt id="flask._request_ctx_stack"> -<tt class="descclassname">flask.</tt><tt class="descname">_request_ctx_stack</tt><a class="headerlink" href="#flask._request_ctx_stack" title="Permalink to this definition">¶</a></dt> -<dd><p>The internal <a class="reference external" href="http://werkzeug.pocoo.org/docs/local/#werkzeug.local.LocalStack" title="(in Werkzeug v0.7)"><tt class="xref py py-class docutils literal"><span class="pre">LocalStack</span></tt></a> that is used to implement -all the context local objects used in Flask. This is a documented -instance and can be used by extensions and application code but the -use is discouraged in general.</p> -<p>The following attributes are always present on each layer of the -stack:</p> -<dl class="docutils"> -<dt><cite>app</cite></dt> -<dd>the active Flask application.</dd> -<dt><cite>url_adapter</cite></dt> -<dd>the URL adapter that was used to match the request.</dd> -<dt><cite>request</cite></dt> -<dd>the current request object.</dd> -<dt><cite>session</cite></dt> -<dd>the active session object.</dd> -<dt><cite>g</cite></dt> -<dd>an object with all the attributes of the <a class="reference internal" href="#flask.g" title="flask.g"><tt class="xref py py-data docutils literal"><span class="pre">flask.g</span></tt></a> object.</dd> -<dt><cite>flashes</cite></dt> -<dd>an internal cache for the flashed messages.</dd> -</dl> -<p>Example usage:</p> -<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">flask</span> <span class="kn">import</span> <span class="n">_request_ctx_stack</span> - -<span class="k">def</span> <span class="nf">get_session</span><span class="p">():</span> - <span class="n">ctx</span> <span class="o">=</span> <span class="n">_request_ctx_stack</span><span class="o">.</span><span class="n">top</span> - <span class="k">if</span> <span class="n">ctx</span> <span class="ow">is</span> <span class="ow">not</span> <span class="bp">None</span><span class="p">:</span> - <span class="k">return</span> <span class="n">ctx</span><span class="o">.</span><span class="n">session</span> -</pre></div> -</div> -</dd></dl> - -<dl class="class"> -<dt id="flask.blueprints.BlueprintSetupState"> -<em class="property">class </em><tt class="descclassname">flask.blueprints.</tt><tt class="descname">BlueprintSetupState</tt><big>(</big><em>blueprint</em>, <em>app</em>, <em>options</em>, <em>first_registration</em><big>)</big><a class="headerlink" href="#flask.blueprints.BlueprintSetupState" title="Permalink to this definition">¶</a></dt> -<dd><p>Temporary holder object for registering a blueprint with the -application. An instance of this class is created by the -<a class="reference internal" href="#flask.Blueprint.make_setup_state" title="flask.Blueprint.make_setup_state"><tt class="xref py py-meth docutils literal"><span class="pre">make_setup_state()</span></tt></a> method and later passed -to all register callback functions.</p> -<dl class="method"> -<dt id="flask.blueprints.BlueprintSetupState.add_url_rule"> -<tt class="descname">add_url_rule</tt><big>(</big><em>rule</em>, <em>endpoint=None</em>, <em>view_func=None</em>, <em>**options</em><big>)</big><a class="headerlink" href="#flask.blueprints.BlueprintSetupState.add_url_rule" title="Permalink to this definition">¶</a></dt> -<dd><p>A helper method to register a rule (and optionally a view function) -to the application. The endpoint is automatically prefixed with the -blueprint’s name.</p> -</dd></dl> - -<dl class="attribute"> -<dt id="flask.blueprints.BlueprintSetupState.app"> -<tt class="descname">app</tt><em class="property"> = None</em><a class="headerlink" href="#flask.blueprints.BlueprintSetupState.app" title="Permalink to this definition">¶</a></dt> -<dd><p>a reference to the current application</p> -</dd></dl> - -<dl class="attribute"> -<dt id="flask.blueprints.BlueprintSetupState.blueprint"> -<tt class="descname">blueprint</tt><em class="property"> = None</em><a class="headerlink" href="#flask.blueprints.BlueprintSetupState.blueprint" title="Permalink to this definition">¶</a></dt> -<dd><p>a reference to the blurprint that created this setup state.</p> -</dd></dl> - -<dl class="attribute"> -<dt id="flask.blueprints.BlueprintSetupState.first_registration"> -<tt class="descname">first_registration</tt><em class="property"> = None</em><a class="headerlink" href="#flask.blueprints.BlueprintSetupState.first_registration" title="Permalink to this definition">¶</a></dt> -<dd><p>as blueprints can be registered multiple times with the -application and not everything wants to be registered -multiple times on it, this attribute can be used to figure -out if the blueprint was registered in the past already.</p> -</dd></dl> - -<dl class="attribute"> -<dt id="flask.blueprints.BlueprintSetupState.options"> -<tt class="descname">options</tt><em class="property"> = None</em><a class="headerlink" href="#flask.blueprints.BlueprintSetupState.options" title="Permalink to this definition">¶</a></dt> -<dd><p>a dictionary with all options that were passed to the -<a class="reference internal" href="#flask.Flask.register_blueprint" title="flask.Flask.register_blueprint"><tt class="xref py py-meth docutils literal"><span class="pre">register_blueprint()</span></tt></a> method.</p> -</dd></dl> - -<dl class="attribute"> -<dt id="flask.blueprints.BlueprintSetupState.subdomain"> -<tt class="descname">subdomain</tt><em class="property"> = None</em><a class="headerlink" href="#flask.blueprints.BlueprintSetupState.subdomain" title="Permalink to this definition">¶</a></dt> -<dd><p>The subdomain that the blueprint should be active for, <cite>None</cite> -otherwise.</p> -</dd></dl> - -<dl class="attribute"> -<dt id="flask.blueprints.BlueprintSetupState.url_defaults"> -<tt class="descname">url_defaults</tt><em class="property"> = None</em><a class="headerlink" href="#flask.blueprints.BlueprintSetupState.url_defaults" title="Permalink to this definition">¶</a></dt> -<dd><p>A dictionary with URL defaults that is added to each and every -URL that was defined with the blueprint.</p> -</dd></dl> - -<dl class="attribute"> -<dt id="flask.blueprints.BlueprintSetupState.url_prefix"> -<tt class="descname">url_prefix</tt><em class="property"> = None</em><a class="headerlink" href="#flask.blueprints.BlueprintSetupState.url_prefix" title="Permalink to this definition">¶</a></dt> -<dd><p>The prefix that should be used for all URLs defined on the -blueprint.</p> -</dd></dl> - -</dd></dl> - -</div> -<div class="section" id="signals"> -<h2>Signals<a class="headerlink" href="#signals" title="Permalink to this headline">¶</a></h2> -<p class="versionadded"> -<span class="versionmodified">New in version 0.6.</span></p> -<dl class="data"> -<dt id="flask.signals_available"> -<tt class="descclassname">flask.</tt><tt class="descname">signals_available</tt><a class="headerlink" href="#flask.signals_available" title="Permalink to this definition">¶</a></dt> -<dd><p><cite>True</cite> if the signalling system is available. This is the case -when <a class="reference external" href="http://pypi.python.org/pypi/blinker">blinker</a> is installed.</p> -</dd></dl> - -<dl class="data"> -<dt id="flask.template_rendered"> -<tt class="descclassname">flask.</tt><tt class="descname">template_rendered</tt><a class="headerlink" href="#flask.template_rendered" title="Permalink to this definition">¶</a></dt> -<dd><p>This signal is sent when a template was successfully rendered. The -signal is invoked with the instance of the template as <cite>template</cite> -and the context as dictionary (named <cite>context</cite>).</p> -</dd></dl> - -<dl class="data"> -<dt id="flask.request_started"> -<tt class="descclassname">flask.</tt><tt class="descname">request_started</tt><a class="headerlink" href="#flask.request_started" title="Permalink to this definition">¶</a></dt> -<dd><p>This signal is sent before any request processing started but when the -request context was set up. Because the request context is already -bound, the subscriber can access the request with the standard global -proxies such as <a class="reference internal" href="#flask.request" title="flask.request"><tt class="xref py py-class docutils literal"><span class="pre">request</span></tt></a>.</p> -</dd></dl> - -<dl class="data"> -<dt id="flask.request_finished"> -<tt class="descclassname">flask.</tt><tt class="descname">request_finished</tt><a class="headerlink" href="#flask.request_finished" title="Permalink to this definition">¶</a></dt> -<dd><p>This signal is sent right before the response is sent to the client. -It is passed the response to be sent named <cite>response</cite>.</p> -</dd></dl> - -<dl class="data"> -<dt id="flask.got_request_exception"> -<tt class="descclassname">flask.</tt><tt class="descname">got_request_exception</tt><a class="headerlink" href="#flask.got_request_exception" title="Permalink to this definition">¶</a></dt> -<dd><p>This signal is sent when an exception happens during request processing. -It is sent <em>before</em> the standard exception handling kicks in and even -in debug mode, where no exception handling happens. The exception -itself is passed to the subscriber as <cite>exception</cite>.</p> -</dd></dl> - -<dl class="data"> -<dt id="flask.request_tearing_down"> -<tt class="descclassname">flask.</tt><tt class="descname">request_tearing_down</tt><a class="headerlink" href="#flask.request_tearing_down" title="Permalink to this definition">¶</a></dt> -<dd><p>This signal is sent when the application is tearing down the request. -This is always called, even if an error happened. No arguments are -provided.</p> -</dd></dl> - -<dl class="class"> -<dt id="flask.signals.Namespace"> -<em class="property">class </em><tt class="descclassname">flask.signals.</tt><tt class="descname">Namespace</tt><a class="headerlink" href="#flask.signals.Namespace" title="Permalink to this definition">¶</a></dt> -<dd><p>An alias for <a class="reference external" href="http://discorporate.us/projects/Blinker/docs/1.1/api.html#blinker.base.Namespace" title="(in Blinker v1.1)"><tt class="xref py py-class docutils literal"><span class="pre">blinker.base.Namespace</span></tt></a> if blinker is available, -otherwise a dummy class that creates fake signals. This class is -available for Flask extensions that want to provide the same fallback -system as Flask itself.</p> -<dl class="method"> -<dt id="flask.signals.Namespace.signal"> -<tt class="descname">signal</tt><big>(</big><em>name</em>, <em>doc=None</em><big>)</big><a class="headerlink" href="#flask.signals.Namespace.signal" title="Permalink to this definition">¶</a></dt> -<dd><p>Creates a new signal for this namespace if blinker is available, -otherwise returns a fake signal that has a send method that will -do nothing but will fail with a <a class="reference external" href="http://docs.python.org/dev/library/exceptions.html#RuntimeError" title="(in Python v3.3)"><tt class="xref py py-exc docutils literal"><span class="pre">RuntimeError</span></tt></a> for all other -operations, including connecting.</p> -</dd></dl> - -</dd></dl> - -</div> -<div class="section" id="class-based-views"> -<h2>Class Based Views<a class="headerlink" href="#class-based-views" title="Permalink to this headline">¶</a></h2> -<p class="versionadded"> -<span class="versionmodified">New in version 0.7.</span></p> -<dl class="class"> -<dt id="flask.views.View"> -<em class="property">class </em><tt class="descclassname">flask.views.</tt><tt class="descname">View</tt><a class="headerlink" href="#flask.views.View" title="Permalink to this definition">¶</a></dt> -<dd><p>Alternative way to use view functions. A subclass has to implement -<tt class="xref py py-meth docutils literal"><span class="pre">dispatch_request()</span></tt> which is called with the view arguments from -the URL routing system. If <tt class="xref py py-attr docutils literal"><span class="pre">methods</span></tt> is provided the methods -do not have to be passed to the <a class="reference internal" href="#flask.Flask.add_url_rule" title="flask.Flask.add_url_rule"><tt class="xref py py-meth docutils literal"><span class="pre">add_url_rule()</span></tt></a> -method explicitly:</p> -<div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">MyView</span><span class="p">(</span><span class="n">View</span><span class="p">):</span> - <span class="n">methods</span> <span class="o">=</span> <span class="p">[</span><span class="s">'GET'</span><span class="p">]</span> - - <span class="k">def</span> <span class="nf">dispatch_request</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">name</span><span class="p">):</span> - <span class="k">return</span> <span class="s">'Hello </span><span class="si">%s</span><span class="s">!'</span> <span class="o">%</span> <span class="n">name</span> - -<span class="n">app</span><span class="o">.</span><span class="n">add_url_rule</span><span class="p">(</span><span class="s">'/hello/<name>'</span><span class="p">,</span> <span class="n">view_func</span><span class="o">=</span><span class="n">MyView</span><span class="o">.</span><span class="n">as_view</span><span class="p">(</span><span class="s">'myview'</span><span class="p">))</span> -</pre></div> -</div> -<p>When you want to decorate a pluggable view you will have to either do that -when the view function is created (by wrapping the return value of -<tt class="xref py py-meth docutils literal"><span class="pre">as_view()</span></tt>) or you can use the <tt class="xref py py-attr docutils literal"><span class="pre">decorators</span></tt> attribute:</p> -<div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">SecretView</span><span class="p">(</span><span class="n">View</span><span class="p">):</span> - <span class="n">methods</span> <span class="o">=</span> <span class="p">[</span><span class="s">'GET'</span><span class="p">]</span> - <span class="n">decorators</span> <span class="o">=</span> <span class="p">[</span><span class="n">superuser_required</span><span class="p">]</span> - - <span class="k">def</span> <span class="nf">dispatch_request</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> - <span class="o">...</span> -</pre></div> -</div> -<p>The decorators stored in the decorators list are applied one after another -when the view function is created. Note that you can <em>not</em> use the class -based decorators since those would decorate the view class and not the -generated view function!</p> -<dl class="classmethod"> -<dt id="flask.views.View.as_view"> -<em class="property">classmethod </em><tt class="descname">as_view</tt><big>(</big><em>name</em>, <em>*class_args</em>, <em>**class_kwargs</em><big>)</big><a class="headerlink" href="#flask.views.View.as_view" title="Permalink to this definition">¶</a></dt> -<dd><p>Converts the class into an actual view function that can be -used with the routing system. What it does internally is generating -a function on the fly that will instanciate the <tt class="xref py py-class docutils literal"><span class="pre">View</span></tt> -on each request and call the <tt class="xref py py-meth docutils literal"><span class="pre">dispatch_request()</span></tt> method on it.</p> -<p>The arguments passed to <tt class="xref py py-meth docutils literal"><span class="pre">as_view()</span></tt> are forwarded to the -constructor of the class.</p> -</dd></dl> - -<dl class="attribute"> -<dt id="flask.views.View.decorators"> -<tt class="descname">decorators</tt><em class="property"> = []</em><a class="headerlink" href="#flask.views.View.decorators" title="Permalink to this definition">¶</a></dt> -<dd><p>The canonical way to decorate class based views is to decorate the -return value of as_view(). However since this moves parts of the -logic from the class declaration to the place where it’s hooked -into the routing system.</p> -<p>You can place one or more decorators in this list and whenever the -view function is created the result is automatically decorated.</p> -<p class="versionadded"> -<span class="versionmodified">New in version 0.8.</span></p> -</dd></dl> - -<dl class="method"> -<dt id="flask.views.View.dispatch_request"> -<tt class="descname">dispatch_request</tt><big>(</big><big>)</big><a class="headerlink" href="#flask.views.View.dispatch_request" title="Permalink to this definition">¶</a></dt> -<dd><p>Subclasses have to override this method to implement the -actual view function code. This method is called with all -the arguments from the URL rule.</p> -</dd></dl> - -<dl class="attribute"> -<dt id="flask.views.View.methods"> -<tt class="descname">methods</tt><em class="property"> = None</em><a class="headerlink" href="#flask.views.View.methods" title="Permalink to this definition">¶</a></dt> -<dd><p>A for which methods this pluggable view can handle.</p> -</dd></dl> - -</dd></dl> - -<dl class="class"> -<dt id="flask.views.MethodView"> -<em class="property">class </em><tt class="descclassname">flask.views.</tt><tt class="descname">MethodView</tt><a class="headerlink" href="#flask.views.MethodView" title="Permalink to this definition">¶</a></dt> -<dd><p>Like a regular class based view but that dispatches requests to -particular methods. For instance if you implement a method called -<tt class="xref py py-meth docutils literal"><span class="pre">get()</span></tt> it means you will response to <tt class="docutils literal"><span class="pre">'GET'</span></tt> requests and -the <tt class="xref py py-meth docutils literal"><span class="pre">dispatch_request()</span></tt> implementation will automatically -forward your request to that. Also <tt class="xref py py-attr docutils literal"><span class="pre">options</span></tt> is set for you -automatically:</p> -<div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">CounterAPI</span><span class="p">(</span><span class="n">MethodView</span><span class="p">):</span> - - <span class="k">def</span> <span class="nf">get</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> - <span class="k">return</span> <span class="n">session</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s">'counter'</span><span class="p">,</span> <span class="mi">0</span><span class="p">)</span> - - <span class="k">def</span> <span class="nf">post</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> - <span class="n">session</span><span class="p">[</span><span class="s">'counter'</span><span class="p">]</span> <span class="o">=</span> <span class="n">session</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s">'counter'</span><span class="p">,</span> <span class="mi">0</span><span class="p">)</span> <span class="o">+</span> <span class="mi">1</span> - <span class="k">return</span> <span class="s">'OK'</span> - -<span class="n">app</span><span class="o">.</span><span class="n">add_url_rule</span><span class="p">(</span><span class="s">'/counter'</span><span class="p">,</span> <span class="n">view_func</span><span class="o">=</span><span class="n">CounterAPI</span><span class="o">.</span><span class="n">as_view</span><span class="p">(</span><span class="s">'counter'</span><span class="p">))</span> -</pre></div> -</div> -</dd></dl> - -</div> -<div class="section" id="url-route-registrations"> -<span id="id2"></span><h2>URL Route Registrations<a class="headerlink" href="#url-route-registrations" title="Permalink to this headline">¶</a></h2> -<p>Generally there are three ways to define rules for the routing system:</p> -<ol class="arabic simple"> -<li>You can use the <a class="reference internal" href="#flask.Flask.route" title="flask.Flask.route"><tt class="xref py py-meth docutils literal"><span class="pre">flask.Flask.route()</span></tt></a> decorator.</li> -<li>You can use the <a class="reference internal" href="#flask.Flask.add_url_rule" title="flask.Flask.add_url_rule"><tt class="xref py py-meth docutils literal"><span class="pre">flask.Flask.add_url_rule()</span></tt></a> function.</li> -<li>You can directly access the underlying Werkzeug routing system -which is exposed as <a class="reference internal" href="#flask.Flask.url_map" title="flask.Flask.url_map"><tt class="xref py py-attr docutils literal"><span class="pre">flask.Flask.url_map</span></tt></a>.</li> -</ol> -<p>Variable parts in the route can be specified with angular brackets -(<tt class="docutils literal"><span class="pre">/user/<username></span></tt>). By default a variable part in the URL accepts any -string without a slash however a different converter can be specified as -well by using <tt class="docutils literal"><span class="pre"><converter:name></span></tt>.</p> -<p>Variable parts are passed to the view function as keyword arguments.</p> -<p>The following converters are available:</p> -<table border="1" class="docutils"> -<colgroup> -<col width="19%" /> -<col width="81%" /> -</colgroup> -<tbody valign="top"> -<tr class="row-odd"><td><cite>unicode</cite></td> -<td>accepts any text without a slash (the default)</td> -</tr> -<tr class="row-even"><td><cite>int</cite></td> -<td>accepts integers</td> -</tr> -<tr class="row-odd"><td><cite>float</cite></td> -<td>like <cite>int</cite> but for floating point values</td> -</tr> -<tr class="row-even"><td><cite>path</cite></td> -<td>like the default but also accepts slashes</td> -</tr> -</tbody> -</table> -<p>Here are some examples:</p> -<div class="highlight-python"><div class="highlight"><pre><span class="nd">@app.route</span><span class="p">(</span><span class="s">'/'</span><span class="p">)</span> -<span class="k">def</span> <span class="nf">index</span><span class="p">():</span> - <span class="k">pass</span> - -<span class="nd">@app.route</span><span class="p">(</span><span class="s">'/<username>'</span><span class="p">)</span> -<span class="k">def</span> <span class="nf">show_user</span><span class="p">(</span><span class="n">username</span><span class="p">):</span> - <span class="k">pass</span> - -<span class="nd">@app.route</span><span class="p">(</span><span class="s">'/post/<int:post_id>'</span><span class="p">)</span> -<span class="k">def</span> <span class="nf">show_post</span><span class="p">(</span><span class="n">post_id</span><span class="p">):</span> - <span class="k">pass</span> -</pre></div> -</div> -<p>An important detail to keep in mind is how Flask deals with trailing -slashes. The idea is to keep each URL unique so the following rules -apply:</p> -<ol class="arabic simple"> -<li>If a rule ends with a slash and is requested without a slash by the -user, the user is automatically redirected to the same page with a -trailing slash attached.</li> -<li>If a rule does not end with a trailing slash and the user requests the -page with a trailing slash, a 404 not found is raised.</li> -</ol> -<p>This is consistent with how web servers deal with static files. This -also makes it possible to use relative link targets safely.</p> -<p>You can also define multiple rules for the same function. They have to be -unique however. Defaults can also be specified. Here for example is a -definition for a URL that accepts an optional page:</p> -<div class="highlight-python"><div class="highlight"><pre><span class="nd">@app.route</span><span class="p">(</span><span class="s">'/users/'</span><span class="p">,</span> <span class="n">defaults</span><span class="o">=</span><span class="p">{</span><span class="s">'page'</span><span class="p">:</span> <span class="mi">1</span><span class="p">})</span> -<span class="nd">@app.route</span><span class="p">(</span><span class="s">'/users/page/<int:page>'</span><span class="p">)</span> -<span class="k">def</span> <span class="nf">show_users</span><span class="p">(</span><span class="n">page</span><span class="p">):</span> - <span class="k">pass</span> -</pre></div> -</div> -<p>This specifies that <tt class="docutils literal"><span class="pre">/users/</span></tt> will be the URL for page one and -<tt class="docutils literal"><span class="pre">/users/page/N</span></tt> will be the URL for page <cite>N</cite>.</p> -<p>Here are the parameters that <a class="reference internal" href="#flask.Flask.route" title="flask.Flask.route"><tt class="xref py py-meth docutils literal"><span class="pre">route()</span></tt></a> and -<a class="reference internal" href="#flask.Flask.add_url_rule" title="flask.Flask.add_url_rule"><tt class="xref py py-meth docutils literal"><span class="pre">add_url_rule()</span></tt></a> accept. The only difference is that -with the route parameter the view function is defined with the decorator -instead of the <cite>view_func</cite> parameter.</p> -<table border="1" class="docutils"> -<colgroup> -<col width="21%" /> -<col width="79%" /> -</colgroup> -<tbody valign="top"> -<tr class="row-odd"><td><cite>rule</cite></td> -<td>the URL roule as string</td> -</tr> -<tr class="row-even"><td><cite>endpoint</cite></td> -<td>the endpoint for the registered URL rule. Flask itself -assumes that the name of the view function is the name -of the endpoint if not explicitly stated.</td> -</tr> -<tr class="row-odd"><td><cite>view_func</cite></td> -<td>the function to call when serving a request to the -provided endpoint. If this is not provided one can -specify the function later by storing it in the -<a class="reference internal" href="#flask.Flask.view_functions" title="flask.Flask.view_functions"><tt class="xref py py-attr docutils literal"><span class="pre">view_functions</span></tt></a> dictionary with the -endpoint as key.</td> -</tr> -<tr class="row-even"><td><cite>defaults</cite></td> -<td>A dictionary with defaults for this rule. See the -example above for how defaults work.</td> -</tr> -<tr class="row-odd"><td><cite>subdomain</cite></td> -<td>specifies the rule for the subdomain in case subdomain -matching is in use. If not specified the default -subdomain is assumed.</td> -</tr> -<tr class="row-even"><td><cite>**options</cite></td> -<td>the options to be forwarded to the underlying -<a class="reference external" href="http://werkzeug.pocoo.org/docs/routing/#werkzeug.routing.Rule" title="(in Werkzeug v0.7)"><tt class="xref py py-class docutils literal"><span class="pre">Rule</span></tt></a> object. A change to -Werkzeug is handling of method options. methods is a list -of methods this rule should be limited to (<cite>GET</cite>, <cite>POST</cite> -etc.). By default a rule just listens for <cite>GET</cite> (and -implicitly <cite>HEAD</cite>). Starting with Flask 0.6, <cite>OPTIONS</cite> is -implicitly added and handled by the standard request -handling. They have to be specified as keyword arguments.</td> -</tr> -</tbody> -</table> -</div> -<div class="section" id="view-function-options"> -<span id="view-func-options"></span><h2>View Function Options<a class="headerlink" href="#view-function-options" title="Permalink to this headline">¶</a></h2> -<p>For internal usage the view functions can have some attributes attached to -customize behavior the view function would normally not have control over. -The following attributes can be provided optionally to either override -some defaults to <a class="reference internal" href="#flask.Flask.add_url_rule" title="flask.Flask.add_url_rule"><tt class="xref py py-meth docutils literal"><span class="pre">add_url_rule()</span></tt></a> or general behavior:</p> -<ul class="simple"> -<li><cite>__name__</cite>: The name of a function is by default used as endpoint. If -endpoint is provided explicitly this value is used. Additionally this -will be prefixed with the name of the blueprint by default which -cannot be customized from the function itself.</li> -<li><cite>methods</cite>: If methods are not provided when the URL rule is added, -Flask will look on the view function object itself is an <cite>methods</cite> -attribute exists. If it does, it will pull the information for the -methods from there.</li> -<li><cite>provide_automatic_options</cite>: if this attribute is set Flask will -either force enable or disable the automatic implementation of the -HTTP <cite>OPTIONS</cite> response. This can be useful when working with -decorators that want to customize the <cite>OPTIONS</cite> response on a per-view -basis.</li> -</ul> -<p>Full example:</p> -<div class="highlight-python"><div class="highlight"><pre><span class="k">def</span> <span class="nf">index</span><span class="p">():</span> - <span class="k">if</span> <span class="n">request</span><span class="o">.</span><span class="n">method</span> <span class="o">==</span> <span class="s">'OPTIONS'</span><span class="p">:</span> - <span class="c"># custom options handling here</span> - <span class="o">...</span> - <span class="k">return</span> <span class="s">'Hello World!'</span> -<span class="n">index</span><span class="o">.</span><span class="n">provide_automatic_options</span> <span class="o">=</span> <span class="bp">False</span> -<span class="n">index</span><span class="o">.</span><span class="n">methods</span> <span class="o">=</span> <span class="p">[</span><span class="s">'GET'</span><span class="p">,</span> <span class="s">'OPTIONS'</span><span class="p">]</span> - -<span class="n">app</span><span class="o">.</span><span class="n">add_url_rule</span><span class="p">(</span><span class="s">'/'</span><span class="p">,</span> <span class="n">index</span><span class="p">)</span> -</pre></div> -</div> -<p class="versionadded"> -<span class="versionmodified">New in version 0.8: </span>The <cite>provide_automatic_options</cite> functionality was added.</p> -</div> -</div> - - - </div> - </div> - </div> - <div class="sphinxsidebar"> - <div class="sphinxsidebarwrapper"><p class="logo"><a href="index.html"> - <img class="logo" src="_static/flask.png" alt="Logo"/> -</a></p> - <h3><a href="index.html">Table Of Contents</a></h3> - <ul> -<li><a class="reference internal" href="#">API</a><ul> -<li><a class="reference internal" href="#application-object">Application Object</a></li> -<li><a class="reference internal" href="#blueprint-objects">Blueprint Objects</a></li> -<li><a class="reference internal" href="#incoming-request-data">Incoming Request Data</a></li> -<li><a class="reference internal" href="#response-objects">Response Objects</a></li> -<li><a class="reference internal" href="#sessions">Sessions</a></li> -<li><a class="reference internal" href="#session-interface">Session Interface</a></li> -<li><a class="reference internal" href="#test-client">Test Client</a></li> -<li><a class="reference internal" href="#application-globals">Application Globals</a></li> -<li><a class="reference internal" href="#useful-functions-and-classes">Useful Functions and Classes</a></li> -<li><a class="reference internal" href="#message-flashing">Message Flashing</a></li> -<li><a class="reference internal" href="#returning-json">Returning JSON</a></li> -<li><a class="reference internal" href="#template-rendering">Template Rendering</a></li> -<li><a class="reference internal" href="#configuration">Configuration</a></li> -<li><a class="reference internal" href="#extensions">Extensions</a></li> -<li><a class="reference internal" href="#useful-internals">Useful Internals</a></li> -<li><a class="reference internal" href="#signals">Signals</a></li> -<li><a class="reference internal" href="#class-based-views">Class Based Views</a></li> -<li><a class="reference internal" href="#url-route-registrations">URL Route Registrations</a></li> -<li><a class="reference internal" href="#view-function-options">View Function Options</a></li> -</ul> -</li> -</ul> -<h3>Related Topics</h3> -<ul> - <li><a href="index.html">Documentation overview</a><ul> - <li>Previous: <a href="becomingbig.html" title="previous chapter">Becoming Big</a></li> - <li>Next: <a href="design.html" title="next chapter">Design Decisions in Flask</a></li> - </ul></li> -</ul> - <h3>This Page</h3> - <ul class="this-page-menu"> - <li><a href="_sources/api.txt" - rel="nofollow">Show Source</a></li> - </ul> -<div id="searchbox" style="display: none"> - <h3>Quick search</h3> - <form class="search" action="search.html" method="get"> - <input type="text" name="q" /> - <input type="submit" value="Go" /> - <input type="hidden" name="check_keywords" value="yes" /> - <input type="hidden" name="area" value="default" /> - </form> - <p class="searchtip" style="font-size: 90%"> - Enter search terms or a module, class or function name. - </p> -</div> -<script type="text/javascript">$('#searchbox').show(0);</script> - </div> - </div> - <div class="clearer"></div> - </div> - <div class="footer"> - © Copyright 2010, Armin Ronacher. - Created using <a href="http://sphinx.pocoo.org/">Sphinx</a>. - </div> - </body> -</html>
\ No newline at end of file |