diff options
Diffstat (limited to 'studio/static/doc/flask-docs/api.html')
| -rw-r--r-- | studio/static/doc/flask-docs/api.html | 3475 |
1 files changed, 3475 insertions, 0 deletions
diff --git a/studio/static/doc/flask-docs/api.html b/studio/static/doc/flask-docs/api.html new file mode 100644 index 0000000..f130677 --- /dev/null +++ b/studio/static/doc/flask-docs/api.html @@ -0,0 +1,3475 @@ + +<!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 |