Werkzeug Documentation (0.15.X) Release 0.15.6
Total Page：16
File Type：pdf, Size：1020Kb
Werkzeug Documentation (0.15.x) Release 0.15.6 Pallets Jan 26, 2020 Contents 1 Getting Started 3 1.1 Installation................................................3 1.2 Transition to Werkzeug 1.0........................................5 1.3 Werkzeug Tutorial............................................6 1.4 API Levels................................................ 14 1.5 Quickstart................................................ 15 2 Serving and Testing 21 2.1 Serving WSGI Applications....................................... 21 2.2 Test Utilities............................................... 26 2.3 Debugging Applications......................................... 32 3 Reference 37 3.1 Request / Response Objects....................................... 37 3.2 URL Routing............................................... 54 3.3 WSGI Helpers.............................................. 67 3.4 Filesystem Utilities............................................ 74 3.5 HTTP Utilities.............................................. 74 3.6 Data Structures.............................................. 83 3.7 Utilities.................................................. 99 3.8 URL Helpers............................................... 106 3.9 Context Locals.............................................. 112 3.10 Middleware................................................ 115 3.11 HTTP Exceptions............................................ 121 4 Deployment 127 4.1 Application Deployment......................................... 127 5 Contributed Modules 133 5.1 Contributed Modules........................................... 133 6 Additional Information 153 6.1 Important Terms............................................. 153 6.2 Unicode.................................................. 154 6.3 Dealing with Request Data........................................ 155 6.4 Changelog................................................ 157 i Python Module Index 187 Index 189 ii Werkzeug Documentation (0.15.x), Release 0.15.6 werkzeug German noun: “tool”. Etymology: werk (“work”), zeug (“stuff”) Werkzeug is a comprehensive WSGI web application library. It began as a simple collection of various utilities for WSGI applications and has become one of the most advanced WSGI utility libraries. Werkzeug is Unicode aware and doesn’t enforce any dependencies. It is up to the developer to choose a template engine, database adapter, and even how to handle requests. Contents 1 Werkzeug Documentation (0.15.x), Release 0.15.6 2 Contents CHAPTER 1 Getting Started 1.1 Installation 1.1.1 Python Version We recommend using the latest version of Python 3. Werkzeug supports Python 3.4 and newer and Python 2.7. 1.1.2 Dependencies Werkzeug does not have any direct dependencies. Optional dependencies These distributions will not be installed automatically. Werkzeug will detect and use them if you install them. • SimpleJSON is a fast JSON implementation that is compatible with Python’s json module. It is preferred for JSON operations if it is installed. • termcolor provides request log highlighting when using the development server. • Watchdog provides a faster, more efficient reloader for the development server. 1.1.3 Virtual environments Use a virtual environment to manage the dependencies for your project, both in development and in production. What problem does a virtual environment solve? The more Python projects you have, the more likely it is that you need to work with different versions of Python libraries, or even Python itself. Newer versions of libraries for one project can break compatibility in another project. Virtual environments are independent groups of Python libraries, one for each project. Packages installed for one project will not affect other projects or the operating system’s packages. 3 Werkzeug Documentation (0.15.x), Release 0.15.6 Python 3 comes bundled with the venv module to create virtual environments. If you’re using a modern version of Python, you can continue on to the next section. If you’re using Python 2, see Install virtualenv first. Create an environment Create a project folder and a venv folder within: mkdir myproject cd myproject python3 -m venv venv On Windows: py -3 -m venv venv If you needed to install virtualenv because you are on an older version of Python, use the following command instead: virtualenv venv On Windows: \Python27\Scripts\virtualenv.exe venv Activate the environment Before you work on your project, activate the corresponding environment: . venv/bin/activate On Windows: venv\Scripts\activate Your shell prompt will change to show the name of the activated environment. 1.1.4 Install Werkzeug Within the activated environment, use the following command to install Werkzeug: pip install Werkzeug Living on the edge If you want to work with the latest Werkzeug code before it’s released, install or update the code from the master branch: pip install -U https://github.com/pallets/werkzeug/archive/master.tar.gz 4 Chapter 1. Getting Started Werkzeug Documentation (0.15.x), Release 0.15.6 1.1.5 Install virtualenv If you are using Python 2, the venv module is not available. Instead, install virtualenv. On Linux, virtualenv is provided by your package manager: # Debian, Ubuntu sudo apt-get install python-virtualenv # CentOS, Fedora sudo yum install python-virtualenv # Arch sudo pacman -S python-virtualenv If you are on Mac OS X or Windows, download get-pip.py, then: sudo python2 Downloads/get-pip.py sudo python2 -m pip install virtualenv On Windows, as an administrator: \Python27\python.exe Downloads\get-pip.py \Python27\python.exe -m pip install virtualenv Now you can continue to Create an environment. 1.2 Transition to Werkzeug 1.0 Werkzeug originally had a magical import system hook that enabled everything to be imported from one module and still loading the actual implementations lazily as necessary. Unfortunately this turned out to be slow and also unreliable on alternative Python implementations and Google’s App Engine. Starting with 0.7 we recommend against the short imports and strongly encourage 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 rewriting them by hand is a painful and boring process we wrote a tool that aids in making this transition. 1.2.1 Automatically Rewriting Imports For instance, with Werkzeug < 0.7 the recommended way to use the escape function was this: from werkzeug import escape With Werkzeug 0.7, the recommended way to import this function is directly from the utils module (and with 1.0 this will become mandatory). To automatically rewrite all imports one can use the werkzeug-import-rewrite script. You can use it by executing it with Python and with a list of folders with Werkzeug based code. It will then spit out a hg/git compatible patch file. Example patch file creation: $ python werkzeug-import-rewrite.py . > new-imports.udiff To apply the patch one of the following methods work: hg: 1.2. Transition to Werkzeug 1.0 5 Werkzeug Documentation (0.15.x), Release 0.15.6 hg import new-imports.udiff git: git apply new-imports.udiff patch: patch-p1< new-imports.udiff 1.2.2 Deprecated and Removed Code Some things that were relevant to Werkzeug’s core (working with WSGI and HTTP) have been removed. These were not commonly used, or are better served by dedicated libraries. • werkzeug.script, replace with Click or another dedicated command line library. • werkzeug.template, replace with Jinja or another dedicated template library. • werkzeug.contrib.jsrouting, this type of URL generation in JavaScript did not scale well. Instead, generate URLs when rendering 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-level version of this. • werkzeug.contrib.testtools, was not significantly useful over the 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 genera- tion library. • werkzeug.contrib.limiter, stream limiting is better handled by the WSGI server library instead of middleware. 1.3 Werkzeug Tutorial Welcome to the Werkzeug tutorial in which we will create a TinyURL clone that stores URLs in a redis instance. The libraries we will use for this applications are Jinja 2 for the templates, redis for the database layer and, of course, Werkzeug for the WSGI layer. You can use pip to install the required libraries: pip install Jinja2 redis Werkzeug Also make sure to have a redis server running on your local machine. If you are on OS X, you can use brew to install it: brew install redis If you are on Ubuntu or Debian, you can use apt-get: sudo apt-get install redis-server Redis was developed for UNIX systems and was never really designed to work on Windows. For development pur- poses, the unofficial ports however work well enough. You can get them from github. 6 Chapter 1. Getting Started Werkzeug Documentation (0.15.x), Release 0.15.6 1.3.1 Introducing Shortly In this tutorial, we will together create a simple URL shortener service with Werkzeug. Please keep in mind that Werkzeug is not a framework, it’s a library with utilities to create your own framework or application and as such is very flexible. The approach we use here is just one of many you can use. As data store, we will use redis here instead of a relational database to keep this simple and because