Upgrading to Newer Releases

Flask itself is changing like any software is changing over time. Most ofthe changes are the nice kind, the kind where you don’t have to changeanything in your code to profit from a new release.

However every once in a while there are changes that do require somechanges in your code or there are changes that make it possible for you toimprove your own code quality by taking advantage of new features inFlask.

This section of the documentation enumerates all the changes in Flask fromrelease to release and how you can change your code to have a painlessupdating experience.

Use the pip command to upgrade your existing Flask installation byproviding the —upgrade parameter:

  1. $ pip install --upgrade Flask

Version 0.12

Changes to send_file

The filename is no longer automatically inferred from file-like objects.This means that the following code will no longer automatically haveX-Sendfile support, etag generation or MIME-type guessing:

  1. response = send_file(open('/path/to/file.txt'))

Any of the following is functionally equivalent:

  1. fname = '/path/to/file.txt'
  3. # Just pass the filepath directly
  4. response = send_file(fname)
  6. # Set the MIME-type and ETag explicitly
  7. response = send_file(open(fname), mimetype='text/plain')
  8. response.set_etag(...)
  10. # Set `attachment_filename` for MIME-type guessing
  11. # ETag still needs to be manually set
  12. response = send_file(open(fname), attachment_filename=fname)
  13. response.set_etag(...)

The reason for this is that some file-like objects have an invalid or evenmisleading name attribute. Silently swallowing errors in such cases was nota satisfying solution.

Additionally the default of falling back to application/octet-stream hasbeen restricted. If Flask can’t guess one or the user didn’t provide one, thefunction fails if no filename information was provided.

Version 0.11

0.11 is an odd release in the Flask release cycle because it was supposedto be the 1.0 release. However because there was such a long lead time upto the release we decided to push out a 0.11 release first with somechanges removed to make the transition easier. If you have been trackingthe master branch which was 1.0 you might see some unexpected changes.

In case you did track the master branch you will notice thatflask —app is removed now.You need to use the environment variable to specify an application.

Debugging

Flask 0.11 removed the debug_log_format attribute from Flaskapplications. Instead the new LOGGER_HANDLER_POLICY configuration canbe used to disable the default log handlers and custom log handlers can beset up.

Error handling

The behavior of error handlers was changed.The precedence of handlers used to be based on the decoration/call order oferrorhandler() andregister_error_handler(), respectively.Now the inheritance hierarchy takes precedence and handlers for morespecific exception classes are executed instead of more general ones.See 错误处理 for specifics.

Trying to register a handler on an instance now raises ValueError.

Note

There used to be a logic error allowing you to register handlersonly for exception instances. This was unintended and plain wrong,and therefore was replaced with the intended behavior of registeringhandlers only using exception classes and HTTP error codes.

Templating

The render_template_string() function has changed toautoescape template variables by default. This better matches the behaviorof render_template().

Extension imports

Extension imports of the form flask.ext.foo are deprecated, you should useflask_foo.

The old form still works, but Flask will issue aflask.exthook.ExtDeprecationWarning for each extension you import the oldway. We also provide a migration utility called flask-ext-migrate that is supposed toautomatically rewrite your imports for this.

Version 0.10

The biggest change going from 0.9 to 0.10 is that the cookie serializationformat changed from pickle to a specialized JSON format. This change hasbeen done in order to avoid the damage an attacker can do if the secretkey is leaked. When you upgrade you will notice two major changes: allsessions that were issued before the upgrade are invalidated and you canonly store a limited amount of types in the session. The new sessions areby design much more restricted to only allow JSON with a few smallextensions for tuples and strings with HTML markup.

In order to not break people’s sessions it is possible to continue usingthe old session system by using the Flask-OldSessions extension.

Flask also started storing the flask.g object on the applicationcontext instead of the request context. This change should be transparentfor you but it means that you now can store things on the g objectwhen there is no request context yet but an application context. The oldflask.Flask.request_globals_class attribute was renamed toflask.Flask.app_ctx_globals_class.

Version 0.9

The behavior of returning tuples from a function was simplified. If youreturn a tuple it no longer defines the arguments for the response objectyou’re creating, it’s now always a tuple in the form (response, status,headers) where at least one item has to be provided. If you depend onthe old behavior, you can add it easily by subclassing Flask:

  1. class TraditionalFlask(Flask):
  2.     def make_response(self, rv):
  3.         if isinstance(rv, tuple):
  4.             return self.response_class(*rv)
  5.         return Flask.make_response(self, rv)

If you maintain an extension that was using _request_ctx_stackbefore, please consider changing to _app_ctx_stack if it makessense for your extension. For instance, the app context stack makes sense forextensions which connect to databases. Using the app context stack instead ofthe request context stack will make extensions more readily handle use casesoutside of requests.

Version 0.8

Flask introduced a new session interface system. We also noticed thatthere was a naming collision between flask.session the module thatimplements sessions and flask.session which is the global sessionobject. With that introduction we moved the implementation details forthe session system into a new module called flask.sessions. If youused the previously undocumented session support we urge you to upgrade.

If invalid JSON data was submitted Flask will now raise aBadRequest exception instead of letting thedefault ValueError bubble up. This has the advantage that you nolonger have to handle that error to avoid an internal server error showingup for the user. If you were catching this down explicitly in the pastas ValueError you will need to change this.

Due to a bug in the test client Flask 0.7 did not trigger teardownhandlers when the test client was used in a with statement. This wassince fixed but might require some changes in your test suites if yourelied on this behavior.

Version 0.7

In Flask 0.7 we cleaned up the code base internally a lot and did somebackwards incompatible changes that make it easier to implement largerapplications with Flask. Because we want to make upgrading as easy aspossible we tried to counter the problems arising from these changes byproviding a script that can ease the transition.

The script scans your whole application and generates a unified diff withchanges it assumes are safe to apply. However as this is an automatedtool it won’t be able to find all use cases and it might miss some. Weinternally spread a lot of deprecation warnings all over the place to makeit easy to find pieces of code that it was unable to upgrade.

We strongly recommend that you hand review the generated patchfile andonly apply the chunks that look good.

If you are using git as version control system for your project werecommend applying the patch with path -p1 < patchfile.diff and thenusing the interactive commit feature to only apply the chunks that lookgood.

To apply the upgrade script do the following:

  1. $ python flask-07-upgrade.py > patchfile.diff

  • Review the generated patchfile.

  • Apply the patch:

  1. $ patch -p1 < patchfile.diff
  • If you were using per-module template folders you need to move sometemplates around. Previously if you had a folder named templatesnext to a blueprint named admin the implicit template pathautomatically was admin/index.html for a template file calledtemplates/index.html. This no longer is the case. Now you needto name the template templates/admin/index.html. The tool willnot detect this so you will have to do that on your own.

Please note that deprecation warnings are disabled by default startingwith Python 2.7. In order to see the deprecation warnings that might beemitted you have to enabled them with the warnings module.

If you are working with windows and you lack the patch command lineutility you can get it as part of various Unix runtime environments forwindows including cygwin, msysgit or ming32. Also source control systemslike svn, hg or git have builtin support for applying unified diffs asgenerated by the tool. Check the manual of your version control systemfor more information.

Bug in Request Locals

Due to a bug in earlier implementations the request local proxies nowraise a RuntimeError instead of an AttributeError when theyare unbound. If you caught these exceptions with AttributeErrorbefore, you should catch them with RuntimeError now.

Additionally the send_file() function is now issuingdeprecation warnings if you depend on functionality that will be removedin Flask 0.11. Previously it was possible to use etags and mimetypeswhen file objects were passed. This was unreliable and caused issuesfor a few setups. If you get a deprecation warning, make sure toupdate your application to work with either filenames there or disableetag attaching and attach them yourself.

Old code:

  1. return send_file(my_file_object)
  2. return send_file(my_file_object)

New code:

  1. return send_file(my_file_object, add_etags=False)

Upgrading to new Teardown Handling

We streamlined the behavior of the callbacks for request handling. Forthings that modify the response the after_request()decorators continue to work as expected, but for things that absolutelymust happen at the end of request we introduced the newteardown_request() decorator. Unfortunately thatchange also made after-request work differently under error conditions.It’s not consistently skipped if exceptions happen whereas previously itmight have been called twice to ensure it is executed at the end of therequest.

If you have database connection code that looks like this:

  1. @app.after_request
  2. def after_request(response):
  3.     g.db.close()
  4.     return response

You are now encouraged to use this instead:

  1. @app.teardown_request
  2. def after_request(exception):
  3.     if hasattr(g, 'db'):
  4.         g.db.close()

On the upside this change greatly improves the internal code flow andmakes it easier to customize the dispatching and error handling. Thismakes it now a lot easier to write unit tests as you can prevent closingdown of database connections for a while. You can take advantage of thefact that the teardown callbacks are called when the response context isremoved from the stack so a test can query the database after requesthandling:

  1. with app.test_client() as client:
  2.     resp = client.get('/')
  3.     # g.db is still bound if there is such a thing
  5. # and here it's gone

Manual Error Handler Attaching

While it is still possible to attach error handlers toFlask.error_handlers it’s discouraged to do so and in factdeprecated. In general we no longer recommend custom error handlerattaching via assignments to the underlying dictionary due to the morecomplex internal handling to support arbitrary exception classes andblueprints. See Flask.errorhandler() for more information.

The proper upgrade is to change this:

  1. app.error_handlers[403] = handle_error

Into this:

  1. app.register_error_handler(403, handle_error)

Alternatively you should just attach the function with a decorator:

  1. @app.errorhandler(403)
  2. def handle_error(e):
  3.     ...

(Note that register_error_handler() is new in Flask 0.7)

Blueprint Support

Blueprints replace the previous concept of “Modules” in Flask. Theyprovide better semantics for various features and work better with largeapplications. The update script provided should be able to upgrade yourapplications automatically, but there might be some cases where it failsto upgrade. What changed?

  • Blueprints need explicit names. Modules had an automatic nameguessing scheme where the shortname for the module was taken from thelast part of the import module. The upgrade script tries to guessthat name but it might fail as this information could change atruntime.

  • Blueprints have an inverse behavior for url_for(). Previously.foo told url_for() that it should look for the endpointfoo on the application. Now it means “relative to current module”.The script will inverse all calls to url_for() automatically foryou. It will do this in a very eager way so you might end up withsome unnecessary leading dots in your code if you’re not usingmodules.

  • Blueprints do not automatically provide static folders. They willalso no longer automatically export templates from a folder calledtemplates next to their location however but it can be enabled fromthe constructor. Same with static files: if you want to continueserving static files you need to tell the constructor explicitly thepath to the static folder (which can be relative to the blueprint’smodule path).

  • Rendering templates was simplified. Now the blueprints can providetemplate folders which are added to a general template searchpath.This means that you need to add another subfolder with the blueprint’sname into that folder if you want blueprintname/template.html asthe template name.

If you continue to use the Module object which is deprecated, Flask willrestore the previous behavior as good as possible. However we stronglyrecommend upgrading to the new blueprints as they provide a lot of usefulimprovement such as the ability to attach a blueprint multiple times,blueprint specific error handlers and a lot more.

Version 0.6

Flask 0.6 comes with a backwards incompatible change which affects theorder of after-request handlers. Previously they were called in the orderof the registration, now they are called in reverse order. This changewas made so that Flask behaves more like people expected it to work andhow other systems handle request pre- and post-processing. If youdepend on the order of execution of post-request functions, be sure tochange the order.

Another change that breaks backwards compatibility is that contextprocessors will no longer override values passed directly to the templaterendering function. If for example request is as variable passeddirectly to the template, the default context processor will not overrideit with the current request object. This makes it easier to extendcontext processors later to inject additional variables without breakingexisting template not expecting them.

Version 0.5

Flask 0.5 is the first release that comes as a Python package instead of asingle module. There were a couple of internal refactoring so if youdepend on undocumented internal details you probably have to adapt theimports.

The following changes may be relevant to your application:

  • autoescaping no longer happens for all templates. Instead it isconfigured to only happen on files ending with .html, .htm,.xml and .xhtml. If you have templates with differentextensions you should override theselect_jinja_autoescape() method.

  • Flask no longer supports zipped applications in this release. Thisfunctionality might come back in future releases if there is demandfor this feature. Removing support for this makes the Flask internalcode easier to understand and fixes a couple of small issues that makedebugging harder than necessary.

  • The create_jinja_loader function is gone. If you want to customizethe Jinja loader now, use thecreate_jinja_environment() method instead.

Version 0.4

For application developers there are no changes that require changes inyour code. In case you are developing on a Flask extension however, andthat extension has a unittest-mode you might want to link the activationof that mode to the new TESTING flag.

Version 0.3

Flask 0.3 introduces configuration support and logging as well ascategories for flashing messages. All these are features that are 100%backwards compatible but you might want to take advantage of them.

Configuration Support

The configuration support makes it easier to write any kind of applicationthat requires some sort of configuration. (Which most likely is the casefor any application out there).

If you previously had code like this:

  1. app.debug = DEBUG
  2. app.secret_key = SECRET_KEY

You no longer have to do that, instead you can just load a configurationinto the config object. How this works is outlined in 配置管理.

Logging Integration

Flask now configures a logger for you with some basic and useful defaults.If you run your application in production and want to profit fromautomatic error logging, you might be interested in attaching a proper loghandler. Also you can start logging warnings and errors into the loggerwhen appropriately. For more information on that, read应用错误处理.

Categories for Flash Messages

Flash messages can now have categories attached. This makes it possibleto render errors, warnings or regular messages differently for example.This is an opt-in feature because it requires some rethinking in the code.

Read all about that in the 消息闪现 pattern.