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

Merge remote branch 'mitsuhiko/master'

Browse source
This commit is contained in:
Nick Walker 2010-10-11 19:09:06 -07:00
commit 38262ccac5
84 changed files with 5584 additions and 2003 deletions
Download patch file Download diff file Expand all files Collapse all files

28
docs/LICENSE
View file

@ -1,28 +0,0 @@
Copyright (c) 2010 by Armin Ronacher and contributors. See AUTHORS
for more details.
Some rights reserved.
Redistribution and use in source (reStructuredText) and 'compiled' forms (HTML,
PDF, PostScript, RTF and so forth) with or without modification, are permitted
provided that the following conditions are met:
* Redistributions of source code (reStructuredText) must retain the above
copyright notice, this list of conditions and the following disclaimer as the
first lines of this file unmodified.
* Redistributions in compiled form (converted to HTML, PDF, PostScript, RTF
and so forth) must reproduce the above copyright notice, this list of
conditions and the following disclaimer in the documentation and/or other
materials provided with the distribution.
THIS DOCUMENTATION IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

1
docs/_themes Submodule

@ -0,0 +1 @@
Subproject commit 3d964b660442e23faedf801caed6e3c7bd42d5c9

122
docs/api.rst
View file

@ -38,6 +38,8 @@ Incoming Request Data
sure that you always get the correct data for the active thread if you
are in a multithreaded environment.
This is a proxy. See :ref:`notes-on-proxies` for more information.
The request object is an instance of a :class:`~werkzeug.Request`
subclass and provides all of the attributes Werkzeug defines. This
just shows a quick overview of the most important ones.
@ -164,6 +166,8 @@ To access the current session you can use the :class:`session` object:
The session object works pretty much like an ordinary dict, with the
difference that it keeps track on modifications.
This is a proxy. See :ref:`notes-on-proxies` for more information.
The following attributes are interesting:
.. attribute:: new
@ -206,6 +210,8 @@ thing, like it does for :class:`request` and :class:`session`.
Just store on this whatever you want. For example a database
connection or the user that is currently logged in.
This is a proxy. See :ref:`notes-on-proxies` for more information.
Useful Functions and Classes
----------------------------
@ -216,6 +222,8 @@ Useful Functions and Classes
extensions that want to support multiple applications running side
by side.
This is a proxy. See :ref:`notes-on-proxies` for more information.
.. autofunction:: url_for
.. function:: abort(code)
@ -228,8 +236,12 @@ Useful Functions and Classes
.. autofunction:: redirect
.. autofunction:: make_response
.. autofunction:: send_file
.. autofunction:: send_from_directory
.. autofunction:: escape
.. autoclass:: Markup
@ -301,6 +313,36 @@ Useful Internals
instance and can be used by extensions and application code but the
use is discouraged in general.
The following attributes are always present on each layer of the
stack:
`app`
the active Flask application.
`url_adapter`
the URL adapter that was used to match the request.
`request`
the current request object.
`session`
the active session object.
`g`
an object with all the attributes of the :data:`flask.g` object.
`flashes`
an internal cache for the flashed messages.
Example usage::
from flask import _request_ctx_stack
def get_session():
ctx = _request_ctx_stack.top
if ctx is not None:
return ctx.session
.. versionchanged:: 0.4
The request context is automatically popped at the end of the request
@ -317,3 +359,83 @@ Useful Internals
information from the context local around for a little longer. Make
sure to properly :meth:`~werkzeug.LocalStack.pop` the stack yourself in
that situation, otherwise your unittests will leak memory.
Signals
-------
.. when modifying this list, also update the one in signals.rst
.. versionadded:: 0.6
.. data:: signals_available
`True` if the signalling system is available. This is the case
when `blinker`_ is installed.
.. data:: template_rendered
This signal is sent when a template was successfully rendered. The
signal is invoked with the instance of the template as `template`
and the context as dictionary (named `context`).
.. data:: request_started
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 :class:`~flask.request`.
.. data:: request_finished
This signal is sent right before the response is sent to the client.
It is passed the response to be sent named `response`.
.. data:: got_request_exception
This signal is sent when an exception happens during request processing.
It is sent *before* 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 `exception`.
.. currentmodule:: None
.. class:: flask.signals.Namespace
An alias for :class:`blinker.base.Namespace` 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.
.. method:: signal(name, doc=None)
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 :exc:`RuntimeError` for all other
operations, including connecting.
.. _blinker: http://pypi.python.org/pypi/blinker
.. _notes-on-proxies:
Notes On Proxies
----------------
Some of the objects provided by Flask are proxies to other objects. The
reason behind this is that these proxies are shared between threads and
they have to dispatch to the actual object bound to a thread behind the
scenes as necessary.
Most of the time you don't have to care about that, but there are some
exceptions where it is good to know that this object is an actual proxy:
- The proxy objects do not fake their inherited types, so if you want to
perform actual instance checks, you have to do that on the instance
that is being proxied (see `_get_current_object` below).
- if the object reference is important (so for example for sending
:ref:`signals`)
If you need to get access to the underlying object that is proxied, you
can use the :meth:`~werkzeug.LocalProxy._get_current_object` method::
app = current_app._get_current_object()
my_signal.send(app)

112
docs/becomingbig.rst
View file

@ -3,54 +3,86 @@
Becoming Big
============
Your application is becoming more and more complex? Flask is really not
designed for large scale applications and does not attempt to do so, but
that does not mean you picked the wrong tool in the first place.
Your application is becoming more and more complex? If you suddenly
realize that Flask does things in a way that does not work out for your
application there are ways to deal with that.
Flask is powered by Werkzeug and Jinja2, two libraries that are in use at
a number of large websites out there and all Flask does is bring those
two together. Being a microframework, Flask is literally a single file.
What that means for large applications is that it's probably a good idea
to take the code from Flask and put it into a new module within the
applications and expand on that.
two together. Being a microframework Flask does not do much more than
combining existing libraries - there is not a lot of code involved.
What that means for large applications is that it's very easy to take the
code from Flask and put it into a new module within the applications and
expand on that.
What Could Be Improved?
-----------------------
Flask is designed to be extended and modified in a couple of different
ways:
For instance it makes a lot of sense to change the way endpoints (the
names of the functions / URL rules) are handled to also take the module
name into account. Right now the function name is the URL name, but
imagine you have a large application consisting of multiple components.
In that case, it makes a lot of sense to use dotted names for the URL
endpoints.
- Flask extensions. For a lot of reusable functionality you can create
extensions. For extensions a number of hooks exist throughout Flask
with signals and callback functions.
Here are some suggestions for how Flask can be modified to better
accommodate large-scale applications:
- Subclassing. The majority of functionality can be changed by creating
a new subclass of the :class:`~flask.Flask` class and overriding
methods provided for this exact purpose.
- get rid of the decorator function registering which causes a lot
of troubles for applications that have circular dependencies. It
also requires that the whole application is imported when the system
initializes or certain URLs will not be available right away. A
better solution would be to have one module with all URLs in there and
specifying the target functions explicitly or by name and importing
them when needed.
- switch to explicit request object passing. This requires more typing
(because you now have something to pass around) but it makes it a
whole lot easier to debug hairy situations and to test the code.
- integrate the `Babel`_ i18n package or `SQLAlchemy`_ directly into the
core framework.
- Forking. If nothing else works out you can just take the Flask
codebase at a given point and copy/paste it into your application
and change it. Flask is designed with that in mind and makes this
incredible easy. You just have to take the package and copy it
into your application's code and rename it (for example to
`framework`). Then you can start modifying the code in there.
.. _Babel: http://babel.edgewall.org/
.. _SQLAlchemy: http://www.sqlalchemy.org/
Why consider Forking?
---------------------
Why does Flask not do all that by Default?
------------------------------------------
The majority of code of Flask is within Werkzeug and Jinja2. These
libraries do the majority of the work. Flask is just the paste that glues
those together. For every project there is the point where the underlying
framework gets in the way (due to assumptions the original developers
had). This is natural because if this would not be the case, the
framework would be a very complex system to begin with which causes a
steep learning curve and a lot of user frustration.
There is a huge difference between a small application that only has to
handle a couple of requests per second and with an overall code complexity
of less than 4000 lines of code and something of larger scale. At some
point it becomes important to integrate external systems, different
storage backends and more.
This is not unique to Flask. Many people use patched and modified
versions of their framework to counter shortcomings. This idea is also
reflected in the license of Flask. You don't have to contribute any
changes back if you decide to modify the framework.
If Flask was designed with all these contingencies in mind, it would be a
much more complex framework and harder to get started with.
The downside of forking is of course that Flask extensions will most
likely break because the new framework has a different import name.
Furthermore integrating upstream changes can be a complex process,
depending on the number of changes. Because of that, forking should be
the very last resort.
Scaling like a Pro
------------------
For many web applications the complexity of the code is less an issue than
the scaling for the number of users or data entries expected. Flask by
itself is only limited in terms of scaling by your application code, the
data store you want to use and the Python implementation and webserver you
are running on.
Scaling well means for example that if you double the amount of servers
you get about twice the performance. Scaling bad means that if you add a
new server the application won't perform any better or would not even
support a second server.
There is only one limiting factor regarding scaling in Flask which are
the context local proxies. They depend on context which in Flask is
defined as being either a thread, process or greenlet. If your server
uses some kind of concurrency that is not based on threads or greenlets,
Flask will no longer be able to support these global proxies. However the
majority of servers are using either threads, greenlets or separate
processes to achieve concurrency which are all methods well supported by
the underlying Werkzeug library.
Dialogue with the Community
---------------------------
The Flask developers are very interested to keep everybody happy, so as
soon as you find an obstacle in your way, caused by Flask, don't hesitate
to contact the developers on the mailinglist or IRC channel. The best way
for the Flask and Flask-extension developers to improve it for larger
applications is getting feedback from users.

18
docs/conf.py
View file

@ -245,7 +245,23 @@ intersphinx_mapping = {
'http://docs.python.org/dev': None,
'http://werkzeug.pocoo.org/documentation/dev/': None,
'http://www.sqlalchemy.org/docs/': None,
'http://wtforms.simplecodes.com/docs/0.5/': None
'http://wtforms.simplecodes.com/docs/0.5/': None,
'http://discorporate.us/projects/Blinker/docs/1.1/': None
}
pygments_style = 'flask_theme_support.FlaskyStyle'
# fall back if theme is not there
try:
__import__('flask_theme_support')
except ImportError, e:
print '-' * 74
print 'Warning: Flask themes unavailable. Building with default theme'
print 'If you want the Flask themes, run this command and build again:'
print
print ' git submodule update --init'
print '-' * 74
pygments_style = 'tango'
html_theme = 'default'
html_theme_options = {}

117
docs/config.rst
View file

@ -6,12 +6,12 @@ Configuration Handling
.. versionadded:: 0.3
Applications need some kind of configuration. There are different things
you might want to change. Like toggling debug mode, the secret key and a
you might want to change like toggling debug mode, the secret key, and a
lot of very similar things.
The way Flask is designed usually requires the configuration to be
available when the application starts up. You can either hardcode the
configuration in the code which for many small applications is not
available when the application starts up. You can hardcode the
configuration in the code, which for many small applications is not
actually that bad, but there are better ways.
Independent of how you load your config, there is a config object
@ -59,13 +59,48 @@ The following configuration values are used internally by Flask:
``PERMANENT_SESSION_LIFETIME`` the lifetime of a permanent session as
:class:`datetime.timedelta` object.
``USE_X_SENDFILE`` enable/disable x-sendfile
``LOGGER_NAME`` the name of the logger
``SERVER_NAME`` the name of the server. Required for
subdomain support (e.g.: ``'localhost'``)
``MAX_CONTENT_LENGTH`` If set to a value in bytes, Flask will
reject incoming requests with a
content length greater than this by
returning a 413 status code.
=============================== =========================================
.. admonition:: More on ``SERVER_NAME``
The ``SERVER_NAME`` key is used for the subdomain support. Because
Flask cannot guess the subdomain part without the knowledge of the
actual server name, this is required if you want to work with
subdomains. This is also used for the session cookie.
Please keep in mind that not only Flask has the problem of not knowing
what subdomains are, your web browser does as well. Most modern web
browsers will not allow cross-subdomain cookies to be set on a
server name without dots in it. So if your server name is
``'localhost'`` you will not be able to set a cookie for
``'localhost'`` and every subdomain of it. Please chose a different
server name in that case, like ``'myapplication.local'`` and add
this name + the subdomains you want to use into your host config
or setup a local `bind`_.
.. _bind: https://www.isc.org/software/bind
.. versionadded:: 0.4
``LOGGER_NAME``
.. versionadded:: 0.5
``SERVER_NAME``
.. versionadded:: 0.6
``MAX_CONTENT_LENGTH``
Configuring from Files
----------------------
Configuration becomes more useful if you can configure from a file. And
ideally that file would be outside of the actual application package that
Configuration becomes more useful if you can configure from a file, and
ideally that file would be outside of the actual application package so that
you can install the package with distribute (:ref:`distribute-deployment`)
and still modify that file afterwards.
@ -75,7 +110,7 @@ So a common pattern is this::
app.config.from_object('yourapplication.default_settings')
app.config.from_envvar('YOURAPPLICATION_SETTINGS')
What this does is first loading the configuration from the
This first loads the configuration from the
`yourapplication.default_settings` module and then overrides the values
with the contents of the file the :envvar:`YOURAPPLICATION_SETTINGS`
environment variable points to. This environment variable can be set on
@ -95,7 +130,7 @@ The configuration files themselves are actual Python files. Only values
in uppercase are actually stored in the config object later on. So make
sure to use uppercase letters for your config keys.
Here an example configuration file::
Here is an example configuration file::
DEBUG = False
SECRET_KEY = '?\xbf,\xb4\x8d\xa3"<\x9c\xb0@\x0f5\xab,w\xee\x8d$0\x13\x8b83'
@ -123,3 +158,71 @@ experience:
2. Do not write code that needs the configuration at import time. If you
limit yourself to request-only accesses to the configuration you can
reconfigure the object later on as needed.
Development / Production
------------------------
Most applications need more than one configuration. There will at least
be a separate configuration for a production server and one used during
development. The easiest way to handle this is to use a default
configuration that is always loaded and part of version control, and a
separate configuration that overrides the values as necessary as mentioned
in the example above::
app = Flask(__name__)
app.config.from_object('yourapplication.default_settings')
app.config.from_envvar('YOURAPPLICATION_SETTINGS')
Then you just have to add a separate `config.py` file and export
``YOURAPPLICATION_SETTINGS=/path/to/config.py`` and you are done. However
there are alternative ways as well. For example you could use imports or
subclassing.
What is very popular in the Django world is to make the import explicit in
the config file by adding an ``from yourapplication.default_settings
import *`` to the top of the file and then overriding the changes by hand.
You could also inspect an environment variable like
``YOURAPPLICATION_MODE`` and set that to `production`, `development` etc
and import different hardcoded files based on that.
An interesting pattern is also to use classes and inheritance for
configuration::
class Config(object):
DEBUG = False
TESTING = False
DATABASE_URI = 'sqlite://:memory:'
class ProductionConfig(Config):
DATABASE_URI = 'mysql://user@localhost/foo'
class DevelopmentConfig(Config):
DEBUG = True
class TestinConfig(Config):
TESTING = True
To enable such a config you just have to call into
:meth:`~flask.Config.from_object`::
app.config.from_object('configmodule.ProductionConfig')
There are many different ways and it's up to you how you want to manage
your configuration files. However here a list of good recommendations:
- keep a default configuration in version control. Either populate the
config with this default configuration or import it in your own
configuration files before overriding values.
- use an environment variable to switch between the configurations.
This can be done from outside the Python interpreter and makes
development and deployment much easier because you can quickly and
easily switch between different configs without having to touch the
code at all. If you are working often on different projects you can
even create your own script for sourcing that activates a virtualenv
and exports the development configuration for you.
- Use a tool like `fabric`_ in production to push code and
configurations separately to the production server(s). For some
details about how to do that, head over to the :ref:`deploy` pattern.
.. _fabric: http://fabfile.org/

9
docs/contents.rst.inc
View file

@ -1,9 +1,9 @@
User's Guide
------------
This part of the documentation is written text and should give you an idea
how to work with Flask. It's a series of step-by-step instructions for
web development.
This part of the documentation, which is mostly prose, begins with some
background information about Flask, then focuses on step-by-step
instructions for web development with Flask.
.. toctree::
:maxdepth: 2
@ -12,9 +12,11 @@ web development.
installation
quickstart
tutorial/index
templating
testing
errorhandling
config
signals
shell
patterns/index
deploying/index
@ -44,6 +46,7 @@ Design notes, legal information and changelog are here for the interested.
security
unicode
extensiondev
styleguide
upgrading
changelog
license

2
docs/deploying/cgi.rst
View file

@ -38,7 +38,7 @@ Server Setup
------------
Usually there are two ways to configure the server. Either just copy the
`.cgi` into a `cgi-bin` (and use `mod_rerwite` or something similar to
`.cgi` into a `cgi-bin` (and use `mod_rewrite` or something similar to
rewrite the URL) or let the server point to the file directly.
In Apache for example you can put a like like this into the config:

2
docs/deploying/fastcgi.rst
View file

@ -123,7 +123,7 @@ webserver user is `www-data`::
$ cd /var/www/yourapplication
$ python application.fcgi
Traceback (most recent call last):
File "yourapplication.fcg", line 4, in <module>
File "yourapplication.fcgi", line 4, in <module>
ImportError: No module named yourapplication
In this case the error seems to be "yourapplication" not being on the python

35
docs/deploying/mod_wsgi.rst
View file

@ -1,3 +1,5 @@
.. _mod_wsgi-deployment:
mod_wsgi (Apache)
=================
@ -91,8 +93,8 @@ For more information consult the `mod_wsgi wiki`_.
.. _virtual python: http://pypi.python.org/pypi/virtualenv
.. _mod_wsgi wiki: http://code.google.com/p/modwsgi/wiki/
Toubleshooting
--------------
Troubleshooting
---------------
If your application does not run, follow this guide to troubleshoot:
@ -133,3 +135,32 @@ If your application does not run, follow this guide to troubleshoot:
The reason for this is that for non-installed packages, the module
filename is used to locate the resources and for symlinks the wrong
filename is picked up.
Support for Automatic Reloading
-------------------------------
To help deployment tools you can activate support for automatic reloading.
Whenever something changes the `.wsgi` file, `mod_wsgi` will reload all
the daemon processes for us.
For that, just add the following directive to your `Directory` section:
.. sourcecode:: apache
WSGIScriptReloading On
Working with Virtual Environments
---------------------------------
Virtual environments have the advantage that they never install the
required dependencies system wide so you have a better control over what
is used where. If you want to use a virtual environment with mod_wsgi you
have to modify your `.wsgi` file slightly.
Add the following lines to the top of your `.wsgi` file::
activate_this = '/path/to/env/bin/activate_this.py'
execfile(activate_this, dict(__file__=activate_this))
This sets up the load paths according to the settings of the virtual
environment. Keep in mind that the path has to be absolute.

35
docs/deploying/others.rst
View file

@ -61,3 +61,38 @@ and `greenlet`_. Running a Flask application on this server is quite simple::
.. _eventlet: http://eventlet.net/
.. _greenlet: http://codespeak.net/py/0.9.2/greenlet.html
Proxy Setups
------------
If you deploy your application behind an HTTP proxy you will need to
rewrite a few headers in order for the application to work. The two
problematic values in the WSGI environment usually are `REMOTE_ADDR` and
`HTTP_HOST`. Werkzeug ships a fixer that will solve some common setups,
but you might want to write your own WSGI middleware for specific setups.
The most common setup invokes the host being set from `X-Forwarded-Host`
and the remote address from `X-Forward-For`::
from werkzeug.contrib.fixers import ProxyFix
app.wsgi_app = ProxyFix(app.wsgi_app)
Please keep in mind that it is a security issue to use such a middleware
in a non-proxy setup because it will blindly trust the incoming
headers which might be forged by malicious clients.
If you want to rewrite the headers from another header, you might want to
use a fixer like this::
class CustomProxyFix(object):
def __init__(self, app):
self.app = app
def __call__(self, environ, start_response):
host = environ.get('HTTP_X_FHOST', '')
if host:
environ['HTTP_HOST'] = host
return self.app(environ, start_response)
app.wsgi_app = CustomProxyFix(app.wsgi_app)

6
docs/design.rst
View file

@ -1,3 +1,5 @@
.. _design:
Design Decisions in Flask
=========================
@ -109,6 +111,10 @@ 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.
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.
Micro with Dependencies
-----------------------

45
docs/errorhandling.rst
View file

@ -5,7 +5,7 @@ Handling Application Errors
.. versionadded:: 0.3
Applications fail, server fail. Sooner or later you will see an exception
Applications fail, servers fail. Sooner or later you will see an exception
in production. Even if your code is 100% correct, you will still see
exceptions from time to time. Why? Because everything else involved will
fail. Here some situations where perfectly fine code can lead to server
@ -20,7 +20,7 @@ errors:
- a programming error in a library you are using
- network connection of the server to another system failed.
And that's just a small sample of issues you could be facing. So how to
And that's just a small sample of issues you could be facing. So how do we
deal with that sort of problem? By default if your application runs in
production mode, Flask will display a very simple page for you and log the
exception to the :attr:`~flask.Flask.logger`.
@ -32,10 +32,10 @@ Error Mails
-----------
If the application runs in production mode (which it will do on your
server) you won't see any log messages by default. Why that? Flask tries
to be a zero-configuration framework and where should it drop the logs for
you if there is no configuration. Guessing is not a good idea because
chances are, the place it guessed is not the place where the user has the
server) you won't see any log messages by default. Why is that? Flask
tries to be a zero-configuration framework. Where should it drop the logs
for you if there is no configuration? Guessing is not a good idea because
chances are, the place it guessed is not the place where the user has
permission to create a logfile. Also, for most small applications nobody
will look at the logs anyways.
@ -45,9 +45,9 @@ when a user reported it for you. What you want instead is a mail the
second the exception happened. Then you get an alert and you can do
something about it.
Flask is using the Python builtin logging system and that one can actually
send you mails for errors which is probably what you want. Here is how
you can configure the Flask logger to send you mails for exceptions::
Flask uses the Python builtin logging system, and it can actually send
you mails for errors which is probably what you want. Here is how you can
configure the Flask logger to send you mails for exceptions::
ADMINS = ['yourname@example.com']
if not app.debug:
@ -63,16 +63,17 @@ So what just happened? We created a new
:class:`~logging.handlers.SMTPHandler` that will send mails with the mail
server listening on ``127.0.0.1`` to all the `ADMINS` from the address
*server-error@example.com* with the subject "YourApplication Failed". If
your mail server requires credentials these can also provided, for that
check out the documentation for the :class:`~logging.handlers.SMTPHandler`.
your mail server requires credentials, these can also be provided. For
that check out the documentation for the
:class:`~logging.handlers.SMTPHandler`.
We also tell the handler to only send errors and more critical messages.
Because we certainly don't want to get a mail for warnings or other
useless logs that might happen during request handling.
Before you run that in production, please also look at :ref:`log-format`
to put more information into that error mail. That will save you from a
lot of frustration.
Before you run that in production, please also look at :ref:`logformat` to
put more information into that error mail. That will save you from a lot
of frustration.
Logging to a File
@ -88,7 +89,7 @@ There are a couple of handlers provided by the logging system out of the
box but not all of them are useful for basic error logging. The most
interesting are probably the following:
- :class:`~logging.handlers.FileHandler` - logs messages to a file on the
- :class:`~logging.FileHandler` - logs messages to a file on the
filesystem.
- :class:`~logging.handlers.RotatingFileHandler` - logs messages to a file
on the filesystem and will rotate after a certain number of messages.
@ -104,23 +105,23 @@ above, just make sure to use a lower setting (I would recommend
if not app.debug:
import logging
from logging.handlers import TheHandlerYouWant
from themodule import TheHandler YouWant
file_handler = TheHandlerYouWant(...)
file_handler.setLevel(logging.WARNING)
app.logger.addHandler(file_handler)
.. _log-format:
.. _logformat:
Controlling the Log Format
--------------------------
By default a handler will only write the message string into a file or
send you that message as mail. But a log record stores more information
send you that message as mail. A log record stores more information,
and it makes a lot of sense to configure your logger to also contain that
information so that you have a better idea of why that error happened, and
more importantly, where it did.
A formatter can be instanciated with a format string. Note that
A formatter can be instantiated with a format string. Note that
tracebacks are appended to the log entry automatically. You don't have to
do that in the log formatter format string.
@ -206,7 +207,7 @@ formatter. The formatter has three interesting methods:
called for `asctime` formatting. If you want a different time format
you can override this method.
:meth:`~logging.Formatter.formatException`
called for exception formatting. It is passed a :attr:`~sys.exc_info`
called for exception formatting. It is passed an :attr:`~sys.exc_info`
tuple and has to return a string. The default is usually fine, you
don't have to override it.
@ -217,8 +218,8 @@ Other Libraries
---------------
So far we only configured the logger your application created itself.
Other libraries might log themselves as well. For example, SQLAlchemy use
logging heavily in the core. While there is a method to configure all
Other libraries might log themselves as well. For example, SQLAlchemy uses
logging heavily in its core. While there is a method to configure all
loggers at once in the :mod:`logging` package, I would not recommend using
it. There might be a situation in which you want to have multiple
separate applications running side by side in the same Python interpreter

65
docs/extensiondev.rst
View file

@ -67,7 +67,7 @@ First we create the following folder structure::
setup.py
LICENSE
Here the contents of the most important files:
Here's the contents of the most important files:
flaskext/__init__.py
````````````````````
@ -153,7 +153,7 @@ There are two recommended ways for an extension to initialize:
initialization functions:
If your extension is called `helloworld` you might have a function
called ``init_helloworld(app[, extra_args])`` that initalizes the
called ``init_helloworld(app[, extra_args])`` that initializes the
extension for that application. It could attach before / after
handlers etc.
@ -171,7 +171,7 @@ controller object that can be used to connect to the database.
The Extension Code
------------------
Here the contents of the `flaskext/sqlite3.py` for copy/paste::
Here's the contents of the `flaskext/sqlite3.py` for copy/paste::
from __future__ import absolute_import
import sqlite3
@ -196,7 +196,7 @@ Here the contents of the `flaskext/sqlite3.py` for copy/paste::
g.sqlite3_db.close()
return response
So here what the lines of code do:
So here's what the lines of code do:
1. the ``__future__`` import is necessary to activate absolute imports.
This is needed because otherwise we could not call our module
@ -237,7 +237,7 @@ If you don't need that, you can go with initialization functions.
Initialization Functions
------------------------
Here how the module would look like with initialization functions::
Here's what the module would look like with initialization functions::
from __future__ import absolute_import
import sqlite3
@ -264,9 +264,60 @@ development. If you want to learn more, it's a very good idea to check
out existing extensions on the `Flask Extension Registry`_. If you feel
lost there is still the `mailinglist`_ and the `IRC channel`_ to get some
ideas for nice looking APIs. Especially if you do something nobody before
you did, it might be a very good idea to get some more input.
you did, it might be a very good idea to get some more input. This not
only to get an idea about what people might want to have from an
extension, but also to avoid having multiple developers working on pretty
much the same side by side.
Remember: good API design is hard :(
Remember: good API design is hard, so introduce your project on the
mailinglist, and let other developers give you a helping hand with
designing the API.
The best Flask extensions are extensions that share common idioms for the
API. And this can only work if collaboration happens early.
Approved Extensions
-------------------
Flask also has the concept of approved extensions. Approved extensions
are tested as part of Flask itself to ensure extensions do not break on
new releases. These approved extensions are listed on the `Flask
Extension Registry`_ and marked appropriately. If you want your own
extension to be approved you have to follow these guidelines:
1. An approved Flask extension must provide exactly one package or module
inside the `flaskext` namespace package.
2. It must ship a testsuite that can either be invoked with ``make test``
or ``python setup.py test``. For testsuites invoked with ``make
test`` the extension has to ensure that all dependencies for the test
are installed automatically, in case of ``python setup.py test``
dependencies for tests alone can be specified in the `setup.py`
file. The testsuite also has to be part of the distribution.
3. APIs of approved extensions will be checked for the following
characteristics:
- an approved extension has to support multiple applications
running in the same Python process.
- it must be possible to use the factory pattern for creating
applications.
4. The license must be BSD/MIT/WTFPL licensed.
5. The naming scheme for official extensions is *Flask-ExtensionName* or
*ExtensionName-Flask*.
6. Approved extensions must define all their dependencies in the
`setup.py` file unless a dependency cannot be met because it is not
available on PyPI.
7. The extension must have documentation that uses one of the two Flask
themes for Sphinx documentation.
8. The setup.py description (and thus the PyPI description) has to
link to the documentation, website (if there is one) and there
must be a link to automatically install the development version
(``PackageName==dev``).
9. The ``zip_safe`` flag in the setup script must be set to ``False``,
even if the extension would be safe for zipping.
10. An extension currently has to support Python 2.5, 2.6 as well as
Python 2.7
.. _Flask Extension Wizard:

134
docs/foreword.rst
View file

@ -2,90 +2,108 @@ Foreword
========
Read this before you get started with Flask. This hopefully answers some
questions about the intention of the project, what it aims at and when you
questions about the purpose and goals of the project, and when you
should or should not be using it.
What does Micro Mean?
---------------------
What does "micro" mean?
-----------------------
The micro in microframework for me means on the one hand being small in
size and complexity but on the other hand also that the complexity of the
applications that are written with these frameworks do not exceed a
certain size. A microframework like Flask sacrifices a few things in
order to be approachable and to be as concise as possible.
To me, the "micro" in microframework refers not only to the simplicity and
small size of the framework, but also to the typically limited complexity
and size of applications that are written with the framework. Also the
fact that you can have an entire application in a single Python file. To
be approachable and concise, a microframework sacrifices a few features
that may be necessary in larger or more complex applications.
For example Flask uses thread local objects internally so that you don't
For example, Flask uses thread-local objects internally so that you don't
have to pass objects around from function to function within a request in
order to stay threadsafe. While this is a really easy approach and saves
you a lot of time, it also does not scale well to large applications.
It's especially painful for more complex unittests and when you suddenly
have to deal with code being executed outside of the context of a request
(for example if you have cronjobs).
you a lot of time, it might also cause some troubles for very large
applications because changes on these thread-local objects can happen
anywhere in the same thread.
Flask provides some tools to deal with the downsides of this approach but
the core problem of this approach obviously stays. It is also based on
convention over configuration which means that a lot of things are
preconfigured in Flask and will work well for smaller applications but not
so much for larger ones (where and how it looks for templates, static
files etc.)
it might be an issue for larger applications because in theory
modifications on these objects might happen anywhere in the same thread.
But don't worry if your application suddenly grows larger than it was
initially and you're afraid Flask might not grow with it. Even with
larger frameworks you sooner or later will find out that you need
something the framework just cannot do for you without modification.
If you are ever in that situation, check out the :ref:`becomingbig`
chapter.
Flask is also based on convention over configuration, which means that
many things are preconfigured. For example, by convention, templates and
static files are in subdirectories within the Python source tree of the
application.
A Framework and An Example
The main reason however why Flask is called a "microframework" is the idea
to keep the core simple but extensible. There is database abstraction
layer, no form validation or anything else where different libraries
already exist that can handle that. However Flask knows the concept of
extensions that can add this functionality into your application as if it
was implemented in Flask itself. There are currently extensions for
object relational mappers, form validation, upload handling, various open
authentication technologies and more.
However Flask is not much code and it is built on a very solid foundation
and with that it is very easy to adapt for large applications. If you are
interested in that, check out the :ref:`becomingbig` chapter.
If you are curious about the Flask design principles, head over to the
section about :ref:`design`.
A Framework and an Example
--------------------------
Flask is not only a microframework, it is also an example. Based on
Flask is not only a microframework; it is also an example. Based on
Flask, there will be a series of blog posts that explain how to create a
framework. Flask itself is just one way to implement a framework on top
of existing libraries. Unlike many other microframeworks Flask does not
try to implement anything on its own, it reuses existing code.
of existing libraries. Unlike many other microframeworks, Flask does not
try to implement everything on its own; it reuses existing code.
Web Development is Dangerous
----------------------------
I'm not even joking. Well, maybe a little. If you write a web
application you are probably allowing users to register and leave their
I'm not joking. Well, maybe a little. If you write a web
application, you are probably allowing users to register and leave their
data on your server. The users are entrusting you with data. And even if
you are the only user that might leave data in your application, you still
want that data to be stored in a secure manner.
want that data to be stored securely.
Unfortunately there are many ways security of a web application can be
Unfortunately, there are many ways the security of a web application can be
compromised. Flask protects you against one of the most common security
problems of modern web applications: cross site scripting (XSS). Unless
you deliberately mark insecure HTML as secure Flask (and the underlying
Jinja2 template engine) have you covered. But there are many more ways to
problems of modern web applications: cross-site scripting (XSS). Unless
you deliberately mark insecure HTML as secure, Flask and the underlying
Jinja2 template engine have you covered. But there are many more ways to
cause security problems.
Whenever something is dangerous where you have to watch out, the
documentation will tell you so. Some of the security concerns of web
development are far more complex than one might think and often we all end
up in situations where we think "well, this is just far fetched, how could
that possibly be exploited" and then an intelligent guy comes along and
figures a way out to exploit that application. And don't think, your
application is not important enough for hackers to take notice. Depending
on the kind of attack, chances are there are automated botnets out there
trying to figure out how to fill your database with viagra advertisements.
The documentation will warn you about aspects of web development that
require attention to security. Some of these security concerns
are far more complex than one might think, and we all sometimes underestimate
the likelihood that a vulnerability will be exploited, until a clever
attacker figures out a way to exploit our applications. And don't think
that your application is not important enough to attract an attacker.
Depending on the kind of attack, chances are that automated bots are
probing for ways to fill your database with spam, links to malicious
software, and the like.
So always keep that in mind when doing web development.
So always keep security in mind when doing web development.
Target Audience
---------------
The Status of Python 3
----------------------
Is Flask for you? If your application small-ish and does not depend on
too complex database structures, Flask is the Framework for you. It was
designed from the ground up to be easy to use, based on established
principles, good intentions and on top of two established libraries in
widespread usage. Recent versions of Flask scale nicely within reasonable
bounds and if you grow larger, you won't have any troubles adjusting Flask
for your new application size.
Currently the Python community is in the process of improving libraries to
support the new iteration of the Python programming language.
Unfortunately there are a few problems with Python 3, namely the missing
consent on what WSGI for Python 3 should look like. These problems are
partially caused by changes in the language that went unreviewed for too
long, also partially the ambitions of everyone involved to drive the WSGI
standard forward.
If you suddenly discover that your application grows larger than
originally intended, head over to the :ref:`becomingbig` section to see
some possible solutions for larger applications.
Because of that we strongly recommend against using Python 3 for web
development of any kind and wait until the WSGI situation is resolved.
You will find a couple of frameworks and web libraries on PyPI that claim
Python 3 support, but this support is based on the broken WSGI
implementation provided by Python 3.0 and 3.1 which will most likely
change in the near future.
Satisfied? Then head over to the :ref:`installation`.
Werkzeug and Flask will be ported to Python 3 as soon as a solution for
WSGI is found, and we will provide helpful tips how to upgrade existing
applications to Python 3. Until then, we strongly recommend using Python
2.6 and 2.7 with activated Python 3 warnings during development, as well
as the unicode literals `__future__` feature.

2
docs/htmlfaq.rst
View file

@ -130,7 +130,7 @@ supported by browsers:
- Wrapping the document in an ``<html>`` tag
- Wrapping header elements in ``<head>`` or the body elements in
``<body>``
- Closing the ``<p>``, ``<li>``, ``<dl>``, ``<dd>``, ``<tr>``,
- Closing the ``<p>``, ``<li>``, ``<dt>``, ``<dd>``, ``<tr>``,
``<td>``, ``<th>``, ``<tbody>``, ``<thead>``, or ``<tfoot>`` tags.
- Quoting attributes, so long as they contain no whitespace or
special characters (like ``<``, ``>``, ``'``, or ``"``).

14
docs/index.rst
View file

@ -4,20 +4,20 @@ Welcome to Flask
================
.. image:: _static/logo-full.png
:alt: The Flask Logo with Subtitle
:alt: Flask: web development, one drop at a time
:class: floatingflask
Welcome to Flask's documentation. This documentation is divided in
different parts. I would suggest to get started with the
:ref:`installation` and then heading over to the :ref:`quickstart`.
Welcome to Flask's documentation. This documentation is divided into
different parts. I recommend that you get started with
:ref:`installation` and then head over to the :ref:`quickstart`.
Besides the quickstart there is also a more detailed :ref:`tutorial` that
shows how to create a complete (albeit small) application with Flask. If
you rather want to dive into all the internal parts of Flask, check out
you'd rather dive into the internals of Flask, check out
the :ref:`api` documentation. Common patterns are described in the
:ref:`patterns` section.
Flask also depends on two external libraries: the `Jinja2`_ template
engine and the `Werkzeug`_ WSGI toolkit. both of which are not documented
Flask depends on two external libraries: the `Jinja2`_ template
engine and the `Werkzeug`_ WSGI toolkit. These libraries are not documented
here. If you want to dive into their documentation check out the
following links:

142
docs/installation.rst
View file

@ -3,44 +3,46 @@
Installation
============
Flask is a microframework and yet it depends on external libraries. There
are various ways how you can install that library and this explains each
way and why there are multiple ways.
Flask depends on two external libraries: `Werkzeug
Flask depends on two external libraries, `Werkzeug
<http://werkzeug.pocoo.org/>`_ and `Jinja2 <http://jinja.pocoo.org/2/>`_.
The first one is responsible for interfacing WSGI the latter for rendering
templates. Now you are maybe asking, what is WSGI? WSGI is a standard
in Python that is basically responsible for ensuring that your application
is behaving in a specific way so that you can run it on different
environments (for example on a local development server, on an Apache2, on
lighttpd, on Google's App Engine or whatever you have in mind).
Werkzeug is a toolkit for WSGI, the standard Python interface between web
applications and a variety of servers for both development and deployment.
Jinja2 renders templates.
So how do you get all that on your computer in no time? The most kick-ass
method is virtualenv, so let's look at that first.
So how do you get all that on your computer quickly? There are many ways
which this section will explain, but the most kick-ass method is
virtualenv, so let's look at that first.
Either way, you will need Python 2.5 or higher to get started, so be sure
to have an up to date Python 2.x installation. At the time of writing,
the WSGI specification is not yet finalized for Python 3, so Flask cannot
support the 3.x series of Python.
.. _virtualenv:
virtualenv
----------
Virtualenv is what you want to use during development and in production if
you have shell access. So first: what does virtualenv do? If you are
like me and you like Python, chances are you want to use it for another
project as well. Now the more projects you have, the more likely it is
that you will be working with different versions of Python itself or at
least an individual library. Because let's face it: quite often libraries
break backwards compatibility and it's unlikely that your application will
not have any dependencies, that just won't happen. So virtualenv to the
rescue!
Virtualenv is probably what you want to use during development, and in
production too if you have shell access there.
It basically makes it possible to have multiple side-by-side
"installations" of Python, each for your own project. It's not actually
an installation but a clever way to keep things separated.
What problem does virtualenv solve? If you like Python as I do,
chances are you want to use it for other projects besides Flask-based
web applications. But the more projects you have, the more likely it is
that you will be working with different versions of Python itself, or at
least different versions of Python libraries. Let's face it; quite often
libraries break backwards compatibility, and it's unlikely that any serious
application will have zero dependencies. So what do you do if two or more
of your projects have conflicting dependencies?
So let's see how that works!
Virtualenv to the rescue! It basically enables multiple side-by-side
installations of Python, one for each project. It doesn't actually
install separate copies of Python, but it does provide a clever way
to keep different project environments isolated.
If you are on OS X or Linux chances are that one of the following two
So let's see how virtualenv works!
If you are on Mac OS X or Linux, chances are that one of the following two
commands will work for you::
$ sudo easy_install virtualenv
@ -49,18 +51,19 @@ or even better::
$ sudo pip install virtualenv
Chances are you have virtualenv installed on your system then. Maybe it's
even in your package manager (on ubuntu try ``sudo apt-get install
python-virtualenv``).
One of these will probably install virtualenv on your system. Maybe it's
even in your package manager. If you use Ubuntu, try::
If you are on Windows and missing the `easy_install` command you have to
$ sudo apt-get install python-virtualenv
If you are on Windows and don't have the `easy_install` command, you must
install it first. Check the :ref:`windows-easy-install` section for more
information about how to do that. Once you have it installed, run the
same commands as above, but without the `sudo` part.
same commands as above, but without the `sudo` prefix.
So now that you have virtualenv running just fire up a shell and create
your own environment. I usually create a folder and a `env` folder
within::
Once you have virtualenv installed, just fire up a shell and create
your own environment. I usually create a project folder and an `env`
folder within::
$ mkdir myproject
$ cd myproject
@ -68,14 +71,14 @@ within::
New python executable in env/bin/python
Installing setuptools............done.
Now you only have to activate it, whenever you work with it. On OS X and
Linux do the following::
Now, whenever you want to work on a project, you only have to activate
the corresponding environment. On OS X and Linux, do the following::
$ . env/bin/activate
(Note the whitespace between the dot and the script name. This means
execute this file in context of the shell. If the dot does not work for
whatever reason in your shell, try substituting it with ``source``)
(Note the space between the dot and the script name. The dot means that
this script should run in the context of the current shell. If this command
does not work in your shell, try replacing the dot with ``source``)
If you are a Windows user, the following command is for you::
@ -95,23 +98,22 @@ A few seconds later you are good to go.
System Wide Installation
------------------------
This is possible as well, but I would not recommend it. Just run
This is possible as well, but I do not recommend it. Just run
`easy_install` with root rights::
sudo easy_install Flask
$ sudo easy_install Flask
(Run it in an Admin shell on Windows systems and without the `sudo`).
(Run it in an Admin shell on Windows systems and without `sudo`).
Living on the Edge
------------------
You want to work with the latest version of Flask, there are two ways: you
can either let `easy_install` pull in the development version or tell it
to operate on a git checkout. Either way it's recommended to do that in a
virtualenv.
If you want to work with the latest version of Flask, there are two ways: you
can either let `easy_install` pull in the development version, or tell it
to operate on a git checkout. Either way, virtualenv is recommended.
Get the git checkout in a new virtualenv and run in develop mode::
Get the git checkout in a new virtualenv and run in development mode::
$ git clone http://github.com/mitsuhiko/flask.git
Initialized empty Git repository in ~/dev/flask/.git/
@ -124,9 +126,9 @@ Get the git checkout in a new virtualenv and run in develop mode::
...
Finished processing dependencies for Flask
This will pull in the dependencies and activate the git head as current
version. Then you just have to ``git pull origin`` to get the latest
version.
This will pull in the dependencies and activate the git head as the current
version inside the virtualenv. Then you just have to ``git pull origin``
to get the latest version.
To just get the development version without git, do this instead::
@ -145,31 +147,29 @@ To just get the development version without git, do this instead::
`easy_install` on Windows
-------------------------
On Windows installation of `easy_install` is a little bit tricker because
on Windows slightly different rules apply, but it's not a biggy. The
easiest way to accomplish that is downloading the `ez_setup.py`_ file and
running it. (Double clicking should do the trick)
On Windows, installation of `easy_install` is a little bit tricker because
slightly different rules apply on Windows than on Unix-like systems, but
it's not difficult. The easiest way to do it is to download the
`ez_setup.py`_ file and run it. The easiest way to run the file is to
open your downloads folder and double-click on the file.
Once you have done that it's important to add the `easy_install` command
and other Python scripts to the path. To do that you have to add the
Python installation's Script folder to the `PATH` variable.
To do that, right-click on your "Computer" desktop icon and click
"Properties". On Windows Vista and Windows 7 then click on "Advanced System
settings", on Windows XP click on the "Advanced" tab instead. Then click
Next, add the `easy_install` command and other Python scripts to the
command search path, by adding your Python installation's Scripts folder
to the `PATH` environment variable. To do that, right-click on the
"Computer" icon on the Desktop or in the Start menu, and choose
"Properties". Then, on Windows Vista and Windows 7 click on "Advanced System
settings"; on Windows XP, click on the "Advanced" tab instead. Then click
on the "Environment variables" button and double click on the "Path"
variable in the "System variables" section.
There append the path of your Python interpreter's Script folder to the
end of the last (make sure you delimit it from existing values with a
semicolon). Assuming you are using Python 2.6 on the default path, add
the following value::
variable in the "System variables" section. There append the path of your
Python interpreter's Scripts folder; make sure you delimit it from
existing values with a semicolon. Assuming you are using Python 2.6 on
the default path, add the following value::
;C:\Python26\Scripts
Then you are done. To check that it worked, open the cmd and execute
"easy_install". If you have UAC enabled it should prompt you for admin
privileges.
Then you are done. To check that it worked, open the Command Prompt and
execute ``easy_install``. If you have User Account Control enabled on
Windows Vista or Windows 7, it should prompt you for admin privileges.
.. _ez_setup.py: http://peak.telecommunity.com/dist/ez_setup.py

2
docs/license.rst
View file

@ -4,7 +4,7 @@ License
Flask is licensed under a three clause BSD License. It basically means:
do whatever you want with it as long as the copyright in Flask sticks
around, the conditions are not modified and the disclaimer is present.
Furthermore you must not use the names of the authors to promote derivates
Furthermore you must not use the names of the authors to promote derivatives
of the software without written consent.
The full license text can be found below (:ref:`flask-license`). For the

4
docs/patterns/distribute.rst
View file

@ -33,6 +33,10 @@ not supported by `distribute`_ so we will not bother with it. If you have
not yet converted your application into a package, head over to the
:ref:`larger-applications` pattern to see how this can be done.
A working deployment with distribute is the first step into more complex
and more automated deployment scenarios. If you want to fully automate
the process, also read the :ref:`fabric-deployment` chapter.
Basic Setup Script
------------------

6
docs/patterns/errorpages.rst
View file

@ -5,7 +5,7 @@ Flask comes with a handy :func:`~flask.abort` function that aborts a
request with an HTTP error code early. It will also provide a plain black
and white error page for you with a basic description, but nothing fancy.
Depening on the error code it is less or more likely for the user to
Depending on the error code it is less or more likely for the user to
actually see such an error.
Common Error Codes
@ -33,7 +33,7 @@ even if the application behaves correctly:
instead of 404. If you are not deleting documents permanently from
the database but just mark them as deleted, do the user a favour and
use the 410 code instead and display a message that what he was
looking for was deleted for all ethernity.
looking for was deleted for all eternity.
*500 Internal Server Error*
Usually happens on programming errors or if the server is overloaded.
@ -49,7 +49,7 @@ An error handler is a function, just like a view function, but it is
called when an error happens and is passed that error. The error is most
likely a :exc:`~werkzeug.exceptions.HTTPException`, but in one case it
can be a different error: a handler for internal server errors will be
passed other exception instances as well if they are uncought.
passed other exception instances as well if they are uncaught.
An error handler is registered with the :meth:`~flask.Flask.errorhandler`
decorator and the error code of the exception. Keep in mind that Flask

196
docs/patterns/fabric.rst Normal file
View file

@ -0,0 +1,196 @@
.. _fabric-deployment:
Deploying with Fabric
=====================
`Fabric`_ is a tool for Python similar to Makefiles but with the ability
to execute commands on a remote server. In combination with a properly
set up Python package (:ref:`larger-applications`) and a good concept for
configurations (:ref:`config`) it is very easy to deploy Flask
applications to external servers.
Before we get started, here a quick checklist of things we have to ensure
upfront:
- Fabric 1.0 has to be installed locally. This tutorial assumes the
latest version of Fabric.
- The application already has to be a package and requires a working
`setup.py` file (:ref:`distribute-deployment`).
- In the following example we are using `mod_wsgi` for the remote
servers. You can of course use your own favourite server there, but
for this example we chose Apache + `mod_wsgi` because it's very easy
to setup and has a simple way to reload applications without root
access.
Creating the first Fabfile
--------------------------
A fabfile is what controls what Fabric executes. It is named `fabfile.py`
and executed by the `fab` command. All the functions defined in that file
will show up as `fab` subcommands. They are executed on one or more
hosts. These hosts can be defined either in the fabfile or on the command
line. In this case we will add them to the fabfile.
This is a basic first example that has the ability to upload the current
sourcecode to the server and install it into a already existing
virtual environment::
from fabric.api import *
# the user to use for the remote commands
env.user = 'appuser'
# the servers where the commands are executed
env.hosts = ['server1.example.com', 'server2.example.com']
def pack():
# create a new source distribution as tarball
local('python setup.py sdist --formats=gztar', capture=False)
def deploy():
# figure out the release name and version
dist = local('python setup.py --fullname').strip()
# upload the source tarball to the temporary folder on the server
put('dist/%s.tar.gz' % dist, '/tmp/yourapplication.tar.gz')
# create a place where we can unzip the tarball, then enter
# that directory and unzip it
run('mkdir yourapplication')
with cd('/tmp/yourapplication'):
run('tar xzf /tmp/yourapplication.tar.gz')
# now setup the package with our virtual environment's
# python interpreter
run('/var/www/yourapplication/env/bin/python setup.py install')
# now that all is set up, delete the folder again
run('rm -rf /tmp/yourapplication /tmp/yourapplication.tar.gz')
# and finally touch the .wsgi file so that mod_wsgi triggers
# a reload of the application
run('touch /var/www/yourapplication.wsgi')
The example above is well documented and should be straightforward. Here
a recap of the most common commands fabric provides:
- `run` - executes a command on a remote server
- `local` - executes a command on the local machine
- `put` - uploads a file to the remote server
- `cd` - changes the directory on the serverside. This has to be used
in combination with the `with` statement.
Running Fabfiles
----------------
Now how do you execute that fabfile? You use the `fab` command. To
deploy the current version of the code on the remote server you would use
this command::
$ fab pack deploy
However this requires that our server already has the
``/var/www/yourapplication`` folder created and
``/var/www/yourapplication/env`` to be a virtual environment. Furthermore
are we not creating the configuration or `.wsgi` file on the server. So
how do we bootstrap a new server into our infrastructure?
This now depends on the number of servers we want to set up. If we just
have one application server (which the majority of applications will
have), creating a command in the fabfile for this is overkill. But
obviously you can do that. In that case you would probably call it
`setup` or `bootstrap` and then pass the servername explicitly on the
command line::
$ fab -H newserver.example.com bootstrap
To setup a new server you would roughly do these steps:
1. Create the directory structure in ``/var/www``::
$ mkdir /var/www/yourapplication
$ cd /var/www/yourapplication
$ virtualenv --distribute env
2. Upload a new `application.wsgi` file to the server and the
configuration file for the application (eg: `application.cfg`)
3. Create a new Apache config for `yourapplication` and activate it.
Make sure to activate watching for changes of the `.wsgi` file so
that we can automatically reload the application by touching it.
(See :ref:`mod_wsgi-deployment` for more information)
So now the question is, where do the `application.wsgi` and
`application.cfg` files come from?
The WSGI File
-------------
The WSGI file has to import the application and also to set an environment
variable so that the application knows where to look for the config. This
is a short example that does exactly that::
import os
os.environ['YOURAPPLICATION_CONFIG'] = '/var/www/yourapplication/application.cfg'
from yourapplication import app
The application itself then has to initialize itself like this to look for
the config at that environment variable::
app = Flask(__name__)
app.config.from_object('yourapplication.default_config')
app.config.from_envvar('YOURAPPLICATION_CONFIG')
This approach is explained in detail in the :ref:`config` section of the
documentation.
The Configuration File
----------------------
Now as mentioned above, the application will find the correct
configuration file by looking up the `YOURAPPLICATION_CONFIG` environment
variable. So we have to put the configuration in a place where the
application will able to find it. Configuration files have the unfriendly
quality of being different on all computers, so you do not version them
usually.
A popular approach is to store configuration files for different servers
in a separate version control repository and check them out on all
servers. Then symlink the file that is active for the server into the
location where it's expected (eg: ``/var/www/yourapplication``).
Either way, in our case here we only expect one or two servers and we can
upload them ahead of time by hand.
First Deployment
----------------
Now we can do our first deployment. We have set up the servers so that
they have their virtual environments and activated apache configs. Now we
can pack up the application and deploy it::
$ fab pack deploy
Fabric will now connect to all servers and run the commands as written
down in the fabfile. First it will execute pack so that we have our
tarball ready and then it will execute deploy and upload the source code
to all servers and install it there. Thanks to the `setup.py` file we
will automatically pull in the required libraries into our virtual
environment.
Next Steps
----------
From that point onwards there is so much that can be done to make
deployment actually fun:
- Create a `bootstrap` command that initializes new servers. It could
initialize a new virtual environment, setup apache appropriately etc.
- Put configuration files into a separate version control repository
and symlink the active configs into place.
- You could also put your application code into a repository and check
out the latest version on the server and then install. That way you
can also easily go back to older versions.
- hook in testing functionality so that you can deploy to an external
server and run the testsuite.
Working with Fabric is fun and you will notice that it's quite magical to
type ``fab deploy`` and see your application being deployed automatically
to one or more remote servers.
.. _Fabric: http://fabfile.org/

56
docs/patterns/fileuploads.rst
View file

@ -28,8 +28,6 @@ bootstrapping code for our application::
ALLOWED_EXTENSIONS = set(['txt', 'pdf', 'png', 'jpg', 'jpeg', 'gif'])
app = Flask(__name__)
app.add_url_rule('/uploads/<filename>', 'uploaded_file',
build_only=True)
So first we need a couple of imports. Most should be straightforward, the
:func:`werkzeug.secure_filename` is explained a little bit later. The
@ -43,9 +41,9 @@ the URL to these files.
Why do we limit the extensions that are allowed? You probably don't want
your users to be able to upload everything there if the server is directly
sending out the data to the client. That way you can make sure that users
are not able to upload HTML files that would cause XSS problems. Also
make sure to disallow `.php` files if the server executes them, but who
has PHP installed on his server, right? :)
are not able to upload HTML files that would cause XSS problems (see
:ref:`xss`). Also make sure to disallow `.php` files if the server
executes them, but who has PHP installed on his server, right? :)
Next the functions that check if an extension is valid and that uploads
the file and redirects the user to the URL for the uploaded file::
@ -100,14 +98,23 @@ before storing it directly on the filesystem.
>>> secure_filename('../../../../home/username/.bashrc')
'home_username_.bashrc'
Now if we run that application, you will notice that uploading works, but
you won't actually see that uploaded file. Well, you would have to
configure the server to serve that file for you. This is not handy for
development situations or when you are just too lazy to properly set up
the server. Would be nice to have the files still be available in that
situation, and that is really easy to do, just hook in a middleware::
Now one last thing is missing: the serving of the uploaded files. As of
Flask 0.5 we can use a function that does that for us::
from flask import send_from_directory
@app.route('/uploads/<filename>')
def uploaded_file(filename):
return send_from_directory(app.config['UPLOAD_FOLDER'],
filename)
Alternatively you can register `uploaded_file` as `build_only` rule and
use the :class:`~werkzeug.SharedDataMiddleware`. This also works with
older versions of Flask::
from werkzeug import SharedDataMiddleware
app.add_url_rule('/uploads/<filename>', 'uploaded_file',
build_only=True)
app.wsgi_app = SharedDataMiddleware(app.wsgi_app, {
'/uploads': UPLOAD_FOLDER
})
@ -118,27 +125,29 @@ If you now run the application everything should work as expected.
Improving Uploads
-----------------
.. versionadded:: 0.6
So how exactly does Flask handle uploads? Well it will store them in the
webserver's memory if the files are reasonable small otherwise in a
temporary location (as returned by :func:`tempfile.gettempdir`). But how
do you specify the maximum file size after which an upload is aborted? By
default Flask will happily accept file uploads to an unlimited amount of
memory, but you can limit that by subclassing the request and overriding
the Werkzeug provided :attr:`~werkzeug.BaseRequest.max_form_memory_size`
attribute::
memory, but you can limit that by setting the ``MAX_CONTENT_LENGTH``
config key::
from flask import Flask, Request
class LimitedRequest(Request):
max_form_memory_size = 16 * 1024 * 1024
app = Flask(__name__)
app.request_class = LimitedRequest
app.config['MAX_CONTENT_LENGTH'] = 16 * 1024 * 1024
The code above will limited the maximum allowed payload to 16 megabytes.
If a larger file is transmitted, Flask will raise an
:exc:`~werkzeug.exceptions.RequestEntityTooLarge` exception.
This feature was added in Flask 0.6 but can be achieved in older versions
as well by subclassing the request object. For more information on that
consult the Werkzeug documentation on file handling.
Upload Progress Bars
--------------------
@ -158,3 +167,14 @@ following libraries for some nice examples how to do that:
- `Plupload <http://www.plupload.com/>`_ - HTML5, Java, Flash
- `SWFUpload <http://www.swfupload.org/>`_ - Flash
- `JumpLoader <http://jumploader.com/>`_ - Java
An Easier Solution
------------------
Because the common pattern for file uploads exists almost unchanged in all
applications dealing with uploads, there is a Flask extension called
`Flask-Uploads`_ that implements a full fledged upload mechanism with
white and blacklisting of extensions and more.
.. _Flask-Uploads: http://packages.python.org/Flask-Uploads/

6
docs/patterns/flashing.rst
View file

@ -14,7 +14,7 @@ template that does this.
Simple Flashing
---------------
So here a full example::
So here is a full example::
from flask import flash, redirect, url_for, render_template
@ -30,7 +30,7 @@ So here a full example::
request.form['password'] != 'secret':
error = 'Invalid credentials'
else:
flash('You were sucessfully logged in')
flash('You were successfully logged in')
return redirect(url_for('index'))
return render_template('login.html', error=error)
@ -100,7 +100,7 @@ to the :func:`~flask.flash` function::
Inside the template you then have to tell the
:func:`~flask.get_flashed_messages` function to also return the
categories. The loop looks slighty different in that situation then:
categories. The loop looks slightly different in that situation then:
.. sourcecode:: html+jinja

2
docs/patterns/index.rst
View file

@ -19,6 +19,7 @@ Snippet Archives <http://flask.pocoo.org/snippets/>`_.
packages
appfactories
distribute
fabric
sqlite3
sqlalchemy
fileuploads
@ -30,3 +31,4 @@ Snippet Archives <http://flask.pocoo.org/snippets/>`_.
jquery
errorpages
lazyloading
mongokit

10
docs/patterns/jquery.rst
View file

@ -40,7 +40,7 @@ Another method is using Google's `AJAX Libraries API
In this case you don't have to put jQuery into your static folder, it will
instead be loaded from Google directly. This has the advantage that your
website will probably load faster for users if they were to at least one
website will probably load faster for users if they went to at least one
other website before using the same jQuery version from Google because it
will already be in the browser cache. Downside is that if you don't have
network connectivity during development jQuery will not load.
@ -53,8 +53,8 @@ is quite simple: it's on localhost port something and directly on the root
of that server. But what if you later decide to move your application to
a different location? For example to ``http://example.com/myapp``? On
the server side this never was a problem because we were using the handy
:func:`~flask.url_for` function that did could answer that question for
us, but if we are using jQuery we should better not hardcode the path to
:func:`~flask.url_for` function that could answer that question for
us, but if we are using jQuery we should not hardcode the path to
the application but make that dynamic, so how can we do that?
A simple method would be to add a script tag to our page that sets a
@ -118,9 +118,9 @@ special error reporting in that case.
The HTML
--------
You index.html template either has to extend a `layout.html` template with
Your index.html template either has to extend a `layout.html` template with
jQuery loaded and the `$SCRIPT_ROOT` variable set, or do that on the top.
Here the HTML code needed for our little application (`index.html`).
Here's the HTML code needed for our little application (`index.html`).
Notice that we also drop the script directly into the HTML here. It is
usually a better idea to have that in a separate script file:

4
docs/patterns/lazyloading.rst
View file

@ -74,7 +74,7 @@ function but internally imports the real function on first use::
return self.view(*args, **kwargs)
What's important here is is that `__module__` and `__name__` are properly
set. This is used by Flask internally to figure out how to do name the
set. This is used by Flask internally to figure out how to name the
URL rules in case you don't provide a name for the rule yourself.
Then you can define your central place to combine the views like this::
@ -100,5 +100,5 @@ name and a dot, and by wrapping `view_func` in a `LazyView` as needed::
url('/user/<username>', 'views.user')
One thing to keep in mind is that before and after request handlers have
to be in a file that is imported upfront to work propery on the first
to be in a file that is imported upfront to work properly on the first
request. The same goes for any kind of remaining decorator.

144
docs/patterns/mongokit.rst Normal file
View file

@ -0,0 +1,144 @@
.. mongokit-pattern:
MongoKit in Flask
=================
Using a document database rather than a full DBMS gets more common these days.
This pattern shows how to use MongoKit, a document mapper library, to
integrate with MongoDB.
This pattern requires a running MongoDB server and the MongoKit library
installed.
There are two very common ways to use MongoKit. I will outline each of them
here:
Declarative
-----------
The default behaviour of MongoKit is the declarative one that is based on
common ideas from Django or the SQLAlchemy declarative extension.
Here an example `app.py` module for your application::
from flask import Flask
from mongokit import Connection, Document
# configuration
MONGODB_HOST = 'localhost'
MONGODB_PORT = 27017
# create the little application object
app = Flask(__name__)
app.config.from_object(__name__)
# connect to the database
connection = Connection(app.config['MONGODB_HOST'],
app.config['MONGODB_PORT'])
To define your models, just subclass the `Document` class that is imported
from MongoKit. If you've seen the SQLAlchemy pattern you may wonder why we do
not have a session and even do not define a `init_db` function here. On the
one hand, MongoKit does not have something like a session. This sometimes
makes it more to type but also makes it blazingly fast. On the other hand,
MongoDB is schemaless. This means you can modify the data structure from one
insert query to the next without any problem. MongoKit is just schemaless
too, but implements some validation to ensure data integrity.
Here is an example document (put this also into `app.py`, e.g.)::
def max_length(length):
def validate(value):
if len(value) <= length:
return True
raise Exception('%s must be at most %s characters long' % length)
return validate
class User(Document):
structure = {
'name': unicode,
'email': unicode,
}
validators = {
'name': max_length(50),
'email': max_length(120)
}
use_dot_notation = True
def __repr__(self):
return '<User %r>' % (self.name)
# register the User document with our current connection
connection.register([User])
This example shows you how to define your schema (named structure), a
validator for the maximum character length and uses a special MongoKit feature
called `use_dot_notation`. Per default MongoKit behaves like a python
dictionary but with `use_dot_notation` set to `True` you can use your
documents like you use models in nearly any other ORM by using dots to
separate between attributes.
You can insert entries into the database like this:
>>> from yourapplication.database import connection
>>> from yourapplication.models import User
>>> collection = connection['test'].users
>>> user = collection.User()
>>> user['name'] = u'admin'
>>> user['email'] = u'admin@localhost'
>>> user.save()
Note that MongoKit is kinda strict with used column types, you must not use a
common `str` type for either `name` or `email` but unicode.
Querying is simple as well:
>>> list(collection.User.find())
[<User u'admin'>]
>>> collection.User.find_one({'name': u'admin'})
<User u'admin'>
.. _MongoKit: http://bytebucket.org/namlook/mongokit/
PyMongo Compatibility Layer
---------------------------
If you just want to use PyMongo, you can do that with MongoKit as well. You
may use this process if you need the best performance to get. Note that this
example does not show how to couple it with Flask, see the above MongoKit code
for examples::
from MongoKit import Connection
connection = Connection()
To insert data you can use the `insert` method. We have to get a
collection first, this is somewhat the same as a table in the SQL world.
>>> collection = connection['test'].users
>>> user = {'name': u'admin', 'email': u'admin@localhost'}
>>> collection.insert(user)
print list(collection.find())
print collection.find_one({'name': u'admin'})
MongoKit will automatically commit for us.
To query your database, you use the collection directly:
>>> list(collection.find())
[{u'_id': ObjectId('4c271729e13823182f000000'), u'name': u'admin', u'email': u'admin@localhost'}]
>>> collection.find_one({'name': u'admin'})
{u'_id': ObjectId('4c271729e13823182f000000'), u'name': u'admin', u'email': u'admin@localhost'}
These results are also dict-like objects:
>>> r = collection.find_one({'name': u'admin'})
>>> r['email']
u'admin@localhost'
For more information about MongoKit, head over to the
`website <http://bytebucket.org/namlook/mongokit/>`_.

89
docs/patterns/packages.rst
View file

@ -162,9 +162,14 @@ modules in the application (`__init__.py`) like this::
from yourapplication.views.frontend import frontend
app = Flask(__name__)
app.register_module(admin)
app.register_module(admin, url_prefix='/admin')
app.register_module(frontend)
We register the modules with the app so that it can add them to the
URL map for our application. Note the prefix argument to the admin
module: by default when we register a module, that module's end-points
will be registered on `/` unless we specify this argument.
So what is different when working with modules? It mainly affects URL
generation. Remember the :func:`~flask.url_for` function? When not
working with modules it accepts the name of the function as first
@ -197,3 +202,85 @@ did in the example above, or we just use the function name::
@frontend.route('/')
def index():
return "I'm the index"
.. _modules-and-resources:
Modules and Resources
---------------------
.. versionadded:: 0.5
If a module is located inside an actual Python package it may contain
static files and templates. Imagine you have an application like this::
/yourapplication
__init__.py
/apps
__init__.py
/frontend
__init__.py
views.py
/static
style.css
/templates
index.html
about.html
...
/admin
__init__.py
views.py
/static
style.css
/templates
list_items.html
show_item.html
...
The static folders automatically become exposed as URLs. For example if
the `admin` module is exported with an URL prefix of ``/admin`` you can
access the style css from its static folder by going to
``/admin/static/style.css``. The URL endpoint for the static files of the
admin would be ``'admin.static'``, similar to how you refer to the regular
static folder of the whole application as ``'static'``.
If you want to refer to the templates you just have to prefix it with the
name of the module. So for the admin it would be
``render_template('admin/list_items.html')`` and so on. It is not
possible to refer to templates without the prefixed module name. This is
explicit unlike URL rules.
You also need to explicitly pass the ``url_prefix`` argument when
registering your modules this way::
# in yourapplication/__init__.py
from flask import Flask
from yourapplication.apps.admin.views import admin
from yourapplication.apps.frontend.views import frontend
app = Flask(__name__)
app.register_module(admin, url_prefix='/admin')
app.register_module(frontend, url_prefix='/frontend')
This is because Flask cannot infer the prefix from the package names.
.. admonition:: References to Static Folders
Please keep in mind that if you are using unqualified endpoints by
default Flask will always assume the module's static folder, even if
there is no such folder.
If you want to refer to the application's static folder, use a leading
dot::
# this refers to the application's static folder
url_for('.static', filename='static.css')
# this refers to the current module's static folder
url_for('static', filename='static.css')
This is the case for all endpoints, not just static folders, but for
static folders it's more common that you will stumble upon this because
most applications will have a static folder in the application and not
a specific module.

18
docs/patterns/sqlalchemy.rst
View file

@ -8,9 +8,23 @@ encouraged to use a package instead of a module for your flask application
and drop the models into a separate module (:ref:`larger-applications`).
While that is not necessary, it makes a lot of sense.
There are three very common ways to use SQLAlchemy. I will outline each
There are four very common ways to use SQLAlchemy. I will outline each
of them here:
Flask-SQLAlchemy Extension
--------------------------
Because SQLAlchemy is a common database abstraction layer and object
relational mapper that requires a little bit of configuration effort,
there is a Flask extension that handles that for you. This is recommended
if you want to get started quickly.
You can download `Flask-SQLAlchemy`_ from `PyPI
<http://pypi.python.org/pypi/Flask-SQLAlchemy>`_.
.. _Flask-SQLAlchemy: http://packages.python.org/Flask-SQLAlchemy/
Declarative
-----------
@ -68,7 +82,7 @@ Here is an example model (put this into `models.py`, e.g.)::
self.email = email
def __repr__(self):
return '<User %r>' % (self.name, self.email)
return '<User %r>' % (self.name)
You can insert entries into the database like this:

10
docs/patterns/sqlite3.rst
View file

@ -3,12 +3,12 @@
Using SQLite 3 with Flask
=========================
In Flask you can implement opening of database connections at the beginning
of the request and closing at the end with the
In Flask you can implement the opening of database connections at the
beginning of the request and closing at the end with the
:meth:`~flask.Flask.before_request` and :meth:`~flask.Flask.after_request`
decorators in combination with the special :class:`~flask.g` object.
So here a simple example of how you can use SQLite 3 with Flask::
So here is a simple example of how you can use SQLite 3 with Flask::
import sqlite3
from flask import g
@ -33,7 +33,7 @@ Easy Querying
-------------
Now in each request handling function you can access `g.db` to get the
current open database connection. To simplify working with SQLite a
current open database connection. To simplify working with SQLite, a
helper function can be useful::
def query_db(query, args=(), one=False):
@ -61,7 +61,7 @@ Or if you just want a single result::
To pass variable parts to the SQL statement, use a question mark in the
statement and pass in the arguments as a list. Never directly add them to
the SQL statement with string formattings because this makes it possible
the SQL statement with string formatting because this makes it possible
to attack the application using `SQL Injections
<http://en.wikipedia.org/wiki/SQL_injection>`_.

8
docs/patterns/viewdecorators.rst
View file

@ -89,7 +89,7 @@ Here the code::
return decorated_function
return decorator
Notice that this assumes an instanciated `cache` object is available, see
Notice that this assumes an instantiated `cache` object is available, see
:ref:`caching-pattern` for more information.
@ -120,7 +120,9 @@ As you can see, if no template name is provided it will use the endpoint
of the URL map with dots converted to slashes + ``'.html'``. Otherwise
the provided template name is used. When the decorated function returns,
the dictionary returned is passed to the template rendering function. If
`None` is returned, an empty dictionary is assumed.
`None` is returned, an empty dictionary is assumed, if something else than
a dictionary is returned we return it from the function unchanged. That
way you can still use the redirect function or return simple strings.
Here the code for that decorator::
@ -138,6 +140,8 @@ Here the code for that decorator::
ctx = f(*args, **kwargs)
if ctx is None:
ctx = {}
elif not isinstance(ctx, dict):
return ctx
return render_template(template_name, **ctx)
return decorated_function
return decorator

13
docs/patterns/wtforms.rst
View file

@ -12,6 +12,15 @@ first. I recommend breaking up the application into multiple modules
(:ref:`larger-applications`) for that and adding a separate module for the
forms.
.. admonition:: Getting most of WTForms with an Extension
The `Flask-WTF`_ extension expands on this pattern and adds a few
handful little helpers that make working with forms and Flask more
fun. You can get it from `PyPI
<http://pypi.python.org/pypi/Flask-WTF>`_.
.. _Flask-WTF: http://packages.python.org/Flask-WTF/
The Forms
---------
@ -68,7 +77,7 @@ how easy this is. WTForms does half the form generation for us already.
To make it even nicer, we can write a macro that renders a field with
label and a list of errors if there are any.
Here an example `_formhelpers.html` template with such a macro:
Here's an example `_formhelpers.html` template with such a macro:
.. sourcecode:: html+jinja
@ -84,7 +93,7 @@ Here an example `_formhelpers.html` template with such a macro:
{% endmacro %}
This macro accepts a couple of keyword arguments that are forwarded to
WTForm's field function that renders the field for us. They keyword
WTForm's field function that renders the field for us. The keyword
arguments will be inserted as HTML attributes. So for example you can
call ``render_field(form.username, class='username')`` to add a class to
the input element. Note that WTForms returns standard Python unicode

196
docs/quickstart.rst
View file

@ -3,7 +3,7 @@
Quickstart
==========
Eager to get started? This page gives a good introduction in how to gets
Eager to get started? This page gives a good introduction in how to get
started with Flask. This assumes you already have Flask installed. If
you do not, head over to the :ref:`installation` section.
@ -37,9 +37,14 @@ see your hello world greeting.
So what did that code do?
1. first we imported the :class:`~flask.Flask` class. An instance of this
class will be our WSGI application.
2. next we create an instance of it. We pass it the name of the module /
1. First we imported the :class:`~flask.Flask` class. An instance of this
class will be our WSGI application. The first argument is the name of
the application's module. If you are using a single module (like here)
you should use `__name__` because depending on if it's started as
application or imported as module the name will be different
(``'__main__'`` versus the actual import name). For more information
on that, have a look at the :class:`~flask.Flask` documentation.
2. Next we create an instance of it. We pass it the name of the module /
package. This is needed so that Flask knows where it should look for
templates, static files and so on.
3. Then we use the :meth:`~flask.Flask.route` decorator to tell Flask
@ -76,7 +81,7 @@ To stop the server, hit control-C.
Debug Mode
----------
Now that :meth:`~flask.Flask.run` method is nice to start a local
The :meth:`~flask.Flask.run` method is nice to start a local
development server, but you would have to restart it manually after each
change you do to code. That is not very nice and Flask can do better. If
you enable the debug support the server will reload itself on code changes
@ -96,11 +101,10 @@ Both will have exactly the same effect.
.. admonition:: Attention
The interactive debugger however does not work in forking environments
which makes it nearly impossible to use on production servers but the
debugger still allows the execution of arbitrary code which makes it a
major security risk and **must never be used on production machines**
because of that.
Even though the interactive debugger does not work in forking environments
(which makes it nearly impossible to use on production servers), it still
allows the execution of arbitrary code. That makes it a major security
risk and therefore it **must never be used on production machines**.
Screenshot of the debugger in action:
@ -113,11 +117,14 @@ Screenshot of the debugger in action:
Routing
-------
As you have seen above, the :meth:`~flask.Flask.route` decorator is used
to bind a function to a URL. But there is more to it! You can make
certain parts of the URL dynamic and attach multiple rules to a function.
Modern web applications have beautiful URLs. This helps people remember
the URLs which is especially handy for applications that are used from
mobile devices with slower network connections. If the user can directly
go to the desired page without having to hit the index page it is more
likely he will like the page and come back next time.
Here some examples::
As you have seen above, the :meth:`~flask.Flask.route` decorator is used
to bind a function to a URL. Here are some basic examples::
@app.route('/')
def index():
@ -127,20 +134,16 @@ Here some examples::
def hello():
return 'Hello World'
But there is more to it! You can make certain parts of the URL dynamic
and attach multiple rules to a function.
Variable Rules
``````````````
Modern web applications have beautiful URLs. This helps people remember
the URLs which is especially handy for applications that are used from
mobile devices with slower network connections. If the user can directly
go to the desired page without having to hit the index page it is more
likely he will like the page and come back next time.
To add variable parts to a URL you can mark these special sections as
``<variable_name>``. Such a part is then passed as keyword argument to
your function. Optionally a converter can be specified by specifying a
rule with ``<converter:variable_name>``. Here some nice examples::
rule with ``<converter:variable_name>``. Here are some nice examples::
@app.route('/user/<username>')
def show_user_profile(username):
@ -198,12 +201,12 @@ The following converters exist:
URL Building
````````````
If it can match URLs, can it also generate them? Of course you can. To
If it can match URLs, can it also generate them? Of course it can. To
build a URL to a specific function you can use the :func:`~flask.url_for`
function. It accepts the name of the function as first argument and a
number of keyword arguments, each corresponding to the variable part of
the URL rule. Unknown variable parts are appended to the URL as query
parameter. Here some examples:
parameter. Here are some examples:
>>> from flask import Flask, url_for
>>> app = Flask(__name__)
@ -228,7 +231,7 @@ parameter. Here some examples:
/user/John%20Doe
(This also uses the :meth:`~flask.Flask.test_request_context` method
explained below. It basically tells flask to think we are handling a
explained below. It basically tells Flask to think we are handling a
request even though we are not, we are in an interactive Python shell.
Have a look at the explanation below. :ref:`context-locals`).
@ -251,7 +254,7 @@ HTTP Methods
HTTP (the protocol web applications are speaking) knows different methods
to access URLs. By default a route only answers to `GET` requests, but
that can be changed by providing the `methods` argument to the
:meth:`~flask.Flask.route` decorator. Here some examples::
:meth:`~flask.Flask.route` decorator. Here are some examples::
@app.route('/login', methods=['GET', 'POST'])
def login():
@ -264,27 +267,27 @@ If `GET` is present, `HEAD` will be added automatically for you. You
don't have to deal with that. It will also make sure that `HEAD` requests
are handled like the `HTTP RFC`_ (the document describing the HTTP
protocol) demands, so you can completely ignore that part of the HTTP
specification.
specification. Likewise as of Flask 0.6, `OPTIONS` is implemented for you
as well automatically.
You have no idea what an HTTP method is? Worry not, here quick
introduction in HTTP methods and why they matter:
You have no idea what an HTTP method is? Worry not, here is a quick
introduction to HTTP methods and why they matter:
The HTTP method (also often called "the verb") tells the server what the
clients wants to *do* with the requested page. The following methods are
very common:
`GET`
The Browser tells the server: just *get* me the information stored on
that page and send them to me. This is probably the most common
method.
The browser tells the server to just *get* the information stored on
that page and send it. This is probably the most common method.
`HEAD`
The Browser tells the server: get me the information, but I am only
The browser tells the server to get the information, but it is only
interested in the *headers*, not the content of the page. An
application is supposed to handle that as if a `GET` request was
received but not deliver the actual contents. In Flask you don't have
to deal with that at all, the underlying Werkzeug library handles that
for you.
received but to not deliver the actual content. In Flask you don't
have to deal with that at all, the underlying Werkzeug library handles
that for you.
`POST`
The browser tells the server that it wants to *post* some new
@ -295,22 +298,27 @@ very common:
`PUT`
Similar to `POST` but the server might trigger the store procedure
multiple times by overwriting the old values more than once. Now you
might be asking why this is any useful, but there are some good
reasons to do that. Consider the connection is lost during
transmission, in that situation a system between the browser and the
server might sent the request safely a second time without breaking
might be asking why is this useful, but there are some good reasons
to do it this way. Consider that the connection gets lost during
transmission: in this situation a system between the browser and the
server might receive the request safely a second time without breaking
things. With `POST` that would not be possible because it must only
be triggered once.
`DELETE`
Remove the information that the given location.
Remove the information at the given location.
`OPTIONS`
Provides a quick way for a client to figure out which methods are
supported by this URL. Starting with Flask 0.6, this is implemented
for you automatically.
Now the interesting part is that in HTML4 and XHTML1, the only methods a
form might submit to the server are `GET` and `POST`. But with JavaScript
and future HTML standards you can use other methods as well. Furthermore
HTTP became quite popular lately and there are more things than browsers
that are speaking HTTP. (Your revision control system for instance might
speak HTTP)
form can submit to the server are `GET` and `POST`. But with JavaScript
and future HTML standards you can use the other methods as well. Furthermore
HTTP has become quite popular lately and browsers are no longer the only
clients that are using HTTP. For instance, many revision control system
use it.
.. _HTTP RFC: http://www.ietf.org/rfc/rfc2068.txt
@ -368,10 +376,11 @@ package it's actually inside your package:
/hello.html
For templates you can use the full power of Jinja2 templates. Head over
to the `Jinja2 Template Documentation
to the :ref:`templating` section of the documentation or the official
`Jinja2 Template Documentation
<http://jinja.pocoo.org/2/documentation/templates>`_ for more information.
Here an example template:
Here is an example template:
.. sourcecode:: html+jinja
@ -399,7 +408,7 @@ markup to HTML) you can mark it as safe by using the
:class:`~jinja2.Markup` class or by using the ``|safe`` filter in the
template. Head over to the Jinja 2 documentation for more examples.
Here a basic introduction in how the :class:`~jinja2.Markup` class works:
Here is a basic introduction to how the :class:`~jinja2.Markup` class works:
>>> from flask import Markup
>>> Markup('<strong>Hello %s!</strong>') % '<blink>hacker</blink>'
@ -409,9 +418,16 @@ Markup(u'&lt;blink&gt;hacker&lt;/blink&gt;')
>>> Markup('<em>Marked up</em> &raquo; HTML').striptags()
u'Marked up \xbb HTML'
.. [#] Unsure what that :class:`~flask.g` object is? It's something you
can store information on yourself, check the documentation of that
object (:class:`~flask.g`) and the :ref:`sqlite3` for more
.. versionchanged:: 0.5
Autoescaping is no longer enabled for all templates. The following
extensions for templates trigger autoescaping: ``.html``, ``.htm``,
``.xml``, ``.xhtml``. Templates loaded from a string will have
autoescaping disabled.
.. [#] Unsure what that :class:`~flask.g` object is? It's something in which
you can store information for your own needs, check the documentation of
that object (:class:`~flask.g`) and the :ref:`sqlite3` for more
information.
@ -435,10 +451,9 @@ Context Locals
If you want to understand how that works and how you can implement
tests with context locals, read this section, otherwise just skip it.
Certain objects in Flask are global objects, but not just a standard
global object, but actually a proxy to an object that is local to a
specific context. What a mouthful. But that is actually quite easy to
understand.
Certain objects in Flask are global objects, but not of the usual kind.
These objects are actually proxies to objects that are local to a specific
context. What a mouthful. But that is actually quite easy to understand.
Imagine the context being the handling thread. A request comes in and the
webserver decides to spawn a new thread (or something else, the
@ -450,13 +465,13 @@ It does that in an intelligent way that one application can invoke another
application without breaking.
So what does this mean to you? Basically you can completely ignore that
this is the case unless you are unittesting or something different. You
this is the case unless you are doing something like unittesting. You
will notice that code that depends on a request object will suddenly break
because there is no request object. The solution is creating a request
object yourself and binding it to the context. The easiest solution for
unittesting is by using the :meth:`~flask.Flask.test_request_context`
context manager. In combination with the `with` statement it will bind a
test request so that you can interact with it. Here an example::
test request so that you can interact with it. Here is an example::
from flask import request
@ -478,8 +493,8 @@ The Request Object
``````````````````
The request object is documented in the API section and we will not cover
it here in detail (see :class:`~flask.request`), but just mention some of
the most common operations. First of all you have to import it from the
it here in detail (see :class:`~flask.request`). Here is a broad overview of
some of the most common operations. First of all you have to import it from
the `flask` module::
from flask import request
@ -487,7 +502,7 @@ the `flask` module::
The current request method is available by using the
:attr:`~flask.request.method` attribute. To access form data (data
transmitted in a `POST` or `PUT` request) you can use the
:attr:`~flask.request.form` attribute. Here a full example of the two
:attr:`~flask.request.form` attribute. Here is a full example of the two
attributes mentioned above::
@app.route('/login', methods=['POST', 'GET'])
@ -515,19 +530,18 @@ To access parameters submitted in the URL (``?key=value``) you can use the
We recommend accessing URL parameters with `get` or by catching the
`KeyError` because users might change the URL and presenting them a 400
bad request page in that case is a bit user unfriendly.
bad request page in that case is not user friendly.
For a full list of methods and attributes on that object, head over to the
:class:`~flask.request` documentation.
For a full list of methods and attributes of the request object, head over
to the :class:`~flask.request` documentation.
File Uploads
````````````
Obviously you can handle uploaded files with Flask just as easy. Just
make sure not to forget to set the ``enctype="multipart/form-data"``
attribute on your HTML form, otherwise the browser will not transmit your
files at all.
You can handle uploaded files with Flask easily. Just make sure not to
forget to set the ``enctype="multipart/form-data"`` attribute on your HTML
form, otherwise the browser will not transmit your files at all.
Uploaded files are stored in memory or at a temporary location on the
filesystem. You can access those files by looking at the
@ -535,8 +549,8 @@ filesystem. You can access those files by looking at the
uploaded file is stored in that dictionary. It behaves just like a
standard Python :class:`file` object, but it also has a
:meth:`~werkzeug.FileStorage.save` method that allows you to store that
file on the filesystem of the server. Here a simple example how that
works::
file on the filesystem of the server. Here is a simple example showing how
that works::
from flask import request
@ -581,8 +595,8 @@ Redirects and Errors
--------------------
To redirect a user to somewhere else you can use the
:func:`~flask.redirect` function, to abort a request early with an error
code the :func:`~flask.abort` function. Here an example how this works::
:func:`~flask.redirect` function. To abort a request early with an error
code use the :func:`~flask.abort` function. Here an example how this works::
from flask import abort, redirect, url_for
@ -628,7 +642,9 @@ unless he knows the secret key used for signing.
In order to use sessions you have to set a secret key. Here is how
sessions work::
from flask import session, redirect, url_for, escape
from flask import Flask, session, redirect, url_for, escape, request
app = Flask(__name__)
@app.route('/')
def index():
@ -652,6 +668,7 @@ sessions work::
def logout():
# remove the username from the session if its there
session.pop('username', None)
return redirect(url_for('index'))
# set the secret key. keep this really secret:
app.secret_key = 'A0Zr98j/3yX R~XHH!jmN]LWX/,?RT'
@ -659,7 +676,7 @@ sessions work::
The here mentioned :func:`~flask.escape` does escaping for you if you are
not using the template engine (like in this example).
.. admonition:: How to generate good Secret Keys
.. admonition:: How to generate good secret keys
The problem with random is that it's hard to judge what random is. And
a secret key should be as random as possible. Your operating system
@ -693,16 +710,17 @@ Logging
.. versionadded:: 0.3
Sometimes you might be in the situation where you deal with data that
should be correct, but actually is not. For example you have some client
side code that sends an HTTP request to the server, and it's obviously
Sometimes you might be in a situation where you deal with data that
should be correct, but actually is not. For example you may have some client
side code that sends an HTTP request to the server but it's obviously
malformed. This might be caused by a user tempering with the data, or the
client code failed. Most the time, it's okay to reply with ``400 Bad
Request`` in that situation, but other times it is not and the code has to
continue working.
client code failing. Most of the time, it's okay to reply with ``400 Bad
Request`` in that situation, but sometimes that won't do and the code has
to continue working.
Yet you want to log that something fishy happened. This is where loggers
come in handy. As of Flask 0.3 a logger is preconfigured for you to use.
You may still want to log that something fishy happened. This is where
loggers come in handy. As of Flask 0.3 a logger is preconfigured for you
to use.
Here are some example log calls::
@ -711,5 +729,17 @@ Here are some example log calls::
app.logger.error('An error occurred')
The attached :attr:`~flask.Flask.logger` is a standard logging
:class:`~logging.Logger`, so head over to the official stdlib
documentation for more information.
:class:`~logging.Logger`, so head over to the official `logging
documentation <http://docs.python.org/library/logging.html>`_ for more
information.
Hooking in WSGI Middlewares
---------------------------
If you want to add a WSGI middleware to your application you can wrap the
internal WSGI application. For example if you want to use one of the
middlewares from the Werkzeug package to work around bugs in lighttpd, you
can do it like this::
from werkzeug.contrib.fixers import LighttpdCGIRootFix
app.wsgi_app = LighttpdCGIRootFix(app.wsgi_app)

80
docs/security.rst
View file

@ -5,9 +5,18 @@ Web applications usually face all kinds of security problems and it's very
hard to get everything right. Flask tries to solve a few of these things
for you, but there are a couple more you have to take care of yourself.
.. _xss:
Cross-Site Scripting (XSS)
--------------------------
Cross site scripting is the concept of injecting arbitrary HTML (and with
it JavaScript) into the context of a website. To rememdy this, developers
have to properly escape text so that it cannot include arbitrary HTML
tags. For more information on that have a look at the Wikipedia article
on `Cross-Site Scripting
<http://en.wikipedia.org/wiki/Cross-site_scripting>`_.
Flask configures Jinja2 to automatically escape all values unless
explicitly told otherwise. This should rule out all XSS problems caused
in templates, but there are still other places where you have to be
@ -21,6 +30,31 @@ careful:
content-type guessing based on the first few bytes so users could
trick a browser to execute HTML.
Another thing that is very important are unquoted attributes. While
Jinja2 can protect you from XSS issues by escaping HTML, there is one
thing it cannot protect you from: XSS by attribute injection. To counter
this possible attack vector, be sure to always quote your attributes with
either double or single quotes when using Jinja expressions in them:
.. sourcecode:: html+jinja
<a href="{{ href }}">the text</a>
Why is this necessary? Because if you would not be doing that, an
attacker could easily inject custom JavaScript handlers. For example an
attacker could inject this piece of HTML+JavaScript:
.. sourcecode:: html
onmouseover=alert(document.cookie)
When the user would then move with the mouse over the link, the cookie
would be presented to the user in an alert window. But instead of showing
the cookie to the user, a good attacker might also execute any other
JavaScript code. In combination with CSS injections the attacker might
even make the element fill out the entire page so that the user would
just have to have the mouse anywhere on the page to trigger the attack.
Cross-Site Request Forgery (CSRF)
---------------------------------
@ -28,33 +62,33 @@ Another big problem is CSRF. This is a very complex topic and I won't
outline it here in detail just mention what it is and how to theoretically
prevent it.
So if your authentication information is stored in cookies you have
implicit state management. By that I mean that the state of "being logged
in" is controlled by a cookie and that cookie is sent with each request to
a page. Unfortunately that really means "each request" so also requests
triggered by 3rd party sites. If you don't keep that in mind some people
might be able to trick your application's users with social engineering to
do stupid things without them knowing.
If your authentication information is stored in cookies, you have implicit
state management. The state of "being logged in" is controlled by a
cookie, and that cookie is sent with each request to a page.
Unfortunately that includes requests triggered by 3rd party sites. If you
don't keep that in mind, some people might be able to trick your
application's users with social engineering to do stupid things without
them knowing.
Say you have a specific URL that, when you sent `POST` requests to will
delete a user's profile (say `http://example.com/user/delete`). If an
attacker now creates a page that sents a post request to that page with
some JavaScript he just has to trick some users to that page and their
profiles will end up being deleted.
attacker now creates a page that sends a post request to that page with
some JavaScript he just has to trick some users to load that page and
their profiles will end up being deleted.
Imagine you would run Facebook with millions of concurrent users and
someone would send out links to images of little kittens. When a user
would go to that page their profiles would get deleted while they are
Imagine you were to run Facebook with millions of concurrent users and
someone would send out links to images of little kittens. When users
would go to that page, their profiles would get deleted while they are
looking at images of fluffy cats.
So how can you prevent yourself from that? Basically for each request
that modifies content on the server you would have to either use a
one-time token and store that in the cookie **and** also transmit it with
the form data. After recieving the data on the server again you would
then have to compare the two tokens and ensure they are equal.
How can you prevent that? Basically for each request that modifies
content on the server you would have to either use a one-time token and
store that in the cookie **and** also transmit it with the form data.
After receiving the data on the server again, you would then have to
compare the two tokens and ensure they are equal.
Why does not Flask do that for you? The ideal place for this to happen is
the form validation framework which does not exist in Flask.
Why does Flask not do that for you? The ideal place for this to happen is
the form validation framework, which does not exist in Flask.
.. _json-security:
@ -77,8 +111,8 @@ generate JSON.
So what is the issue and how to avoid it? The problem are arrays at
toplevel in JSON. Imagine you send the following data out in a JSON
request. Say that's exporting the names and email adresses of all your
friends for a part of the userinterface that is written in JavaScript.
request. Say that's exporting the names and email addresses of all your
friends for a part of the user interface that is written in JavaScript.
Not very uncommon:
.. sourcecode:: javascript
@ -129,6 +163,6 @@ page loaded the data from the JSON response is in the `captured` array.
Because it is a syntax error in JavaScript to have an object literal
(``{...}``) toplevel an attacker could not just do a request to an
external URL with the script tag to load up the data. So what Flask does
is only allowing objects as toplevel elements when using
is to only allow objects as toplevel elements when using
:func:`~flask.jsonify`. Make sure to do the same when using an ordinary
JSON generate function.

232
docs/signals.rst Normal file
View file

@ -0,0 +1,232 @@
.. _signals:
Signals
=======
.. versionadded:: 0.6
Starting with Flask 0.6, there is integrated support for signalling in
Flask. This support is provided by the excellent `blinker`_ library and
will gracefully fall back if it is not available.
What are signals? Signals help you decouple applications by sending
notifications when actions occur elsewhere in the core framework or
another Flask extensions. In short, signals allow certain senders to
notify subscribers that something happened.
Flask comes with a couple of signals and other extensions might provide
more. Also keep in mind that signals are intended to notify subscribers
and should not encourage subscribers to modify data. You will notice that
there are signals that appear to do the same thing like some of the
builtin decorators do (eg: :data:`~flask.request_started` is very similar
to :meth:`~flask.Flask.before_request`). There are however difference in
how they work. The core :meth:`~flask.Flask.before_request` handler for
example is executed in a specific order and is able to abort the request
early by returning a response. In contrast all signal handlers are
executed in undefined order and do not modify any data.
The big advantage of signals over handlers is that you can safely
subscribe to them for the split of a second. These temporary
subscriptions are helpful for unittesting for example. Say you want to
know what templates were rendered as part of a request: signals allow you
to do exactly that.
Subscribing to Signals
----------------------
To subscribe to a signal, you can use the
:meth:`~blinker.base.Signal.connect` method of a signal. The first
argument is the function that should be called when the signal is emitted,
the optional second argument specifies a sender. To unsubscribe from a
signal, you can use the :meth:`~blinker.base.Signal.disconnect` method.
For all core Flask signals, the sender is the application that issued the
signal. When you subscribe to a signal, be sure to also provide a sender
unless you really want to listen for signals of all applications. This is
especially true if you are developing an extension.
Here for example a helper context manager that can be used to figure out
in a unittest which templates were rendered and what variables were passed
to the template::
from flask import template_rendered
from contextlib import contextmanager
@contextmanager
def captured_templates(app):
recorded = []
def record(sender, template, context):
recorded.append((template, context))
template_rendered.connect(record, app)
try:
yield recorded
finally:
template_rendered.disconnect(record, app)
This can now easily be paired with a test client::
with captured_templates(app) as templates:
rv = app.test_client().get('/')
assert rv.status_code == 200
assert len(templates) == 1
template, context = templates[0]
assert template.name == 'index.html'
assert len(context['items']) == 10
All the template rendering in the code issued by the application `app`
in the body of the `with` block will now be recorded in the `templates`
variable. Whenever a template is rendered, the template object as well as
context are appended to it.
Additionally there is a convenient helper method
(:meth:`~blinker.base.Signal.connected_to`). that allows you to
temporarily subscribe a function to a signal with is a context manager on
its own which simplifies the example above::
from flask import template_rendered
def captured_templates(app):
recorded = []
def record(sender, template, context):
recorded.append((template, context))
return template_rendered.connected_to(record, app)
.. admonition:: Blinker API Changes
The :meth:`~blinker.base.Signal.connected_to` method arrived in Blinker
with version 1.1.
Creating Signals
----------------
If you want to use signals in your own application, you can use the
blinker library directly. The most common use case are named signals in a
custom :class:`~blinker.base.Namespace`.. This is what is recommended
most of the time::
from blinker import Namespace
my_signals = Namespace()
Now you can create new signals like this::
model_saved = my_signals.signal('model-saved')
The name for the signal here makes it unique and also simplifies
debugging. You can access the name of the signal with the
:attr:`~blinker.base.NamedSignal.name` attribute.
.. admonition:: For Extension Developers
If you are writing a Flask extension and you to gracefully degrade for
missing blinker installations, you can do so by using the
:class:`flask.signals.Namespace` class.
Sending Signals
---------------
If you want to emit a signal, you can do so by calling the
:meth:`~blinker.base.Signal.send` method. It accepts a sender as first
argument and optionally some keyword arguments that are forwarded to the
signal subscribers::
class Model(object):
...
def save(self):
model_saved.send(self)
Try to always pick a good sender. If you have a class that is emitting a
signal, pass `self` as sender. If you emitting a signal from a random
function, you can pass ``current_app._get_current_object()`` as sender.
.. admonition:: Passing Proxies as Senders
Never pass :data:`~flask.current_app` as sender to a signal. Use
``current_app._get_current_object()`` instead. The reason for this is
that :data:`~flask.current_app` is a proxy and not the real application
object.
Decorator Based Signal Subscriptions
------------------------------------
With Blinker 1.1 you can also easily subscribe to signals by using the new
:meth:`~blinker.base.NamedSignal.connect_via` decorator::
from flask import template_rendered
@template_rendered.connect_via(app)
def when_template_rendered(sender, template, context):
print 'Template %s is rendered with %s' % (template.name, context)
Core Signals
------------
.. when modifying this list, also update the one in api.rst
The following signals exist in Flask:
.. data:: flask.template_rendered
:noindex:
This signal is sent when a template was successfully rendered. The
signal is invoked with the instance of the template as `template`
and the context as dictionary (named `context`).
Example subscriber::
def log_template_renders(sender, template, context):
sender.logger.debug('Rendering template "%s" with context %s',
template.name or 'string template',
context)
from flask import request_started
request_started.connect(log_template_renders, app)
.. data:: flask.request_started
:noindex:
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 :class:`~flask.request`.
Example subscriber::
def log_request(sender):
sender.logger.debug('Request context is set up')
from flask import request_started
request_started.connect(log_request, app)
.. data:: flask.request_finished
:noindex:
This signal is sent right before the response is sent to the client.
It is passed the response to be sent named `response`.
Example subscriber::
def log_response(sender, response):
sender.logger.debug('Request context is about to close down. '
'Response: %s', response)
from flask import request_finished
request_finished.connect(log_response, app)
.. data:: flask.got_request_exception
:noindex:
This signal is sent when an exception happens during request processing.
It is sent *before* 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 `exception`.
Example subscriber::
def log_exception(sender, exception):
sender.logger.debug('Got exception during processing: %s', exception)
from flask import got_request_exception
got_request_exception.connect(log_exception, app)
.. _blinker: http://pypi.python.org/pypi/blinker

200
docs/styleguide.rst Normal file
View file

@ -0,0 +1,200 @@
Pocoo Styleguide
================
The Pocoo styleguide is the styleguide for all Pocoo Projects, including
Flask. This styleguide is a requirement for Patches to Flask and a
recommendation for Flask extensions.
In general the Pocoo Styleguide closely follows :pep:`8` with some small
differences and extensions.
General Layout
--------------
Indentation:
4 real spaces. No tabs, no exceptions.
Maximum line length:
79 characters with a soft limit for 84 if absolutely necessary. Try
to avoid too nested code by cleverly placing `break`, `continue` and
`return` statements.
Continuing long statements:
To continue a statement you can use backslashes in which case you should
align the next line with the last dot or equal sign, or indent four
spaces::
this_is_a_very_long(function_call, 'with many parameters') \
.that_returns_an_object_with_an_attribute
MyModel.query.filter(MyModel.scalar > 120) \
.order_by(MyModel.name.desc()) \
.limit(10)
If you break in a statement with parentheses or braces, align to the
braces::
this_is_a_very_long(function_call, 'with many parameters',
23, 42, 'and even more')
For lists or tuples with many items, break immediately after the
opening brace::
items = [
'this is the first', 'set of items', 'with more items',
'to come in this line', 'like this'
]
Blank lines:
Top level functions and classes are separated by two lines, everything
else by one. Do not use too many blank lines to separate logical
segments in code. Example::
def hello(name):
print 'Hello %s!' % name
def goodbye(name):
print 'See you %s.' % name
class MyClass(object):
"""This is a simple docstring"""
def __init__(self, name):
self.name = name
def get_annoying_name(self):
return self.name.upper() + '!!!!111'
Expressions and Statements
--------------------------
General whitespace rules:
- No whitespace for unary operators that are not words
(e.g.: ``-``, ``~`` etc.) as well on the inner side of parentheses.
- Whitespace is placed between binary operators.
Good::
exp = -1.05
value = (item_value / item_count) * offset / exp
value = my_list[index]
value = my_dict['key']
Bad::
exp = - 1.05
value = ( item_value / item_count ) * offset / exp
value = (item_value/item_count)*offset/exp
value=( item_value/item_count ) * offset/exp
value = my_list[ index ]
value = my_dict ['key']
Yoda statements are a nogo:
Never compare constant with variable, always variable with constant:
Good::
if method == 'md5':
pass
Bad::
if 'md5' == method:
pass
Comparisons:
- against arbitrary types: ``==`` and ``!=``
- against singletons with ``is`` and ``is not`` (eg: ``foo is not
None``)
- never compare something with `True` or `False` (for example never
do ``foo == False``, do ``not foo`` instead)
Negated containment checks:
use ``foo not in bar`` instead of ``not foo in bar``
Instance checks:
``isinstance(a, C)`` instead of ``type(A) is C``, but try to avoid
instance checks in general. Check for features.
Naming Conventions
------------------
- Class names: ``CamelCase``, with acronyms kept uppercase (``HTTPWriter``
and not ``HttpWriter``)
- Variable names: ``lowercase_with_underscores``
- Method and function names: ``lowercase_with_underscores``
- Constants: ``UPPERCASE_WITH_UNDERSCORES``
- precompiled regular expressions: ``name_re``
Protected members are prefixed with a single underscore. Double
underscores are reserved for mixin classes.
On classes with keywords, trailing underscores are appended. Clashes with
builtins are allowed and **must not** be resolved by appending an
underline to the variable name. If the function needs to access a
shadowed builtin, rebind the builtin to a different name instead.
Function and method arguments:
- class methods: ``cls`` as first parameter
- instance methods: ``self`` as first parameter
- lambdas for properties might have the first parameter replaced
with ``x`` like in ``display_name = property(lambda x: x.real_name
or x.username)``
Docstrings
----------
Docstring conventions:
All docstrings are formatted with reStructuredText as understood by
Sphinx. Depending on the number of lines in the docstring, they are
laid out differently. If it's just one line, the closing triple
quote is on the same line as the opening, otherwise the text is on
the same line as the opening quote and the triple quote that closes
the string on its own line::
def foo():
"""This is a simple docstring"""
def bar():
"""This is a longer docstring with so much information in there
that it spans three lines. In this case the closing triple quote
is on its own line.
"""
Module header:
The module header consists of an utf-8 encoding declaration (if non
ASCII letters are used, but it is recommended all the time) and a
standard docstring::
# -*- coding: utf-8 -*-
"""
package.module
~~~~~~~~~~~~~~
A brief description goes here.
:copyright: (c) YEAR by AUTHOR.
:license: LICENSE_NAME, see LICENSE_FILE for more details.
"""
Please keep in mind that proper copyrights and license files are a
requirement for approved Flask extensions.
Comments
--------
Rules for comments are similar to docstrings. Both are formatted with
reStructuredText. If a comment is used to document an attribute, put a
colon after the opening pound sign (``#``)::
class User(object):
#: the name of the user as unicode string
name = Column(String)
#: the sha1 hash of the password + inline salt
pw_hash = Column(String)

188
docs/templating.rst Normal file
View file

@ -0,0 +1,188 @@
Templates
=========
Flask leverages Jinja2 as template engine. You are obviously free to use
a different template engine, but you still have to install Jinja2 to run
Flask itself. This requirement is necessary to enable rich extensions.
An extension can depend on Jinja2 being present.
This section only gives a very quick introduction into how Jinja2
is integrated into Flask. If you want information on the template
engine's syntax itself, head over to the official `Jinja2 Template
Documentation <http://jinja.pocoo.org/2/documentation/templates>`_ for
more information.
Jinja Setup
-----------
Unless customized, Jinja2 is configured by Flask as follows:
- autoescaping is enabled for all templates ending in ``.html``,
``.htm``, ``.xml`` as well as ``.xhtml``
- a template has the ability to opt in/out autoescaping with the
``{% autoescape %}`` tag.
- Flask inserts a couple of global functions and helpers into the
Jinja2 context, additionally to the values that are present by
default.
Standard Context
----------------
The following global variables are available within Jinja2 templates
by default:
.. data:: config
:noindex:
The current configuration object (:data:`flask.config`)
.. versionadded:: 0.6
.. data:: request
:noindex:
The current request object (:class:`flask.request`)
.. data:: session
:noindex:
The current session object (:class:`flask.session`)
.. data:: g
:noindex:
The request-bound object for global variables (:data:`flask.g`)
.. function:: url_for
:noindex:
The :func:`flask.url_for` function.
.. function:: get_flashed_messages
:noindex:
The :func:`flask.get_flashed_messages` function.
.. admonition:: The Jinja Context Behaviour
These variables are added to the context of variables, they are not
global variables. The difference is that by default these will not
show up in the context of imported templates. This is partially caused
by performance considerations, partially to keep things explicit.
What does this mean for you? If you have a macro you want to import,
that needs to access the request object you have two possibilities:
1. you explicitly pass the request to the macro as parameter, or
the attribute of the request object you are interested in.
2. you import the macro "with context".
Importing with context looks like this:
.. sourcecode:: jinja
{% from '_helpers.html' import my_macro with context %}
Standard Filters
----------------
These filters are available in Jinja2 additionally to the filters provided
by Jinja2 itself:
.. function:: tojson
:noindex:
This function converts the given object into JSON representation. This
is for example very helpful if you try to generate JavaScript on the
fly.
Note that inside `script` tags no escaping must take place, so make
sure to disable escaping with ``|safe`` if you intend to use it inside
`script` tags:
.. sourcecode:: html+jinja
<script type=text/javascript>
doSomethingWith({{ user.username|tojson|safe }});
</script>
That the ``|tojson`` filter escapes forward slashes properly for you.
Controlling Autoescaping
------------------------
Autoescaping is the concept of automatically escaping special characters
of you. Special characters in the sense of HTML (or XML, and thus XHTML)
are ``&``, ``>``, ``<``, ``"`` as well as ``'``. Because these characters
carry specific meanings in documents on their own you have to replace them
by so called "entities" if you want to use them for text. Not doing so
would not only cause user frustration by the inability to use these
characters in text, but can also lead to security problems. (see
:ref:`xss`)
Sometimes however you will need to disable autoescaping in templates.
This can be the case if you want to explicitly inject HTML into pages, for
example if they come from a system that generate secure HTML like a
markdown to HTML converter.
There are three ways to accomplish that:
- In the Python code, wrap the HTML string in a :class:`~flask.Markup`
object before passing it to the template. This is in general the
recommended way.
- Inside the template, use the ``|safe`` filter to explicitly mark a
string as safe HTML (``{{ myvariable|safe }}``)
- Temporarily disable the autoescape system altogether.
To disable the autoescape system in templates, you can use the ``{%
autoescape %}`` block:
.. sourcecode:: html+jinja
{% autoescape false %}
<p>autoescaping is disabled here
<p>{{ will_not_be_escaped }}
{% endautoescape %}
Whenever you do this, please be very cautious about the variables you are
using in this block.
Registering Filters
-------------------
If you want to register your own filters in Jinja2 you have two ways to do
that. You can either put them by hand into the
:attr:`~flask.Flask.jinja_env` of the application or use the
:meth:`~flask.Flask.template_filter` decorator.
The two following examples work the same and both reverse an object::
@app.template_filter('reverse')
def reverse_filter(s):
return s[::-1]
def reverse_filter(s):
return s[::-1]
app.jinja_env.filters['reverse'] = reverse_filter
In case of the decorator the argument is optional if you want to use the
function name as name of the filter.
Context Processors
------------------
To inject new variables automatically into the context of a template
context processors exist in Flask. Context processors run before the
template is rendered and have the ability to inject new values into the
template context. A context processor is a function that returns a
dictionary. The keys and values of this dictionary are then merged with
the template context::
@app.context_processor
def inject_user():
return dict(user=g.user)
The context processor above makes a variable called `user` available in
the template with the value of `g.user`. This example is not very
interesting because `g` is available in templates anyways, but it gives an
idea how this works.

16
docs/testing.rst
View file

@ -8,8 +8,8 @@ Testing Flask Applications
Not sure where that is coming from, and it's not entirely correct, but
also not that far from the truth. Untested applications make it hard to
improve existing code and developers of untested applications tend to
become pretty paranoid. If an application however has automated tests, you
can safely change things and you will instantly know if your change broke
become pretty paranoid. If an application has automated tests, you can
safely change things, and you will instantly know if your change broke
something.
Flask gives you a couple of ways to test applications. It mainly does
@ -43,13 +43,13 @@ In order to test that, we add a second module (
class FlaskrTestCase(unittest.TestCase):
def setUp(self):
self.db_fd, flaskr.DATABASE = tempfile.mkstemp()
self.db_fd, flaskr.app.config['DATABASE'] = tempfile.mkstemp()
self.app = flaskr.app.test_client()
flaskr.init_db()
def tearDown(self):
os.close(self.db_fd)
os.unlink(flaskr.DATABASE)
os.unlink(flaskr.app.config['DATABASE'])
if __name__ == '__main__':
unittest.main()
@ -60,7 +60,7 @@ each individual test function. To delete the database after the test, we
close the file and remove it from the filesystem in the
:meth:`~unittest.TestCase.tearDown` method. What the test client does is
give us a simple interface to the application. We can trigger test
requests to the application and the client will also keep track of cookies
requests to the application, and the client will also keep track of cookies
for us.
Because SQLite3 is filesystem-based we can easily use the tempfile module
@ -130,7 +130,7 @@ Logging In and Out
------------------
The majority of the functionality of our application is only available for
the administration user. So we need a way to log our test client in to the
the administrative user, so we need a way to log our test client in to the
application and out of it again. For that we fire some requests to the
login and logout pages with the required form data (username and
password). Because the login and logout pages redirect, we tell the
@ -200,12 +200,12 @@ suite.
Other Testing Tricks
--------------------
Besides using the test client we used above there is also the
Besides using the test client we used above, there is also the
:meth:`~flask.Flask.test_request_context` method that in combination with
the `with` statement can be used to activate a request context
temporarily. With that you can access the :class:`~flask.request`,
:class:`~flask.g` and :class:`~flask.session` objects like in view
functions. Here a full example that showcases this::
functions. Here's a full example that showcases this::
app = flask.Flask(__name__)

6
docs/tutorial/setup.rst
View file

@ -52,7 +52,7 @@ The `secret_key` is needed to keep the client-side sessions secure.
Choose that key wisely and as hard to guess and complex as possible. The
debug flag enables or disables the interactive debugger. Never leave
debug mode activated in a production system because it will allow users to
executed code on the server!
execute code on the server!
We also add a method to easily connect to the database specified. That
can be used to open a connection on request and also from the interactive
@ -64,7 +64,7 @@ Python shell or a script. This will come in handy later
return sqlite3.connect(app.config['DATABASE'])
Finally we just add a line to the bottom of the file that fires up the
server if we run that file as standalone application::
server if we want to run that file as a standalone application::
if __name__ == '__main__':
app.run()
@ -76,7 +76,7 @@ focus on that a little later. First we should get the database working.
.. admonition:: Externally Visible Server
Want your server to be publically available? Check out the
Want your server to be publicly available? Check out the
:ref:`externally visible server <public-server>` section for more
information.

2
docs/tutorial/testing.rst
View file

@ -4,7 +4,7 @@ Bonus: Testing the Application
==============================
Now that you have finished the application and everything works as
expected, it's probably not a good idea to add automated tests to simplify
expected, it's probably not a bad idea to add automated tests to simplify
modifications in the future. The application above is used as a basic
example of how to perform unittesting in the :ref:`testing` section of the
documentation. Go there to see how easy it is to test Flask applications.

35
docs/tutorial/views.rst
View file

@ -11,11 +11,11 @@ Show Entries
This view shows all the entries stored in the database. It listens on the
root of the application and will select title and text from the database.
The one with the highest id (the newest entry) on top. The rows returned
from the cursor are tuples with the columns ordered like specified in the
select statement. This is good enough for small applications like here,
but you might want to convert them into a dict. If you are interested how
to do that, check out the :ref:`easy-querying` example.
The one with the highest id (the newest entry) will be on top. The rows
returned from the cursor are tuples with the columns ordered like specified
in the select statement. This is good enough for small applications like
here, but you might want to convert them into a dict. If you are
interested in how to do that, check out the :ref:`easy-querying` example.
The view function will pass the entries as dicts to the
`show_entries.html` template and return the rendered one::
@ -48,16 +48,23 @@ redirect back to the `show_entries` page::
Note that we check that the user is logged in here (the `logged_in` key is
present in the session and `True`).
.. admonition:: Security Note
Be sure to use question marks when building SQL statements, as done in the
example above. Otherwise, your app will be vulnerable to SQL injection when
you use string formatting to build SQL statements.
See :ref:`sqlite3` for more.
Login and Logout
----------------
These functions are used to sign the user in and out. Login checks the
username and password against the ones from the configuration and sets the
`logged_in` key in the session. If the user logged in successfully that
key is set to `True` and the user is redirected back to the `show_entries`
page. In that case also a message is flashed that informs the user he or
she was logged in successfully. If an error occoured the template is
notified about that and the user asked again::
`logged_in` key in the session. If the user logged in successfully, that
key is set to `True`, and the user is redirected back to the `show_entries`
page. In addition, a message is flashed that informs the user that he or
she was logged in successfully. If an error occurred, the template is
notified about that, and the user is asked again::
@app.route('/login', methods=['GET', 'POST'])
def login():
@ -73,12 +80,12 @@ notified about that and the user asked again::
return redirect(url_for('show_entries'))
return render_template('login.html', error=error)
The logout function on the other hand removes that key from the session
The logout function, on the other hand, removes that key from the session
again. We use a neat trick here: if you use the :meth:`~dict.pop` method
of the dict and pass a second parameter to it (the default) the method
of the dict and pass a second parameter to it (the default), the method
will delete the key from the dictionary if present or do nothing when that
key was not in there. This is helpful because we don't have to check in
that case if the user was logged in.
key is not in there. This is helpful because now we don't have to check
if the user was logged in.
::

36
docs/unicode.rst
View file

@ -8,7 +8,7 @@ should probably read `The Absolute Minimum Every Software Developer
Absolutely, Positively Must Know About Unicode and Character Sets
<http://www.joelonsoftware.com/articles/Unicode.html>`_. This part of the
documentation just tries to cover the very basics so that you have a
pleasent experience with unicode related things.
pleasant experience with unicode related things.
Automatic Conversion
--------------------
@ -54,6 +54,8 @@ unicode. What does working with unicode in Python 2.x mean?
UTF-8 for this purpose. To tell the interpreter your encoding you can
put the ``# -*- coding: utf-8 -*-`` into the first or second line of
your Python source file.
- Jinja is configured to decode the template files from UTF-8. So make
sure to tell your editor to save the file as UTF-8 there as well.
Encoding and Decoding Yourself
------------------------------
@ -61,12 +63,12 @@ Encoding and Decoding Yourself
If you are talking with a filesystem or something that is not really based
on unicode you will have to ensure that you decode properly when working
with unicode interface. So for example if you want to load a file on the
filesystem and embedd it into a Jinja2 template you will have to decode it
form the encoding of that file. Here the old problem that textfiles do
filesystem and embed it into a Jinja2 template you will have to decode it
from the encoding of that file. Here the old problem that text files do
not specify their encoding comes into play. So do yourself a favour and
limit yourself to UTF-8 for textfiles as well.
limit yourself to UTF-8 for text files as well.
Anyways. To load such a file with unicode you can use the builtin
Anyways. To load such a file with unicode you can use the built-in
:meth:`str.decode` method::
def read_file(filename, charset='utf-8'):
@ -79,3 +81,27 @@ To go from unicode into a specific charset such as UTF-8 you can use the
def write_file(filename, contents, charset='utf-8'):
with open(filename, 'w') as f:
f.write(contents.encode(charset))
Configuring Editors
-------------------
Most editors save as UTF-8 by default nowadays but in case your editor is
not configured to do this you have to change it. Here some common ways to
set your editor to store as UTF-8:
- Vim: put ``set enc=utf-8`` to your ``.vimrc`` file.
- Emacs: either use an encoding cookie or put this into your ``.emacs``
file::
(prefer-coding-system 'utf-8)
(setq default-buffer-file-coding-system 'utf-8)
- Notepad++:
1. Go to *Settings -> Preferences ...*
2. Select the "New Document/Default Directory" tab
3. Select "UTF-8 without BOM" as encoding
It is also recommended to use the Unix newline format, you can select
it in the same panel but this is not a requirement.

70
docs/upgrading.rst
View file

@ -2,7 +2,7 @@ Upgrading to Newer Releases
===========================
Flask itself is changing like any software is changing over time. Most of
the changes are the nice kind, the kind where you don't have th change
the changes are the nice kind, the kind where you don't have to change
anything in your code to profit from a new release.
However every once in a while there are changes that do require some
@ -19,6 +19,74 @@ installation, make sure to pass it the ``-U`` parameter::
$ easy_install -U Flask
Version 0.7
-----------
Due to a bug in earlier implementations the request local proxies now
raise a :exc:`RuntimeError` instead of an :exc:`AttributeError` when they
are unbound. If you caught these exceptions with :exc:`AttributeError`
before, you should catch them with :exc:`RuntimeError` now.
Additionally the :func:`~flask.send_file` function is now issuing
deprecation warnings if you depend on functionality that will be removed
in Flask 1.0. Previously it was possible to use etags and mimetypes
when file objects were passed. This was unreliable and caused issues
for a few setups. If you get a deprecation warning, make sure to
update your application to work with either filenames there or disable
etag attaching and attach them yourself.
Old code::
return send_file(my_file_object)
return send_file(my_file_object)
New code::
return send_file(my_file_object, add_etags=False)
Version 0.6
-----------
Flask 0.6 comes with a backwards incompatible change which affects the
order of after-request handlers. Previously they were called in the order
of the registration, now they are called in reverse order. This change
was made so that Flask behaves more like people expected it to work and
how other systems handle request pre- and postprocessing. If you
depend on the order of execution of post-request functions, be sure to
change the order.
Another change that breaks backwards compatibility is that context
processors will no longer override values passed directly to the template
rendering function. If for example `request` is as variable passed
directly to the template, the default context processor will not override
it with the current request object. This makes it easier to extend
context processors later to inject additional variables without breaking
existing template not expecting them.
Version 0.5
-----------
Flask 0.5 is the first release that comes as a Python package instead of a
single module. There were a couple of internal refactoring so if you
depend on undocumented internal details you probably have to adapt the
imports.
The following changes may be relevant to your application:
- autoescaping no longer happens for all templates. Instead it is
configured to only happen on files ending with ``.html``, ``.htm``,
``.xml`` and ``.xhtml``. If you have templates with different
extensions you should override the
:meth:`~flask.Flask.select_jinja_autoescape` method.
- Flask no longer supports zipped applications in this release. This
functionality might come back in future releases if there is demand
for this feature. Removing support for this makes the Flask internal
code easier to understand and fixes a couple of small issues that make
debugging harder than necessary.
- The `create_jinja_loader` function is gone. If you want to customize
the Jinja loader now, use the
:meth:`~flask.Flask.create_jinja_environment` method instead.
Version 0.4
-----------