========
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 ``<input type="file" name="" />``.  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 ``<form>`` 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

.. class:: werkzeug.wrappers.UserAgentMixin

    .. property:: werkzeug.wrappers.UserAgentMixin.user_agent


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
