diff options
Diffstat (limited to 'app/static/doc/flask-docs/design.html')
| -rw-r--r-- | app/static/doc/flask-docs/design.html | 276 |
1 files changed, 0 insertions, 276 deletions
diff --git a/app/static/doc/flask-docs/design.html b/app/static/doc/flask-docs/design.html deleted file mode 100644 index b5dd479..0000000 --- a/app/static/doc/flask-docs/design.html +++ /dev/null @@ -1,276 +0,0 @@ - -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" - "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> - - -<html xmlns="http://www.w3.org/1999/xhtml"> - <head> - <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> - - <title>Design Decisions in Flask — 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="HTML/XHTML FAQ" href="htmlfaq.html" /> - <link rel="prev" title="API" href="api.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="htmlfaq.html" title="HTML/XHTML FAQ" - accesskey="N">next</a> |</li> - <li class="right" > - <a href="api.html" title="API" - 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="design-decisions-in-flask"> -<span id="design"></span><h1>Design Decisions in Flask<a class="headerlink" href="#design-decisions-in-flask" title="Permalink to this headline">¶</a></h1> -<p>If you are curious why Flask does certain things the way it does and not -differently, this section is for you. This should give you an idea about -some of the design decisions that may appear arbitrary and surprising at -first, especially in direct comparison with other frameworks.</p> -<div class="section" id="the-explicit-application-object"> -<h2>The Explicit Application Object<a class="headerlink" href="#the-explicit-application-object" title="Permalink to this headline">¶</a></h2> -<p>A Python web application based on WSGI has to have one central callable -object that implements the actual application. In Flask this is an -instance of the <a class="reference internal" href="api.html#flask.Flask" title="flask.Flask"><tt class="xref py py-class docutils literal"><span class="pre">Flask</span></tt></a> class. Each Flask application has -to create an instance of this class itself and pass it the name of the -module, but why can’t Flask do that itself?</p> -<p>Without such an explicit application object the following code:</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> - -<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>Would look like this instead:</p> -<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">hypothetical_flask</span> <span class="kn">import</span> <span class="n">route</span> - -<span class="nd">@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>There are three major reasons for this. The most important one is that -implicit application objects require that there may only be one instance at -the time. There are ways to fake multiple applications with a single -application object, like maintaining a stack of applications, but this -causes some problems I won’t outline here in detail. Now the question is: -when does a microframework need more than one application at the same -time? A good example for this is unittesting. When you want to test -something it can be very helpful to create a minimal application to test -specific behavior. When the application object is deleted everything it -allocated will be freed again.</p> -<p>Another thing that becomes possible when you have an explicit object lying -around in your code is that you can subclass the base class -(<a class="reference internal" href="api.html#flask.Flask" title="flask.Flask"><tt class="xref py py-class docutils literal"><span class="pre">Flask</span></tt></a>) to alter specific behaviour. This would not be -possible without hacks if the object were created ahead of time for you -based on a class that is not exposed to you.</p> -<p>But there is another very important reason why Flask depends on an -explicit instantiation of that class: the package name. Whenever you -create a Flask instance you usually pass it <cite>__name__</cite> as package name. -Flask depends on that information to properly load resources relative -to your module. With Python’s outstanding support for reflection it can -then access the package to figure out where the templates and static files -are stored (see <a class="reference internal" href="api.html#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>). Now obviously there -are frameworks around that do not need any configuration and will still be -able to load templates relative to your application module. But they have -to use the current working directory for that, which is a very unreliable -way to determine where the application is. The current working directory -is process-wide and if you are running multiple applications in one -process (which could happen in a webserver without you knowing) the paths -will be off. Worse: many webservers do not set the working directory to -the directory of your application but to the document root which does not -have to be the same folder.</p> -<p>The third reason is “explicit is better than implicit”. That object is -your WSGI application, you don’t have to remember anything else. If you -want to apply a WSGI middleware, just wrap it and you’re done (though -there are better ways to do that so that you do not lose the reference -to the application object <a class="reference internal" href="api.html#flask.Flask.wsgi_app" title="flask.Flask.wsgi_app"><tt class="xref py py-meth docutils literal"><span class="pre">wsgi_app()</span></tt></a>).</p> -<p>Furthermore this design makes it possible to use a factory function to -create the application which is very helpful for unittesting and similar -things (<a class="reference internal" href="patterns/appfactories.html#app-factories"><em>Application Factories</em></a>).</p> -</div> -<div class="section" id="the-routing-system"> -<h2>The Routing System<a class="headerlink" href="#the-routing-system" title="Permalink to this headline">¶</a></h2> -<p>Flask uses the Werkzeug routing system which has was designed to -automatically order routes by complexity. This means that you can declare -routes in arbitrary order and they will still work as expected. This is a -requirement if you want to properly implement decorator based routing -since decorators could be fired in undefined order when the application is -split into multiple modules.</p> -<p>Another design decision with the Werkzeug routing system is that routes -in Werkzeug try to ensure that there is that URLs are unique. Werkzeug -will go quite far with that in that it will automatically redirect to a -canonical URL if a route is ambiguous.</p> -</div> -<div class="section" id="one-template-engine"> -<h2>One Template Engine<a class="headerlink" href="#one-template-engine" title="Permalink to this headline">¶</a></h2> -<p>Flask decides on one template engine: Jinja2. Why doesn’t Flask have a -pluggable template engine interface? You can obviously use a different -template engine, but Flask will still configure Jinja2 for you. While -that limitation that Jinja2 is <em>always</em> configured will probably go away, -the decision to bundle one template engine and use that will not.</p> -<p>Template engines are like programming languages and each of those engines -has a certain understanding about how things work. On the surface they -all work the same: you tell the engine to evaluate a template with a set -of variables and take the return value as string.</p> -<p>But that’s about where similarities end. Jinja2 for example has an -extensive filter system, a certain way to do template inheritance, support -for reusable blocks (macros) that can be used from inside templates and -also from Python code, uses Unicode for all operations, supports -iterative template rendering, configurable syntax and more. On the other -hand an engine like Genshi is based on XML stream evaluation, template -inheritance by taking the availability of XPath into account and more. -Mako on the other hand treats templates similar to Python modules.</p> -<p>When it comes to connecting a template engine with an application or -framework there is more than just rendering templates. For instance, -Flask uses Jinja2’s extensive autoescaping support. Also it provides -ways to access macros from Jinja2 templates.</p> -<p>A template abstraction layer that would not take the unique features of -the template engines away is a science on its own and a too large -undertaking for a microframework like Flask.</p> -<p>Furthermore extensions can then easily depend on one template language -being present. You can easily use your own templating language, but an -extension could still depend on Jinja itself.</p> -</div> -<div class="section" id="micro-with-dependencies"> -<h2>Micro with Dependencies<a class="headerlink" href="#micro-with-dependencies" title="Permalink to this headline">¶</a></h2> -<p>Why does Flask call itself a microframework and yet it depends on two -libraries (namely Werkzeug and Jinja2). Why shouldn’t it? If we look -over to the Ruby side of web development there we have a protocol very -similar to WSGI. Just that it’s called Rack there, but besides that it -looks very much like a WSGI rendition for Ruby. But nearly all -applications in Ruby land do not work with Rack directly, but on top of a -library with the same name. This Rack library has two equivalents in -Python: WebOb (formerly Paste) and Werkzeug. Paste is still around but -from my understanding it’s sort of deprecated in favour of WebOb. The -development of WebOb and Werkzeug started side by side with similar ideas -in mind: be a good implementation of WSGI for other applications to take -advantage.</p> -<p>Flask is a framework that takes advantage of the work already done by -Werkzeug to properly interface WSGI (which can be a complex task at -times). Thanks to recent developments in the Python package -infrastructure, packages with dependencies are no longer an issue and -there are very few reasons against having libraries that depend on others.</p> -</div> -<div class="section" id="thread-locals"> -<h2>Thread Locals<a class="headerlink" href="#thread-locals" title="Permalink to this headline">¶</a></h2> -<p>Flask uses thread local objects (context local objects in fact, they -support greenlet contexts as well) for request, session and an extra -object you can put your own things on (<a class="reference internal" href="api.html#flask.g" title="flask.g"><tt class="xref py py-data docutils literal"><span class="pre">g</span></tt></a>). Why is that and -isn’t that a bad idea?</p> -<p>Yes it is usually not such a bright idea to use thread locals. They cause -troubles for servers that are not based on the concept of threads and make -large applications harder to maintain. However Flask is just not designed -for large applications or asynchronous servers. Flask wants to make it -quick and easy to write a traditional web application.</p> -<p>Also see the <a class="reference internal" href="becomingbig.html#becomingbig"><em>Becoming Big</em></a> section of the documentation for some -inspiration for larger applications based on Flask.</p> -</div> -<div class="section" id="what-flask-is-what-flask-is-not"> -<h2>What Flask is, What Flask is Not<a class="headerlink" href="#what-flask-is-what-flask-is-not" title="Permalink to this headline">¶</a></h2> -<p>Flask will never have a database layer. It will not have a form library -or anything else in that direction. Flask itself just bridges to Werkzeug -to implement a proper WSGI application and to Jinja2 to handle templating. -It also binds to a few common standard library packages such as logging. -Everything else is up for extensions.</p> -<p>Why is this the case? Because people have different preferences and -requirements and Flask could not meet those if it would force any of this -into the core. The majority of web applications will need a template -engine in some sort. However not every application needs a SQL database.</p> -<p>The idea of Flask is to build a good foundation for all applications. -Everything else is up to you or extensions.</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="#">Design Decisions in Flask</a><ul> -<li><a class="reference internal" href="#the-explicit-application-object">The Explicit Application Object</a></li> -<li><a class="reference internal" href="#the-routing-system">The Routing System</a></li> -<li><a class="reference internal" href="#one-template-engine">One Template Engine</a></li> -<li><a class="reference internal" href="#micro-with-dependencies">Micro with Dependencies</a></li> -<li><a class="reference internal" href="#thread-locals">Thread Locals</a></li> -<li><a class="reference internal" href="#what-flask-is-what-flask-is-not">What Flask is, What Flask is Not</a></li> -</ul> -</li> -</ul> -<h3>Related Topics</h3> -<ul> - <li><a href="index.html">Documentation overview</a><ul> - <li>Previous: <a href="api.html" title="previous chapter">API</a></li> - <li>Next: <a href="htmlfaq.html" title="next chapter">HTML/XHTML FAQ</a></li> - </ul></li> -</ul> - <h3>This Page</h3> - <ul class="this-page-menu"> - <li><a href="_sources/design.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 |