======== Wrappers ======== .. module:: werkzeug.wrappers You can import all these objects directly from `werkzeug`. Base Wrappers ============= These objects implement a common set of operations. They are missing fancy addon functionality like user agent parsing or etag handling. These features are available by mixing in various mixin classes or using `Request` and `Response`. .. class:: werkzeug.wrappers.BaseRequest **Creating Request Objects** .. def:: werkzeug.wrappers.BaseRequest.__init__ .. def:: werkzeug.wrappers.BaseRequest.from_values .. def:: werkzeug.wrappers.BaseRequest.application **Properties** `path` The current path requested, relative to the position where the WSGI application is mounted (`PATH_INFO`). It will contain a leading slash and will be at least a string with a single slash when accessing the URL root. `script_root` The root path for the script (`SCRIPT_NAME`). Does not contain a trailing slash. `url` The full URL for the current request. `base_url` The current full URL without the query string. `url_root` The current URL up to the script root. `host_url` The current URL for the host. `host` The current hostname, without scheme. `is_secure` True if this is an HTTPS request. `is_multithread` True if this request was created in a multithreaded environment. `is_multiprocess` True if this request was created in a forking environment. `is_run_once` True if this request was created on the command line, a CGI script or a similar environment. `is_xhr` True if the request was triggered via an JavaScript XMLHttpRequest. This only works with libraries that support the X-Requested-With header and set it to "XMLHttpRequest". Libraries that do that are prototype, jQuery and Mochikit and probably some more. `method` The request method. `GET`, `POST` etc. `args` A dictionary-like object containing all given HTTP GET parameters. See the `MultiDict` documentation in the `utils`_ section. `form` A dictionary-like object containing all given HTTP POST parameters. See the `MultiDict` documentation in the `utils`_ section. This dict does not contain uploaded files, see `files` regarding that. `values` An immutable dictionary-like object containing both the `args` and `form` values. See the `CombinedMultiDict` documentation in the `utils`_ section. `cookies` A dictionary with the submitted cookie values. `files` A dictionary-like object containing all uploaded files. Each key in `files` is the name from the ````. Each value in `files` is a Werkzeug `FileStorage` object with the following members: - `filename` - The name of the uploaded file, as a Python string. - `type` - The content type of the uploaded file. - `data` - The raw content of the uploaded file. - `read()` - Read from the stream. Note that `files` will only contain data if the request method was POST and the ``
`` that posted to the request had ``enctype="multipart/form-data"``. It will be empty otherwise. See the `MultiDict` / `FileStorage` documentation in the `utils`_ section for more details about the used data structure. `environ` The WSGI environment used to create the request object. `stream` The buffered stream with incoming data from the webbrowser if the submitted data was not multipart or URL-encoded form data. `input_stream` The input stream provided by the client. Used internally by the form data parser. Reading from this stream must never be mixed with accessing `stream`, `data`, `files`, or `form`, because then it's not guaranteed that more data is requested from the client than expected. Never read beyond ``environ['CONTENT_LENGTH']``. `data` Accessing this the first time reads the whole `stream` and stores it. Keep in mind that this does not read the whole WSGI input stream like Django does. `remote_addr` The remote address for the user that created this request. If the class variable `is_behind_proxy` is set to `True` (either by subclassing the process or overriding this variable on the instance) it will try to get the value from the `X_HTTP_FORWARDED_FOR` header. Keep in mind that this is disabled by default because unless you are really behind a proxy this is a security problem. `access_route` If you are behind a proxy server this will list all the IP addresses that take place in the request. The end user IP address is the first one in the list, the last proxy server is the last item in the list. This also works if the `is_behind_proxy` class variable is set to `False`. .. class:: werkzeug.wrappers.BaseResponse **Creating Response Objects** .. def:: werkzeug.wrappers.BaseResponse.__init__ .. def:: werkzeug.wrappers.BaseResponse.force_type .. def:: werkzeug.wrappers.BaseResponse.from_app **Properties** `response` The application iterator. If constructed from a string this will be a list, otherwise the object provided as application iterator. `headers` A `Headers` object representing the response headers. `status` The response status as string. `status_code` The response status as integer. `data` When accessed the response iterator is buffered and, encoded and returned as bytestring. `header_list` Read only list that contains the current list for the headers in the response encoding. `is_streamed` If the response is streamed (the response is not a sequence) this property is `True`. In this case streamed means that there is no information about the number of iterations. This is usully `True` if a generator is passed to the response object. This is useful for checking before applying some sort of post filtering that should not take place for streamed responses. **Methods** .. def:: werkzeug.wrappers.BaseResponse.iter_encoded .. def:: werkzeug.wrappers.BaseResponse.set_cookie .. def:: werkzeug.wrappers.BaseResponse.delete_cookie .. def:: werkzeug.wrappers.BaseResponse.fix_headers .. def:: werkzeug.wrappers.BaseResponse.close .. def:: werkzeug.wrappers.BaseResponse.freeze .. def:: werkzeug.wrappers.BaseResponse.__call__ Mixin Classes ============= Werkzeug also provides helper mixins for various HTTP related functionality such as etags, cache control, user agents etc. When subclassing you can mix those classes in to extend the functionality of the `BaseRequest` or `BaseResponse` object. Here a small example for a request object that parses accept headers:: from werkzeug import BaseRequest, AcceptMixin class Request(BaseRequest, AcceptMixin): pass The `Request` and `Response` classes subclass the `BaseRequest` and `BaseResponse` classes and implement all the mixins Werkzeug provides: .. class:: werkzeug.wrappers.Request .. class:: werkzeug.wrappers.Response .. class:: werkzeug.wrappers.AcceptMixin .. property:: werkzeug.wrappers.AcceptMixin.accept_mimetypes .. property:: werkzeug.wrappers.AcceptMixin.accept_charsets .. property:: werkzeug.wrappers.AcceptMixin.accept_encodings .. property:: werkzeug.wrappers.AcceptMixin.accept_languages All this properties store `Accept` objects as documented in the `utils`_ section. .. class:: werkzeug.wrappers.AuthorizationMixin .. property:: werkzeug.wrappers.AuthorizationMixin.authorization .. class:: werkzeug.wrappers.ETagRequestMixin .. property:: werkzeug.wrappers.ETagRequestMixin.cache_control .. property:: werkzeug.wrappers.ETagRequestMixin.if_match .. property:: werkzeug.wrappers.ETagRequestMixin.if_none_match .. property:: werkzeug.wrappers.ETagRequestMixin.if_modified_since .. property:: werkzeug.wrappers.ETagRequestMixin.if_unmodified_since All the used data structures are documented in the `utils`_ section. .. class:: werkzeug.wrappers.ETagResponseMixin .. property:: werkzeug.wrappers.ETagResponseMixin.cache_control .. def:: werkzeug.wrappers.ETagResponseMixin.make_conditional .. def:: werkzeug.wrappers.ETagResponseMixin.add_etag .. def:: werkzeug.wrappers.ETagResponseMixin.set_etag .. def:: werkzeug.wrappers.ETagResponseMixin.get_etag .. def:: werkzeug.wrappers.ETagResponseMixin.freeze .. class:: werkzeug.wrappers.ResponseStreamMixin .. property:: werkzeug.wrappers.ResponseStreamMixin.stream .. class:: werkzeug.wrappers.CommonResponseDescriptorsMixin .. property:: werkzeug.wrappers.CommonResponseDescriptorsMixin.mimetype .. property:: werkzeug.wrappers.CommonResponseDescriptorsMixin.location .. property:: werkzeug.wrappers.CommonResponseDescriptorsMixin.age .. property:: werkzeug.wrappers.CommonResponseDescriptorsMixin.content_type .. property:: werkzeug.wrappers.CommonResponseDescriptorsMixin.content_length .. property:: werkzeug.wrappers.CommonResponseDescriptorsMixin.content_location .. property:: werkzeug.wrappers.CommonResponseDescriptorsMixin.content_encoding .. property:: werkzeug.wrappers.CommonResponseDescriptorsMixin.content_language .. property:: werkzeug.wrappers.CommonResponseDescriptorsMixin.content_md5 .. property:: werkzeug.wrappers.CommonResponseDescriptorsMixin.date .. property:: werkzeug.wrappers.CommonResponseDescriptorsMixin.expires .. property:: werkzeug.wrappers.CommonResponseDescriptorsMixin.last_modified .. property:: werkzeug.wrappers.CommonResponseDescriptorsMixin.retry_after .. property:: werkzeug.wrappers.CommonResponseDescriptorsMixin.vary .. property:: werkzeug.wrappers.CommonResponseDescriptorsMixin.allow .. class:: werkzeug.wrappers.WWWAuthenticateMixin .. property:: werkzeug.wrappers.WWWAuthenticateMixin.www_authenticate Note on File Uploads ==================== File uploads are a tricky thing in general. Per default all the file uploads go into temporary files on the filesystem and not the memory of the current process to avoid high memory usage. You could also change that to store the data somewhere else by implementing an object that implements the python IO protocol (see `StringIO`) for both writing and reading. Then you have to subclass a request object and override `_get_file_stream`: .. def:: werkzeug.wrappers.BaseRequest._get_file_stream .. _utils: utils.txt