Merge branch 'master' into first-request-decorator

Conflicts:
	flask/app.py

.travis.yml

@@ -0,0 +1,15 @@
+language: python
+
+python:
+  - 2.5
+  - 2.6
+  - 2.7
+  - pypy
+
+before_install: pip install simplejson
+
+script: python setup.py test
+
+branches:
+  except:
+    - website

CHANGES

@@ -6,8 +6,10 @@ Here you can see the full list of changes between each Flask release.
 Version 0.9
 -----------
 
-Relase date to be decided, codename to be chosen.
+Released on July 1st 2012, codename Campari.
 
+- The :func:`flask.Request.on_json_loading_failed` now returns a JSON formatted
+  response by default.
 - The :func:`flask.url_for` function now can generate anchors to the
   generated links.
 - The :func:`flask.url_for` function now can also explicitly generate
@@ -42,12 +44,40 @@ Relase date to be decided, codename to be chosen.
   using configuration values, e.g. ``app.run(app.config.get('MYHOST'),
   app.config.get('MYPORT'))``, with proper behavior whether or not a config
   file is provided.
-
+- The :meth:`flask.render_template` method now accepts a either an iterable of
+  template names or a single template name.  Previously, it only accepted a
+  single template name.  On an iterable, the first template found is rendered.
+- Added :meth:`flask.Flask.app_context` which works very similar to the
+  request context but only provides access to the current application.  This
+  also adds support for URL generation without an active request context.
+- View functions can now return a tuple with the first instance being an
+  instance of :class:`flask.Response`.  This allows for returning
+  ``jsonify(error="error msg"), 400`` from a view function.
+- :class:`~flask.Flask` and :class:`~flask.Blueprint` now provide a
+  :meth:`~flask.Flask.get_send_file_max_age` hook for subclasses to override
+  behavior of serving static files from Flask when using
+  :meth:`flask.Flask.send_static_file` (used for the default static file
+  handler) and :func:`~flask.helpers.send_file`.  This hook is provided a
+  filename, which for example allows changing cache controls by file extension.
+  The default max-age for `send_file` and static files can be configured
+  through a new ``SEND_FILE_MAX_AGE_DEFAULT`` configuration variable, which is
+  used in the default `get_send_file_max_age` implementation.
+- Fixed an assumption in sessions implementation which could break message
+  flashing on sessions implementations which use external storage.
+- Changed the behavior of tuple return values from functions.  They are no
+  longer arguments to the response object, they now have a defined meaning.
+- Added :attr:`flask.Flask.request_globals_class` to allow a specific class to
+  be used on creation of the :data:`~flask.g` instance of each request.
+- Added `required_methods` attribute to view functions to force-add methods
+  on registration.
+- Added :func:`flask.after_this_request`.
+- Added :func:`flask.stream_with_context` and the ability to push contexts
+  multiple times without producing unexpected behavior.
 
 Version 0.8.1
 -------------
 
-Bugfix release, release date to be decided
+Bugfix release, released on July 1st 2012
 
 - Fixed an issue with the undocumented `flask.session` module to not
   work properly on Python 2.5.  It should not be used but did cause
@@ -89,7 +119,7 @@ Released on September 29th 2011, codename Rakija
   variable as well as ``SERVER_NAME`` are now properly used by the test client
   as defaults.
 - Added :attr:`flask.views.View.decorators` to support simpler decorating of
-  pluggable (class based) views.
+  pluggable (class-based) views.
 - Fixed an issue where the test client if used with the "with" statement did not
   trigger the execution of the teardown handlers.
 - Added finer control over the session cookie parameters.
@@ -131,7 +161,7 @@ Released on June 28th 2011, codename Grappa
 
 - Added :meth:`~flask.Flask.make_default_options_response`
   which can be used by subclasses to alter the default
-  behaviour for `OPTIONS` responses.
+  behavior for `OPTIONS` responses.
 - Unbound locals now raise a proper :exc:`RuntimeError` instead
   of an :exc:`AttributeError`.
 - Mimetype guessing and etag support based on file objects is now
@@ -141,7 +171,7 @@ Released on June 28th 2011, codename Grappa
 - Static file handling for modules now requires the name of the
   static folder to be supplied explicitly.  The previous autodetection
   was not reliable and caused issues on Google's App Engine.  Until
-  1.0 the old behaviour will continue to work but issue dependency
+  1.0 the old behavior will continue to work but issue dependency
   warnings.
 - fixed a problem for Flask to run on jython.
 - added a `PROPAGATE_EXCEPTIONS` configuration variable that can be
@@ -177,7 +207,7 @@ Released on June 28th 2011, codename Grappa
   might occur during request processing (for instance database connection
   errors, timeouts from remote resources etc.).
 - Blueprints can provide blueprint specific error handlers.
-- Implemented generic :ref:`views` (class based views).
+- Implemented generic :ref:`views` (class-based views).
 
 Version 0.6.1
 -------------
@@ -259,14 +289,14 @@ Released on July 6th 2010, codename Calvados
   the session cookie cross-subdomain wide.
 - autoescaping is no longer active for all templates.  Instead it
   is only active for ``.html``, ``.htm``, ``.xml`` and ``.xhtml``.
-  Inside templates this behaviour can be changed with the
+  Inside templates this behavior can be changed with the
   ``autoescape`` tag.
 - refactored Flask internally.  It now consists of more than a
   single file.
 - :func:`flask.send_file` now emits etags and has the ability to
   do conditional responses builtin.
 - (temporarily) dropped support for zipped applications.  This was a
-  rarely used feature and led to some confusing behaviour.
+  rarely used feature and led to some confusing behavior.
 - added support for per-package template and static-file directories.
 - removed support for `create_jinja_loader` which is no longer used
   in 0.5 due to the improved module support.

LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2010 by Armin Ronacher and contributors.  See AUTHORS
+Copyright (c) 2012 by Armin Ronacher and contributors.  See AUTHORS
 for more details.
 
 Some rights reserved.

Makefile

@@ -23,12 +23,21 @@ clean-pyc:
 	find . -name '*~' -exec rm -f {} +
 
 upload-docs:
-	$(MAKE) -C docs html dirhtml latex
+	$(MAKE) -C docs html dirhtml latex epub
 	$(MAKE) -C docs/_build/latex all-pdf
 	cd docs/_build/; mv html flask-docs; zip -r flask-docs.zip flask-docs; mv flask-docs html
 	rsync -a docs/_build/dirhtml/ pocoo.org:/var/www/flask.pocoo.org/docs/
 	rsync -a docs/_build/latex/Flask.pdf pocoo.org:/var/www/flask.pocoo.org/docs/flask-docs.pdf
 	rsync -a docs/_build/flask-docs.zip pocoo.org:/var/www/flask.pocoo.org/docs/flask-docs.zip
+	rsync -a docs/_build/epub/Flask.epub pocoo.org:/var/www/flask.pocoo.org/docs/flask-docs.epub
+
+# ebook-convert docs: http://manual.calibre-ebook.com/cli/ebook-convert.html
+ebook:
+	@echo 'Using .epub from `make upload-docs` to create .mobi.'
+	@echo 'Command `ebook-covert` is provided by calibre package.'
+	@echo 'Requires X-forwarding for Qt features used in conversion (ssh -X).'
+	@echo 'Do not mind "Invalid value for ..." CSS errors if .mobi renders.'
+	ssh -X pocoo.org ebook-convert /var/www/flask.pocoo.org/docs/flask-docs.epub /var/www/flask.pocoo.org/docs/flask-docs.mobi --cover http://flask.pocoo.org/docs/_images/logo-full.png --authors 'Armin Ronacher'
 
 docs:
 	$(MAKE) -C docs html

README

@@ -6,7 +6,7 @@
     ~ What is Flask?
 
       Flask is a microframework for Python based on Werkzeug
-      and Jinja2.  It's intended for small scale applications
+      and Jinja2.  It's intended for getting started very quickly
       and was developed with best intentions in mind.
 
     ~ Is it ready?
@@ -17,10 +17,11 @@
 
     ~ What do I need?
 
-      Jinja 2.4 and Werkzeug 0.6.1.  `pip` or `easy_install` will
-      install them for you if you do `easy_install Flask`.
-      I encourage you to use a virtualenv.  Check the docs for
-      complete installation and usage instructions.
+      Jinja 2.4 and Werkzeug 0.7 or later.
+      `pip` or `easy_install` will install them for you if you do
+      `pip install Flask`.  I encourage you to use a virtualenv.
+      Check the docs for complete installation and usage
+      instructions.
 
     ~ Where are the docs?
 
@@ -50,3 +51,5 @@
 
       Either use the #pocoo IRC channel on irc.freenode.net or
       ask on the mailinglist: http://flask.pocoo.org/mailinglist/
+
+      See http://flask.pocoo.org/community/ for more resources.

docs/_templates/sidebarintro.html

@@ -9,6 +9,8 @@ <h3>Other Formats</h3>
 </p>
 <ul>
   <li><a href="http://flask.pocoo.org/docs/flask-docs.pdf">as PDF</a>
+  <li><a href="http://flask.pocoo.org/docs/flask-docs.epub">as ePub</a>
+  <li><a href="http://flask.pocoo.org/docs/flask-docs.mobi">as .mobi</a>
   <li><a href="http://flask.pocoo.org/docs/flask-docs.zip">as zipped HTML</a>
 </ul>
 <h3>Useful Links</h3>

docs/advanced_foreword.rst

@@ -0,0 +1,68 @@
+.. _advanced_foreword:
+
+Foreword for Experienced Programmers
+====================================
+
+Thread-Locals in Flask
+----------------------
+
+One of the design decisions in Flask was that simple tasks should be simple;
+they should not take a lot of code and yet they should not limit you. Because
+of that, Flask has few design choices that some people might find surprising or
+unorthodox. 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. This approach is convenient, but requires a valid
+request context for dependency injection or when attempting to reuse code which
+uses a value pegged to the request.  The Flask project is honest about
+thread-locals, does not hide them, and calls out in the code and documentation
+where they are used.
+
+Develop for the Web with Caution
+--------------------------------
+
+Always keep security in mind when building web applications.
+
+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 securely.
+
+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 cause
+security problems.
+
+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.
+
+Flask is no different from any other framework in that you the developer must
+build with caution, watching for exploits when building to your requirements.
+
+The Status of Python 3
+----------------------
+
+Currently the Python community is in the process of improving libraries to
+support the new iteration of the Python programming language.  While the
+situation is greatly improving there are still some issues that make it
+hard for us to switch over to Python 3 just now.  These problems are
+partially caused by changes in the language that went unreviewed for too
+long, partially also because we have not quite worked out how the lower-
+level API should change to account for the Unicode differences in Python 3.
+
+Werkzeug and Flask will be ported to Python 3 as soon as a solution for
+the changes 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.  If you plan on upgrading to Python 3 in the near future we
+strongly recommend that you read `How to write forwards compatible
+Python code <http://lucumr.pocoo.org/2011/1/22/forwards-compatible-python/>`_.
+
+Continue to :ref:`installation` or the :ref:`quickstart`.

docs/api.rst

@@ -265,12 +265,16 @@ Useful Functions and Classes
 
    Points to the application handling the request.  This is useful for
    extensions that want to support multiple applications running side
-   by side.
+   by side.  This is powered by the application context and not by the
+   request context, so you can change the value of this proxy by
+   using the :meth:`~flask.Flask.app_context` method.
 
    This is a proxy.  See :ref:`notes-on-proxies` for more information.
 
 .. autofunction:: has_request_context
 
+.. autofunction:: has_app_context
+
 .. autofunction:: url_for
 
 .. function:: abort(code)
@@ -285,6 +289,8 @@ Useful Functions and Classes
 
 .. autofunction:: make_response
 
+.. autofunction:: after_this_request
+
 .. autofunction:: send_file
 
 .. autofunction:: send_from_directory
@@ -369,6 +375,11 @@ Extensions
 
    .. versionadded:: 0.8
 
+Stream Helpers
+--------------
+
+.. autofunction:: stream_with_context
+
 Useful Internals
 ----------------
 
@@ -412,6 +423,16 @@ Useful Internals
           if ctx is not None:
               return ctx.session
 
+.. autoclass:: flask.ctx.AppContext
+   :members:
+
+.. data:: _app_ctx_stack
+
+   Works similar to the request context but only binds the application.
+   This is mainly there for extensions to store data.
+
+   .. versionadded:: 0.9
+
 .. autoclass:: flask.blueprints.BlueprintSetupState
    :members:
 
@@ -455,8 +476,18 @@ Signals
 .. data:: request_tearing_down
 
    This signal is sent when the application is tearing down the request.
-   This is always called, even if an error happened.  No arguments are
-   provided.
+   This is always called, even if an error happened.  An `exc` keyword
+   argument is passed with the exception that caused the teardown.
+
+   .. versionchanged:: 0.9
+      The `exc` parameter was added.
+
+.. data:: appcontext_tearing_down
+
+   This signal is sent when the application is tearing down the
+   application context.  This is always called, even if an error happened.
+   An `exc` keyword argument is passed with the exception that caused the
+   teardown.
 
 .. currentmodule:: None
 
@@ -476,7 +507,7 @@ Signals
 
 .. _blinker: http://pypi.python.org/pypi/blinker
 
-Class Based Views
+Class-Based Views
 -----------------
 
 .. versionadded:: 0.7
@@ -511,7 +542,7 @@ Variable parts are passed to the view function as keyword arguments.
 The following converters are available:
 
 =========== ===============================================
-`unicode`   accepts any text without a slash (the default)
+`string`    accepts any text without a slash (the default)
 `int`       accepts integers
 `float`     like `int` but for floating point values
 `path`      like the default but also accepts slashes
@@ -562,7 +593,7 @@ with the route parameter the view function is defined with the decorator
 instead of the `view_func` parameter.
 
 =============== ==========================================================
-`rule`          the URL roule as string
+`rule`          the URL rule as string
 `endpoint`      the endpoint for the registered URL rule.  Flask itself
                 assumes that the name of the view function is the name
                 of the endpoint if not explicitly stated.
@@ -612,6 +643,10 @@ some defaults to :meth:`~flask.Flask.add_url_rule` or general behavior:
     decorators that want to customize the `OPTIONS` response on a per-view
     basis.
 
+-   `required_methods`: if this attribute is set, Flask will always add
+    these methods when registering a URL rule even if the methods were
+    explicitly overriden in the ``route()`` call.
+
 Full example::
 
     def index():