webob – Request/Response objects — WebOb 1.4.1 documentation

### Navigation

- index
- modules |
- next |
- previous |
- WebOb 1.4.1 documentation »

# `webob` – Request/Response objects

## Request

class `webob.request.` `BaseRequest`(environ, charset=None, unicode_errors=None, decode_param_names=None, **kw)
  `GET`

    Return a MultiDict containing all the variables from the QUERY_STRING.

  `POST`

    Return a MultiDict containing all the variables from a form request. Returns an empty dict-like object for non-form requests.

    Form requests are typically POST requests, however PUT & PATCH requests with an appropriate Content-Type are also supported.

  `ResponseClass`

    alias of `Response`

  `accept`

    Gets and sets the `Accept` header (HTTP spec section 14.1).

  `accept_charset`

    Gets and sets the `Accept-Charset` header (HTTP spec section 14.2).

  `accept_encoding`

    Gets and sets the `Accept-Encoding` header (HTTP spec section 14.3).

  `accept_language`

    Gets and sets the `Accept-Language` header (HTTP spec section 14.4).

  `application_url`

    The URL including SCRIPT_NAME (no PATH_INFO or query string)

  `as_bytes`(skip_body=False)

    Return HTTP bytes representing this request. If skip_body is True, exclude the body. If skip_body is an integer larger than one, skip body only if its length is bigger than that number.

  `authorization`

    Gets and sets the `Authorization` header (HTTP spec section 14.8). Converts it using `parse_auth` and `serialize_auth`.

  classmethod `blank`(path, environ=None, base_url=None, headers=None, POST=None, **kw)

    Create a blank request environ (and Request wrapper) with the given path (path should be urlencoded), and any keys from environ.

    The path will become path_info, with any query string split off and used.

    All necessary keys will be added to the environ, but the values you pass in will take precedence. If you pass in base_url then wsgi.url_scheme, HTTP_HOST, and SCRIPT_NAME will be filled in from that value.

    Any extra keyword will be passed to `__init__`.

  `body`

    Return the content of the request body.

  `body_file`

    Input stream of the request (wsgi.input). Setting this property resets the content_length and seekable flag (unlike setting req.body_file_raw).

  `body_file_raw`

    Gets and sets the `wsgi.input` key in the environment.

  `body_file_seekable`

    Get the body of the request (wsgi.input) as a seekable file-like object. Middleware and routing applications should use this attribute over .body_file.

    If you access this value, CONTENT_LENGTH will also be updated.

  `cache_control`

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

  `call_application`(application, catch_exc_info=False)

    Call the given WSGI application, returning `(status_string, headerlist, app_iter)`

    Be sure to call `app_iter.close()` if it’s there.

    If catch_exc_info is true, then returns `(status_string, headerlist, app_iter, exc_info)`, where the fourth item may be None, but won’t be if there was an exception. If you don’t do this and there was an exception, the exception will be raised directly.

  `client_addr`

    The effective client IP address as a string. If the `HTTP_X_FORWARDED_FOR` header exists in the WSGI environ, this attribute returns the client IP address present in that header (e.g. if the header value is `192.168.1.1, 192.168.1.2`, the value will be `192.168.1.1`). If no `HTTP_X_FORWARDED_FOR` header is present in the environ at all, this attribute will return the value of the `REMOTE_ADDR` header. If the `REMOTE_ADDR` header is unset, this attribute will return the value `None`.

    Warning

    It is possible for user agents to put someone else’s IP or just any string in `HTTP_X_FORWARDED_FOR` as it is a normal HTTP header. Forward proxies can also provide incorrect values (private IP addresses etc). You cannot “blindly” trust the result of this method to provide you with valid data unless you’re certain that `HTTP_X_FORWARDED_FOR` has the correct values. The WSGI server must be behind a trusted proxy for this to be true.

  `content_length`

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

  `content_type`

    Return the content type, but leaving off any parameters (like charset, but also things like the type in `application/atom+xml; type=entry`)

    If you set this property, you can include parameters, or if you don’t include any parameters in the value then existing parameters will be preserved.

  `cookies`

    Return a dictionary of cookies as found in the request.

  `copy`()

    Copy the request and environment object.

    This only does a shallow copy, except of wsgi.input

  `copy_body`()

    Copies the body, in cases where it might be shared with another request object and that is not desired.

    This copies the body in-place, either into a BytesIO object or a temporary file.

  `copy_get`()

    Copies the request and environment object, but turning this request into a GET along the way. If this was a POST request (or any other verb) then it becomes GET, and the request body is thrown away.

  `date`

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

  `domain`

    Returns the domain portion of the host value. Equivalent to:

        domain = request.host
        if ':' in domain:
            domain = domain.split(':', 1)[0]

    This will be equivalent to the domain portion of the `HTTP_HOST` value in the environment if it exists, or the `SERVER_NAME` value in the environment if it doesn’t. For example, if the environment contains an `HTTP_HOST` value of `foo.example.com:8000`, `request.domain` will return `foo.example.com`.

    Note that this value cannot be set on the request. To set the host value use `webob.request.Request.host()` instead.

  classmethod `from_bytes`(b)

    Create a request from HTTP bytes data. If the bytes contain extra data after the request, raise a ValueError.

  classmethod `from_file`(fp)

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

    It will read up to the end of the request, not the end of the file (unless the request is a POST or PUT and has no Content-Length, in that case, the entire file is read).

    This reads the request as represented by `str(req)`; it may not read every valid HTTP request properly.

  `get_response`(application=None, catch_exc_info=False)

    Like `.call_application(application)`, except returns a response object with `.status`, `.headers`, and `.body` attributes.

    This will use `self.ResponseClass` to figure out the class of the response object to return.

    If `application` is not given, this will send the request to `self.make_default_send_app()`

  `headers`

    All the request headers as a case-insensitive dictionary-like object.

  `host`

    Host name provided in HTTP_HOST, with fall-back to SERVER_NAME

  `host_port`

    The effective server port number as a string. If the `HTTP_HOST` header exists in the WSGI environ, this attribute returns the port number present in that header. If the `HTTP_HOST` header exists but contains no explicit port number: if the WSGI url scheme is “https” , this attribute returns “443”, if the WSGI url scheme is “http”, this attribute returns “80” . If no `HTTP_HOST` header is present in the environ at all, this attribute will return the value of the `SERVER_PORT` header (which is guaranteed to be present).

  `host_url`

    The URL through the host (no path)

  `http_version`

    Gets and sets the `SERVER_PROTOCOL` key in the environment.

  `if_match`

    Gets and sets the `If-Match` header (HTTP spec section 14.24). Converts it as a Etag.

  `if_modified_since`

    Gets and sets the `If-Modified-Since` header (HTTP spec section 14.25). Converts it using HTTP date.

  `if_none_match`

    Gets and sets the `If-None-Match` header (HTTP spec section 14.26). Converts it as a Etag.

  `if_range`

    Gets and sets the `If-Range` header (HTTP spec section 14.27). Converts it using IfRange object.

  `if_unmodified_since`

    Gets and sets the `If-Unmodified-Since` header (HTTP spec section 14.28). Converts it using HTTP date.

  `is_body_readable`

    webob.is_body_readable is a flag that tells us that we can read the input stream even though CONTENT_LENGTH is missing. This allows FakeCGIBody to work and can be used by servers to support chunked encoding in requests. For background see https://bitbucket.org/ianb/webob/issue/6

  `is_body_seekable`

    Gets and sets the `webob.is_body_seekable` key in the environment.

  `is_xhr`

    Is X-Requested-With header present and equal to `XMLHttpRequest`?

    Note: this isn’t set by every XMLHttpRequest request, it is only set if you are using a Javascript library that sets it (or you set the header yourself manually). Currently Prototype and jQuery are known to set this header.

  `json`

    Access the body of the request as JSON

  `json_body`

    Access the body of the request as JSON

  `make_body_seekable`()

    This forces `environ['wsgi.input']` to be seekable. That means that, the content is copied into a BytesIO or temporary file and flagged as seekable, so that it will not be unnecessarily copied again.

    After calling this method the .body_file is always seeked to the start of file and .content_length is not None.

    The choice to copy to BytesIO is made from `self.request_body_tempfile_limit`

  `make_tempfile`()

    Create a tempfile to store big request body. This API is not stable yet. A ‘size’ argument might be added.

  `max_forwards`

    Gets and sets the `Max-Forwards` header (HTTP spec section 14.31). Converts it using int.

  `method`

    Gets and sets the `REQUEST_METHOD` key in the environment.

  `params`

    A dictionary-like object containing both the parameters from the query string and request body.

  `path`

    The path of the request, without host or query string

  `path_info`

    Gets and sets the `PATH_INFO` key in the environment.

  `path_info_peek`()

    Returns the next segment on PATH_INFO, or None if there is no next segment. Doesn’t modify the environment.

  `path_info_pop`(pattern=None)

    ‘Pops’ off the next segment of PATH_INFO, pushing it onto SCRIPT_NAME, and returning the popped segment. Returns None if there is nothing left on PATH_INFO.

    Does not return `''` when there’s an empty segment (like `/path//path`); these segments are just ignored.

    Optional `pattern` argument is a regexp to match the return value before returning. If there is no match, no changes are made to the request and None is returned.

  `path_qs`

    The path of the request, without host but with query string

  `path_url`

    The URL including SCRIPT_NAME and PATH_INFO, but not QUERY_STRING

  `pragma`

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

  `query_string`

    Gets and sets the `QUERY_STRING` key in the environment.

  `range`

    Gets and sets the `Range` header (HTTP spec section 14.35). Converts it using Range object.

  `referer`

    Gets and sets the `Referer` header (HTTP spec section 14.36).

  `referrer`

    Gets and sets the `Referer` header (HTTP spec section 14.36).

  `relative_url`(other_url, to_application=False)

    Resolve other_url relative to the request URL.

    If `to_application` is True, then resolve it relative to the URL with only SCRIPT_NAME

  `remote_addr`

    Gets and sets the `REMOTE_ADDR` key in the environment.

  `remote_user`

    Gets and sets the `REMOTE_USER` key in the environment.

  `remove_conditional_headers`(remove_encoding=True, remove_range=True, remove_match=True, remove_modified=True)

    Remove headers that make the request conditional.

    These headers can cause the response to be 304 Not Modified, which in some cases you may not want to be possible.

    This does not remove headers like If-Match, which are used for conflict detection.

  `scheme`

    Gets and sets the `wsgi.url_scheme` key in the environment.

  `script_name`

    Gets and sets the `SCRIPT_NAME` key in the environment.

  `send`(application=None, catch_exc_info=False)

    Like `.call_application(application)`, except returns a response object with `.status`, `.headers`, and `.body` attributes.

    This will use `self.ResponseClass` to figure out the class of the response object to return.

    If `application` is not given, this will send the request to `self.make_default_send_app()`

  `server_name`

    Gets and sets the `SERVER_NAME` key in the environment.

  `server_port`

    Gets and sets the `SERVER_PORT` key in the environment. Converts it using int.

  `str_GET`

    <Deprecated attribute None>

  `str_POST`

    <Deprecated attribute None>

  `str_cookies`

    <Deprecated attribute None>

  `str_params`

    <Deprecated attribute None>

  `text`

    Get/set the text value of the body

  `upath_info`

    Gets and sets the `PATH_INFO` key in the environment.

  `url`

    The full request URL, including QUERY_STRING

  `url_encoding`

    Gets and sets the `webob.url_encoding` key in the environment.

  `urlargs`

    Return any positional variables matched in the URL.

    Takes values from `environ['wsgiorg.routing_args']`. Systems like `routes` set this value.

  `urlvars`

    Return any named variables matched in the URL.

    Takes values from `environ['wsgiorg.routing_args']`. Systems like `routes` set this value.

  `uscript_name`

    Gets and sets the `SCRIPT_NAME` key in the environment.

  `user_agent`

    Gets and sets the `User-Agent` header (HTTP spec section 14.43).

## Response

class `webob.response.` `Response`(body=None, status=None, headerlist=None, app_iter=None, content_type=None, conditional_response=None, **kw)

  Represents a WSGI response

  `accept_ranges`

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

  `age`

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

  `allow`

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

  `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)

  `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.

  `body`

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

  `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.

  `cache_control`

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

  `charset`

    Get/set the charset (in the Content-Type)

  `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)
  `content_disposition`

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

  `content_encoding`

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

  `content_language`

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

  `content_length`

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

  `content_location`

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

  `content_md5`

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

  `content_range`

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

  `content_type`

    Get/set the Content-Type header (or None), without the charset or any parameters.

    If you include parameters (or `;` at all) when setting the content_type, any existing parameters will be deleted; otherwise they will be preserved.

  `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 would not be applied otherwise)

  `copy`()

    Makes a copy of the response

  `date`

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

  `delete_cookie`(key, 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.

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

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

  `etag`

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

  `expires`

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

  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`

  `headerlist`

    The list of response headers

  `headers`

    The headers in a dictionary-like object

  `json`

    Access the body of the response as JSON

  `json_body`

    Access the body of the response as JSON

  `last_modified`

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

  `location`

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

  `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

  `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.

  `pragma`

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

  `retry_after`

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

  `server`

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

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

    Set (add) a cookie for the response.

    Arguments are:

    `key`

    > 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 or `None`. If this value is an integer, it is used as the `Max-Age` of the generated cookie. If `expires` is not passed and this value is an integer, 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 also sent).

    `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.

    `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 or the value `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 (`Max-Age` will be ‘expires_value - datetime.utcnow()’). If this value is `None`, the `Expires` cookie value will be unset (unless `max_age` is also passed).

    `overwrite`

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

  `status`

    The status string

  `status_code`

    The status as an integer

  `status_int`

    The status as an integer

  `text`

    Get/set the text value of the body (using the charset of the Content-Type)

  `ubody`

    Deprecated alias for .text

  `unicode_body`

    Deprecated alias for .text

  `unset_cookie`(key, strict=True)

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

  `vary`

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

  `www_authenticate`

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

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

  Wraps an app_iter, returning just a range of bytes

## Headers

### Accept-*

Parses a variety of `Accept-*` headers.

These headers generally take the form of:

    value1; q=0.5, value2; q=0

Where the `q` parameter is optional. In theory other parameters exists, but this ignores them.

class `webob.acceptparse.` `Accept`(header_value)

  Represents a generic `Accept-*` style header.

  This object should not be modified. To add items you can use `accept_obj + 'accept_thing'` to get a new object

  `best_match`(offers, default_match=None)

    Returns the best match in the sequence of offered types.

    The sequence can be a simple sequence, or you can have `(match, server_quality)` items in the sequence. If you have these tuples then the client quality is multiplied by the server_quality to get a total. If two matches have equal weight, then the one that shows up first in the offers list will be returned.

    But among matches with the same quality the match to a more specific requested type will be chosen. For example a match to text/* trumps /.

    default_match (default None) is returned if there is no intersection.

  `first_match`(offers)

    DEPRECATED Returns the first allowed offered type. Ignores quality. Returns the first offered type if nothing else matches; or if you include None at the end of the match list then that will be returned.

  static `parse`(value)

    Parse `Accept-*` style header.

    Return iterator of `(value, quality)` pairs. `quality` defaults to 1.

  `quality`(offer, modifier=1)

    Return the quality of the given offer. Returns None if there is no match (not 0).

class `webob.acceptparse.` `MIMEAccept`(header_value)

  Represents the `Accept` header, which is a list of mimetypes.

  This class knows about mime wildcards, like `image/*`

  `accept_html`()

    Returns true if any HTML-like type is accepted

  `accepts_html`

    Returns true if any HTML-like type is accepted

### Cache-Control

class `webob.cachecontrol.` `CacheControl`(properties, type)

  Represents the Cache-Control header.

  By giving a type of `'request'` or `'response'` you can control what attributes are allowed (some Cache-Control values only apply to requests or responses).

  `copy`()

    Returns a copy of this object.

  classmethod `parse`(header, updates_to=None, type=None)

    Parse the header, returning a CacheControl object.

    The object is bound to the request or response object `updates_to`, if that is given.

  `update_dict`

    alias of `UpdateDict`

### Range and related headers

class `webob.byterange.` `Range`(start, end)

  Represents the Range header.

  `content_range`(length)

    Works like range_for_length; returns None or a ContentRange object

    You can use it like:

        response.content_range = req.range.content_range(response.content_length)

    Though it’s still up to you to actually serve that content range!

  classmethod `parse`(header)

    Parse the header; may return None if header is invalid

  `range_for_length`(length)

    If there is only one range, and if it is satisfiable by the given length, then return a (start, end) non-inclusive range of bytes to serve. Otherwise return None

class `webob.byterange.` `ContentRange`(start, stop, length)

  Represents the Content-Range header

  This header is `start-stop/length`, where start-stop and length can be `*` (represented as None in the attributes).

  classmethod `parse`(value)

    Parse the header. May return None if it cannot parse.

class `webob.etag.` `IfRange`(etag)
  classmethod `parse`(value)

    Parse this from a header value.

### ETag

class `webob.etag.` `ETagMatcher`(etags)
  classmethod `parse`(value, strong=True)

    Parse this from a header value

### Cookies

class `webob.cookies.` `CookieProfile`(cookie_name, secure=False, max_age=None, httponly=None, path='/', domains=None, serializer=None)

  A helper class that helps bring some sanity to the insanity that is cookie handling.

  The helper is capable of generating multiple cookies if necessary to support subdomains and parent domains.

  `cookie_name`
    The name of the cookie used for sessioning. Default: `'session'`.
  `max_age`
    The maximum age of the cookie used for sessioning (in seconds). Default: `None` (browser scope).
  `secure`
    The ‘secure’ flag of the session cookie. Default: `False`.
  `httponly`
    Hide the cookie from Javascript by setting the ‘HttpOnly’ flag of the session cookie. Default: `False`.
  `path`
    The path used for the session cookie. Default: `'/'`.
  `domains`
    The domain(s) used for the session cookie. Default: `None` (no domain). Can be passed an iterable containing multiple domains, this will set multiple cookies one for each domain.
  `serializer`
    An object with two methods: `loads` and `dumps`. The `loads` method should accept a bytestring and return a Python object. The `dumps` method should accept a Python object and return bytes. A `ValueError` should be raised for malformed inputs. Default: `None`, which will use a derivation of `json.dumps()` and `json.loads()`.
  `bind`(request)

    Bind a request to a copy of this instance and return it

  `get_headers`(value, domains=<object object at 0xb576cbd8>, max_age=<object object at 0xb576cbd8>, path=<object object at 0xb576cbd8>, secure=<object object at 0xb576cbd8>, httponly=<object object at 0xb576cbd8>)

    Retrieve raw headers for setting cookies.

    Returns a list of headers that should be set for the cookies to be correctly tracked.

  `get_value`()

    Looks for a cookie by name in the currently bound request, and returns its value. If the cookie profile is not bound to a request, this method will raise a `ValueError`.

    Looks for the cookie in the cookies jar, and if it can find it it will attempt to deserialize it. Returns `None` if there is no cookie or if the value in the cookie cannot be successfully deserialized.

  `set_cookies`(response, value, domains=<object object at 0xb576cbd8>, max_age=<object object at 0xb576cbd8>, path=<object object at 0xb576cbd8>, secure=<object object at 0xb576cbd8>, httponly=<object object at 0xb576cbd8>)

    Set the cookies on a response.

class `webob.cookies.` `SignedCookieProfile`(secret, salt, cookie_name, secure=False, max_age=None, httponly=False, path='/', domains=None, hashalg='sha512', serializer=None)

  A helper for generating cookies that are signed to prevent tampering.

  By default this will create a single cookie, given a value it will serialize it, then use HMAC to cryptographically sign the data. Finally the result is base64-encoded for transport. This way a remote user can not tamper with the value without uncovering the secret/salt used.

  `secret`
    A string which is used to sign the cookie. The secret should be at least as long as the block size of the selected hash algorithm. For `sha512` this would mean a 128 bit (64 character) secret.
  `salt`
    A namespace to avoid collisions between different uses of a shared secret.
  `hashalg`
    The HMAC digest algorithm to use for signing. The algorithm must be supported by the `hashlib` library. Default: `'sha512'`.
  `cookie_name`
    The name of the cookie used for sessioning. Default: `'session'`.
  `max_age`
    The maximum age of the cookie used for sessioning (in seconds). Default: `None` (browser scope).
  `secure`
    The ‘secure’ flag of the session cookie. Default: `False`.
  `httponly`
    Hide the cookie from Javascript by setting the ‘HttpOnly’ flag of the session cookie. Default: `False`.
  `path`
    The path used for the session cookie. Default: `'/'`.
  `domains`
    The domain(s) used for the session cookie. Default: `None` (no domain). Can be passed an iterable containing multiple domains, this will set multiple cookies one for each domain.
  `serializer`
    An object with two methods: loads` and `dumps`. The `loads` method should accept bytes and return a Python object. The `dumps` method should accept a Python object and return bytes. A `ValueError` should be raised for malformed inputs. Default: `None`, which will use a derivation of :func:`json.dumps` and ``json.loads`.
  `bind`(request)

    Bind a request to a copy of this instance and return it

class `webob.cookies.` `SignedSerializer`(secret, salt, hashalg='sha512', serializer=None)

  A helper to cryptographically sign arbitrary content using HMAC.

  The serializer accepts arbitrary functions for performing the actual serialization and deserialization.

  `secret`
    A string which is used to sign the cookie. The secret should be at least as long as the block size of the selected hash algorithm. For `sha512` this would mean a 128 bit (64 character) secret.
  `salt`
    A namespace to avoid collisions between different uses of a shared secret.
  `hashalg`
    The HMAC digest algorithm to use for signing. The algorithm must be supported by the `hashlib` library. Default: `'sha512'`.
  `serializer`
    An object with two methods: loads` and `dumps`. The `loads` method should accept bytes and return a Python object. The `dumps` method should accept a Python object and return bytes. A `ValueError` should be raised for malformed inputs. Default: `None`, which will use a derivation of :func:`json.dumps` and ``json.loads`.
  `dumps`(appstruct)

    Given an `appstruct`, serialize and sign the data.

    Returns a bytestring.

  `loads`(bstruct)

    Given a `bstruct` (a bytestring), verify the signature and then deserialize and return the deserialized value.

    A `ValueError` will be raised if the signature fails to validate.

class `webob.cookies.` `JSONSerializer`

  A serializer which uses json.dumps` and `json.loads`

`webob.cookies.` `make_cookie`(name, value, max_age=None, path='/', domain=None, secure=False, httponly=False, comment=None)

  Generate a cookie value. If `value` is None, generate a cookie value with an expiration date in the past

## Misc Functions and Internals

`webob.` `html_escape`(s)

  HTML-escape a string or object

  This converts any non-string objects passed into it to strings (actually, using `unicode()`). All values returned are non-unicode strings (using `&#num;` entities for all non-ASCII characters).

  None is treated specially, and returns the empty string.

class `webob.headers.` `ResponseHeaders`(*args, **kw)

  Dictionary view on the response headerlist. Keys are normalized for case and whitespace.

class `webob.headers.` `EnvironHeaders`(environ)

  An object that represents the headers as present in a WSGI environment.

  This object is a wrapper (with no internal state) for a WSGI request object, representing the CGI-style HTTP_* keys as a dictionary. Because a CGI environment can only hold one value for each key, this dictionary is single-valued (unlike outgoing headers).

Gives a multi-value dictionary object (MultiDict) plus several wrappers

class `webob.multidict.` `MultiDict`(*args, **kw)

  An ordered dictionary that can have multiple values for each key. Adds the methods getall, getone, mixed and extend and add to the normal dictionary interface.

  `add`(key, value)

    Add the key and value, not overwriting any previous value.

  `dict_of_lists`()

    Returns a dictionary where each key is associated with a list of values.

  classmethod `from_fieldstorage`(fs)

    Create a dict from a cgi.FieldStorage instance

  `getall`(key)

    Return a list of all values matching the key (may be an empty list)

  `getone`(key)

    Get one value matching the key, raising a KeyError if multiple values were found.

  `mixed`()

    Returns a dictionary where the values are either single values, or a list of values when a key/value appears more than once in this dictionary. This is similar to the kind of dictionary often used to represent the variables in a web request.

  classmethod `view_list`(lst)

    Create a dict that is a view on the given list

class `webob.multidict.` `NestedMultiDict`(*dicts)

  Wraps several MultiDict objects, treating it as one large MultiDict

class `webob.multidict.` `NoVars`(reason=None)

  Represents no variables; used when no variables are applicable.

  This is read-only

class `webob.cachecontrol.` `UpdateDict`

  Dict that has a callback on all updates

### Navigation

- index
- modules |
- next |
- previous |
- WebOb 1.4.1 documentation »