webob.response -- Response — WebOb 1.8.7 documentation

# `webob.response` -- Response

## Response

class webob.response.Response(body=None, status=None, headerlist=None, app_iter=None, content_type=None, conditional_response=None, charset=<object object>, **kw)

  Represents a WSGI response.

  If no arguments are passed, creates a `Response` that uses a variety of defaults. The defaults may be changed by sub-classing the `Response`. See the sub-classing notes.

  Variables:

    - ~Response.body (bytes or text_type) -- If `body` is a `text_type`, then it will be encoded using either `charset` when provided or `default_encoding` when `charset` is not provided if the `content_type` allows for a `charset`. This argument is mutually exclusive with `app_iter`.

    - ~Response.status (int or str) -- Either an `int` or a string that is an integer followed by the status text. If it is an integer, it will be converted to a proper status that also includes the status text. Any existing status text will be kept. Non-standard values are allowed.

    - ~Response.headerlist (list) -- A list of HTTP headers for the response.

    - ~Response.app_iter (iterable) -- An iterator that is used as the body of the response. Should conform to the WSGI requirements and should provide bytes. This argument is mutually exclusive with `body`.

    - ~Response.content_type (str or None) -- Sets the `Content-Type` header. If no `content_type` is provided, and there is no `headerlist`, the `default_content_type` will be automatically set. If `headerlist` is provided then this value is ignored.

    - conditional_response (bool) -- Used to change the behavior of the `Response` to check the original request for conditional response headers. See `conditional_response_app()` for more information.

    - ~Response.charset (str or None) -- Adds a `charset` `Content-Type` parameter. If no `charset` is provided and the `Content-Type` is text, then the `default_charset` will automatically be added. Currently the only `Content-Type`'s that allow for a `charset` are defined to be `text/*`, `application/xml`, and `*/*+xml`. Any other `Content-Type`'s will not have a `charset` added. If a `headerlist` is provided this value is ignored.

  All other response attributes may be set on the response by providing them as keyword arguments. A `TypeError` will be raised for any unexpected keywords.

  Sub-classing notes:

  - The `default_content_type` is used as the default for the `Content-Type` header that is returned on the response. It is `text/html`.

  - The `default_charset` is used as the default character set to return on the `Content-Type` header, if the `Content-Type` allows for a `charset` parameter. Currently the only `Content-Type`'s that allow for a `charset` are defined to be: `text/*`, `application/xml`, and `*/*+xml`. Any other `Content-Type`'s will not have a `charset` added.

  - The `unicode_errors` is set to `strict`, and access on a `text` will raise an error if it fails to decode the `body`.

  - `default_conditional_response` is set to `False`. This flag may be set to `True` so that all `Response` objects will attempt to check the original request for conditional response headers. See `conditional_response_app()` for more information.

  - `default_body_encoding` is set to 'UTF-8' by default. It exists to allow users to get/set the `Response` object using `.text`, even if no `charset` has been set for the `Content-Type`.

  classmethod from_file(fp)

    Reads a response from a file-like object (it must implement `.read(size)` and `.readline()`).

    It will read up to the end of the response, not the end of the file.

    This reads the response as represented by `str(resp)`; it may not read every valid HTTP response properly. Responses must have a `Content-Length`.

  copy()

    Makes a copy of the response.

  property status

    The status string.

  property status_code

    The status as an integer.

  property status_int

    The status as an integer.

  property headerlist

    The list of response headers.

  property headers

    The headers in a dictionary-like object.

  property body

    The body of the response, as a `bytes`. This will read in the entire app_iter if necessary.

  property json

    Set/get the body of the response as JSON.

    Note

    This will automatically `decode()` the `body` as `UTF-8` on get, and `encode()` the `json.dumps()` as `UTF-8` before assigning to `body`.

  property json_body

    Set/get the body of the response as JSON.

    Note

    This will automatically `decode()` the `body` as `UTF-8` on get, and `encode()` the `json.dumps()` as `UTF-8` before assigning to `body`.

  property has_body

    Determine if the the response has a `body`. In contrast to simply accessing `body`, this method will not read the underlying `app_iter`.

  property text

    Get/set the text value of the body using the `charset` of the `Content-Type` or the `default_body_encoding`.

  property unicode_body

    Deprecated alias for .text

  property ubody

    Deprecated alias for .text

  property body_file

    A file-like object that can be used to write to the body. If you passed in a list `app_iter`, that `app_iter` will be modified by writes.

  property app_iter

    Returns the `app_iter` of the response.

    If `body` was set, this will create an `app_iter` from that `body` (a single-item list).

  property allow

    Gets and sets the `Allow` header (HTTP spec section 14.7). Converts it using list.

  property vary

    Gets and sets the `Vary` header (HTTP spec section 14.44). Converts it using list.

  property content_length

    Gets and sets the `Content-Length` header (HTTP spec section 14.17). Converts it using int.

  property content_encoding

    Gets and sets the `Content-Encoding` header (HTTP spec section 14.11).

  property content_language

    Gets and sets the `Content-Language` header (HTTP spec section 14.12). Converts it using list.

  property content_location

    Gets and sets the `Content-Location` header (HTTP spec section 14.14).

  property content_md5

    Gets and sets the `Content-MD5` header (HTTP spec section 14.14).

  property content_disposition

    Gets and sets the `Content-Disposition` header (HTTP spec section 19.5.1).

  property accept_ranges

    Gets and sets the `Accept-Ranges` header (HTTP spec section 14.5).

  property content_range

    Gets and sets the `Content-Range` header (HTTP spec section 14.16). Converts it using ContentRange object.

  property date

    Gets and sets the `Date` header (HTTP spec section 14.18). Converts it using HTTP date.

  property expires

    Gets and sets the `Expires` header (HTTP spec section 14.21). Converts it using HTTP date.

  property last_modified

    Gets and sets the `Last-Modified` header (HTTP spec section 14.29). Converts it using HTTP date.

  property etag

    Gets and sets the `ETag` header (HTTP spec section 14.19). Converts it using Entity tag.

  property location

    Gets and sets the `Location` header (HTTP spec section 14.30).

  property pragma

    Gets and sets the `Pragma` header (HTTP spec section 14.32).

  property age

    Gets and sets the `Age` header (HTTP spec section 14.6). Converts it using int.

  property retry_after

    Gets and sets the `Retry-After` header (HTTP spec section 14.37). Converts it using HTTP date or delta seconds.

  property server

    Gets and sets the `Server` header (HTTP spec section 14.38).

  property www_authenticate

    Gets and sets the `WWW-Authenticate` header (HTTP spec section 14.47). Converts it using `parse_auth` and `serialize_auth`.

  property charset

    Get/set the `charset` specified in `Content-Type`.

    There is no checking to validate that a `content_type` actually allows for a `charset` parameter.

  property content_type

    Get/set the `Content-Type` header. If no `Content-Type` header is set, this will return `None`.

    Changed in version 1.7: Setting a new `Content-Type` will remove all `Content-Type` parameters and reset the `charset` to the default if the `Content-Type` is `text/*` or XML (`application/xml` or `*/*+xml`).

    To preserve all `Content-Type` parameters, you may use the following code:

        resp = Response()
        params = resp.content_type_params
        resp.content_type = 'application/something'
        resp.content_type_params = params

  property content_type_params

    A dictionary of all the parameters in the content type.

    (This is not a view, set to change, modifications of the dict will not be applied otherwise.)

  set_cookie(name, value='', max_age=None, path='/', domain=None, secure=False, httponly=False, comment=None, expires=None, overwrite=False, samesite=None)

    Set (add) a cookie for the response.

    Arguments are:

    `name`

    > The cookie name.

    `value`

    > The cookie value, which should be a string or `None`. If `value` is `None`, it's equivalent to calling the `webob.response.Response.unset_cookie()` method for this cookie key (it effectively deletes the cookie on the client).

    `max_age`

    > An integer representing a number of seconds, `datetime.timedelta`, or `None`. This value is used as the `Max-Age` of the generated cookie. If `expires` is not passed and this value is not `None`, the `max_age` value will also influence the `Expires` value of the cookie (`Expires` will be set to `now` + `max_age`). If this value is `None`, the cookie will not have a `Max-Age` value (unless `expires` is set). If both `max_age` and `expires` are set, this value takes precedence.

    `path`

    > A string representing the cookie `Path` value. It defaults to `/`.

    `domain`

    > A string representing the cookie `Domain`, or `None`. If domain is `None`, no `Domain` value will be sent in the cookie.

    `secure`

    > A boolean. If it's `True`, the `secure` flag will be sent in the cookie, if it's `False`, the `secure` flag will not be sent in the cookie.

    `httponly`

    > A boolean. If it's `True`, the `HttpOnly` flag will be sent in the cookie, if it's `False`, the `HttpOnly` flag will not be sent in the cookie.

    `samesite`

    > A string representing the `SameSite` attribute of the cookie or `None`. If samesite is `None` no `SameSite` value will be sent in the cookie. Should only be `"strict"`, `"lax"`, or `"none"`.

    `comment`

    > A string representing the cookie `Comment` value, or `None`. If `comment` is `None`, no `Comment` value will be sent in the cookie.

    `expires`

    > A `datetime.timedelta` object representing an amount of time, `datetime.datetime` or `None`. A non-`None` value is used to generate the `Expires` value of the generated cookie. If `max_age` is not passed, but this value is not `None`, it will influence the `Max-Age` header. If this value is `None`, the `Expires` cookie value will be unset (unless `max_age` is set). If `max_age` is set, it will be used to generate the `expires` and this value is ignored.

    > If a `datetime.datetime` is provided it has to either be timezone aware or be based on UTC. `datetime.datetime` objects that are local time are not supported. Timezone aware `datetime.datetime` objects are converted to UTC.

    > This argument will be removed in future versions of WebOb (version 1.9).

    `overwrite`

    > If this key is `True`, before setting the cookie, unset any existing cookie.

  delete_cookie(name, path='/', domain=None)

    Delete a cookie from the client. Note that `path` and `domain` must match how the cookie was originally set.

    This sets the cookie to the empty string, and `max_age=0` so that it should expire immediately.

  unset_cookie(name, strict=True)

    Unset a cookie with the given name (remove it from the response).

  merge_cookies(resp)

    Merge the cookies that were set on this response with the given `resp` object (which can be any WSGI application).

    If the `resp` is a `webob.Response` object, then the other object will be modified in-place.

  property cache_control

    Get/set/modify the Cache-Control header (HTTP spec section 14.9).

  encode_content(encoding='gzip', lazy=False)

    Encode the content with the given encoding (only `gzip` and `identity` are supported).

  md5_etag(body=None, set_content_md5=False)

    Generate an etag for the response object using an MD5 hash of the body (the `body` parameter, or `self.body` if not given).

    Sets `self.etag`.

    If `set_content_md5` is `True`, sets `self.content_md5` as well.

  conditional_response_app(environ, start_response)

    Like the normal `__call__` interface, but checks conditional headers:

    > - `If-Modified-Since` (`304 Not Modified`; only on `GET`, `HEAD`)

    > - `If-None-Match` (`304 Not Modified`; only on `GET`, `HEAD`)

    > - `Range` (`406 Partial Content`; only on `GET`, `HEAD`)

  app_iter_range(start, stop)

    Return a new `app_iter` built from the response `app_iter`, that serves up only the given `start:stop` range.

class webob.response.ResponseBodyFile(response)
  property encoding

    The encoding of the file (inherited from response.charset)

  writelines(seq)

    Write a sequence of lines to the response.

  tell()

    Provide the current location where we are going to start writing.

class webob.response.AppIterRange(app_iter, start, stop)

  Wraps an `app_iter`, returning just a range of bytes.