Transition to Werkzeug 1.0

Werkzeug originally had a magical import system hook that enabledeverything to be imported from one module and still loading the actualimplementations lazily as necessary. Unfortunately this turned out to beslow and also unreliable on alternative Python implementations andGoogle’s App Engine.

Starting with 0.7 we recommend against the short imports and stronglyencourage starting importing from the actual implementation module.Werkzeug 1.0 will disable the magical import hook completely.

Because finding out where the actual functions are imported and rewritingthem by hand is a painful and boring process we wrote a tool that aids inmaking this transition.

Automatically Rewriting Imports

For instance, with Werkzeug < 0.7 the recommended way to use the escape functionwas this:

  1. from werkzeug import escape

With Werkzeug 0.7, the recommended way to import this function isdirectly from the utils module (and with 1.0 this will become mandatory).To automatically rewrite all imports one can use thewerkzeug-import-rewrite script.

You can use it by executing it with Python and with a list of folders withWerkzeug based code. It will then spit out a hg/git compatible patchfile. Example patch file creation:

  1. $ python werkzeug-import-rewrite.py . > new-imports.udiff

To apply the patch one of the following methods work:

hg:

  1. hg import new-imports.udiff

git:

  1. git apply new-imports.udiff

patch:

  1. patch -p1 < new-imports.udiff

Deprecated and Removed Code

Some things that were relevant to Werkzeug’s core (working with WSGI andHTTP) have been removed. These were not commonly used, or are betterserved by dedicated libraries.

  • werkzeug.script, replace with Click or another dedicatedcommand line library.
  • werkzeug.template, replace with Jinja or another dedicatedtemplate library.
  • werkzeug.contrib.jsrouting, this type of URL generation inJavaScript did not scale well. Instead, generate URLs whenrendering templates, or add a URL field to a JSON response.
  • werkzeug.contrib.kickstart, replace with custom code if needed,the Werkzeug API has improved in general. Flask is a higher-levelversion of this.
  • werkzeug.contrib.testtools, was not significantly useful overthe default behavior.
  • werkzeug.contrib.cache, has been extracted to cachelib.
  • werkzeug.contrib.atom, was outside the core focus of Werkzeug,replace with a dedicated feed generation library.
  • werkzeug.contrib.limiter, stream limiting is better handled bythe WSGI server library instead of middleware.