circuits.web.tools module

Tools

This module implements tools used throughout circuits.web. These tools can also be used within Controllers and request handlers.

circuits.web.tools.expires(request, response, secs=0, force=False)

Tool for influencing cache mechanisms using the ‘Expires’ header.

‘secs’ must be either an int or a datetime.timedelta, and indicates the number of seconds between response.time and when the response should expire. The ‘Expires’ header will be set to (response.time + secs).

If ‘secs’ is zero, the ‘Expires’ header is set one year in the past, and the following “cache prevention” headers are also set: - ‘Pragma’: ‘no-cache’ - ‘Cache-Control’: ‘no-cache, must-revalidate’

If ‘force’ is False (the default), the following headers are checked: ‘Etag’, ‘Last-Modified’, ‘Age’, ‘Expires’. If any are already present, none of the above response headers are set.

circuits.web.tools.serve_file(request, response, path, type=None, disposition=None, name=None)

Set status, headers, and body in order to serve the given file.

The Content-Type header will be set to the type arg, if provided. If not provided, the Content-Type will be guessed by the file extension of the ‘path’ argument.

If disposition is not None, the Content-Disposition header will be set to “<disposition>; filename=<name>”. If name is None, it will be set to the basename of path. If disposition is None, no Content-Disposition header will be written.

circuits.web.tools.serve_download(request, response, path, name=None)

Serve ‘path’ as an application/x-download attachment.

circuits.web.tools.validate_etags(request, response, autotags=False)

Validate the current ETag against If-Match, If-None-Match headers.

If autotags is True, an ETag response-header value will be provided from an MD5 hash of the response body (unless some other code has already provided an ETag header). If False (the default), the ETag will not be automatic.

WARNING: the autotags feature is not designed for URL’s which allow methods other than GET. For example, if a POST to the same URL returns no content, the automatic ETag will be incorrect, breaking a fundamental use for entity tags in a possibly destructive fashion. Likewise, if you raise 304 Not Modified, the response body will be empty, the ETag hash will be incorrect, and your application will break. See http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.24

circuits.web.tools.validate_since(request, response)

Validate the current Last-Modified against If-Modified-Since headers.

If no code has set the Last-Modified response header, then no validation will be performed.

circuits.web.tools.check_auth(request, response, realm, users, encrypt=None)

Check Authentication

If an Authorization header contains credentials, return True, else False.

Parameters

  • realm (str) – The authentication realm.

  • users (dict or callable) – A dict of the form: {username: password} or a callable returning a dict.

  • encrypt (callable) – Callable used to encrypt the password returned from the user-agent. if None it defaults to a md5 encryption.

circuits.web.tools.basic_auth(request, response, realm, users, encrypt=None)

Perform Basic Authentication

If auth fails, returns an Unauthorized error with a basic authentication header.

Parameters

  • realm (str) – The authentication realm.

  • users (dict or callable) – A dict of the form: {username: password} or a callable returning a dict.

  • encrypt (callable) – Callable used to encrypt the password returned from the user-agent. if None it defaults to a md5 encryption.

circuits.web.tools.digest_auth(request, response, realm, users)

Perform Digest Authentication

If auth fails, raise 401 with a digest authentication header.

Parameters

  • realm (str) – The authentication realm.

  • users (dict or callable) – A dict of the form: {username: password} or a callable returning a dict.

circuits.web.tools.gzip(response, level=4, mime_types=('text/html', 'text/plain'))

Try to gzip the response body if Content-Type in mime_types.

response.headers[‘Content-Type’] must be set to one of the values in the mime_types arg before calling this function.

No compression is performed if any of the following hold:

  • The client sends no Accept-Encoding request header

  • No ‘gzip’ or ‘x-gzip’ is present in the Accept-Encoding header

  • No ‘gzip’ or ‘x-gzip’ with a qvalue > 0 is present

  • The ‘identity’ value is given with a qvalue > 0.

class circuits.web.tools.ReverseProxy(*args, **kwargs)

Bases: BaseComponent

initializes x; see x.__class__.__doc__ for signature

headers = ('X-Real-IP', 'X-Forwarded-For')
init(headers=None)

Web Component for identifying the original client IP when a reverse proxy is used

Parameters

headers – List of HTTP headers to read the original client IP