# `paste.request` – Utility functions for the WSGI environment

This module provides helper routines with work directly on a WSGI environment to solve common requirements.

> - get_cookies(environ)
> - parse_querystring(environ)
> - parse_formvars(environ, include_get_vars=True)
> - construct_url(environ, with_query_string=True, with_path_info=True,
>     script_name=None, path_info=None, querystring=None)
> - path_info_split(path_info)
> - path_info_pop(environ)
> - resolve_relative_url(url, environ)

## Module Contents

`paste.request.``get_cookies`(environ)

  Gets a cookie object (which is a dictionary-like object) from the request environment; caches this value in case get_cookies is called again for the same request.

`paste.request.``get_cookie_dict`(environ)

  Return a plain dictionary of cookies as found in the request.

  Unlike `get_cookies` this returns a dictionary, not a `SimpleCookie` object. For incoming cookies a dictionary fully represents the information. Like `get_cookies` this caches and checks the cache.

`paste.request.``parse_querystring`(environ)

  Parses a query string into a list like `[(name, value)]`. Caches this value in case parse_querystring is called again for the same request.

  You can pass the result to `dict()`, but be aware that keys that appear multiple times will be lost (only the last value will be preserved).

`paste.request.``parse_formvars`(environ, include_get_vars=True, encoding=None, errors=None)

  Parses the request, returning a MultiDict of form variables.

  If `include_get_vars` is true then GET (query string) variables will also be folded into the MultiDict.

  All values should be strings, except for file uploads which are left as `FieldStorage` instances.

  If the request was not a normal form request (e.g., a POST with an XML body) then `environ['wsgi.input']` won’t be read.

`paste.request.``construct_url`(environ, with_query_string=True, with_path_info=True, script_name=None, path_info=None, querystring=None)

  Reconstructs the URL from the WSGI environment.

  You may override SCRIPT_NAME, PATH_INFO, and QUERYSTRING with the keyword arguments.

`paste.request.``path_info_split`(path_info)

  Splits off the first segment of the path. Returns (first_part, rest_of_path). first_part can be None (if PATH_INFO is empty), ‘’ (if PATH_INFO is ‘/’), or a name without any /’s. rest_of_path can be ‘’ or a string starting with /.

`paste.request.``path_info_pop`(environ)

  ‘Pops’ off the next segment of PATH_INFO, pushing it onto SCRIPT_NAME, and returning that segment.

  For instance:

      >>> def call_it(script_name, path_info):
      ...     env = {'SCRIPT_NAME': script_name, 'PATH_INFO': path_info}
      ...     result = path_info_pop(env)
      ...     print('SCRIPT_NAME=%r; PATH_INFO=%r; returns=%r' % (
      ...         env['SCRIPT_NAME'], env['PATH_INFO'], result))
      >>> call_it('/foo', '/bar')
      SCRIPT_NAME='/foo/bar'; PATH_INFO=''; returns='bar'
      >>> call_it('/foo/bar', '')
      SCRIPT_NAME='/foo/bar'; PATH_INFO=''; returns=None
      >>> call_it('/foo/bar', '/')
      SCRIPT_NAME='/foo/bar/'; PATH_INFO=''; returns=''
      >>> call_it('', '/1/2/3')
      SCRIPT_NAME='/1'; PATH_INFO='/2/3'; returns='1'
      >>> call_it('', '//1/2')
      SCRIPT_NAME='//1'; PATH_INFO='/2'; returns='1'

`paste.request.``resolve_relative_url`(url, environ)

  Resolve the given relative URL as being relative to the location represented by the environment. This can be used for redirecting to a relative path. Note: if url is already absolute, this function will (intentionally) have no effect on it.

class `paste.request.``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).