Utilities¶

HTTP Parsers¶

Pulsar ships with its own HTTP parser used by both server and the HTTP client. Headers are collected using the Headers data structure which exposes a list/dictionary-type interface.

Authentication¶

Handle basic and digest authentication on the server.

HttpAuthenticate¶

class pulsar.apps.wsgi.auth.HttpAuthenticate(type, realm=None, **options)[source]¶

Exception when basic or digest authentication is required.

This HttpException is raised with status code 401 and the extra WWW_Authenticate header if type is either basic or digest.

Authorization header parser¶

pulsar.apps.wsgi.auth.parse_authorization_header(value, charset='utf-8')[source]¶

Parse an HTTP basic/digest authorisation header.

Parameters:	value – the authorisation header to parse.
Returns:	either None if the header was invalid or not given, otherwise an `Auth` object.

Structures¶

class pulsar.apps.wsgi.structures.Accept[source]¶

An Accept object is a tuple subclass for tuples of (value, quality) tuples. It is automatically sorted by quality.

All Accept objects work similar to a list but provide extra functionality for working with the data. Containment checks are normalised to the rules of that header:

>>> a = CharsetAccept([('ISO-8859-1', 1), ('utf-8', 0.7)])
>>> a.best
'ISO-8859-1'
>>> 'iso-8859-1' in a
True
>>> 'UTF8' in a
True
>>> 'utf7' in a
False

To get the quality for an item you can use normal item lookup:

>>> print(a['utf-8'])
0.7
>>> a(['utf7'])
0

best¶: The best match as value.

best_match(matches, default=None)[source]¶

Returns the best match from a list of possible matches based on the quality of the client. If two items have the same quality, the one is returned that comes first.

Parameters:	matches – a list of matches to check for default – the value that is returned if none match

find(key)[source]¶

Get the position of an entry or return -1.

Parameters:	key – The key to be looked up.

index(key)[source]¶

Get the position of an entry or raise ValueError.

Parameters:	key – The key to be looked up.

Changed in version 0.5: This used to raise IndexError, which was inconsistent with the list API.

quality(key)[source]¶: Returns the quality of the key.

New in version 0.6: In previous versions you had to use the item-lookup syntax (eg: obj[key] instead of obj.quality(key))

to_header()[source]¶: Convert the header set into an HTTP header string.

values()[source]¶: Iterate over all values.

class pulsar.apps.wsgi.structures.CharsetAccept[source]¶: Like Accept but with normalisation for charsets.

class pulsar.apps.wsgi.structures.ContentAccept[source]¶

Like Accept but with special methods and behaviour for content types.

accept_html¶: True if this object accepts HTML.

accept_json¶: True if this object accepts JSON.

accept_xhtml¶: True if this object accepts XHTML.

class pulsar.apps.wsgi.structures.LanguageAccept[source]¶: Like Accept but with normalisation for languages.

Miscellaneous¶

The pulsar.apps.wsgi.utils module include several utilities used by various components in the wsgi application

pulsar.apps.wsgi.utils.cookie_date(epoch_seconds=None)[source]¶

Formats the time to ensure compatibility with Netscape’s cookie standard.

Accepts a floating point number expressed in seconds since the epoch in, a datetime object or a timetuple. All times in UTC. The parse_date() function can be used to parse such a date.

Outputs a string in the format Wdy, DD-Mon-YYYY HH:MM:SS GMT.

Parameters:	expires – If provided that date is used, otherwise the current.

pulsar.apps.wsgi.utils.handle_wsgi_error(environ, exc)[source]¶

The default error handler while serving a WSGI request.

Parameters:	environ – The WSGI environment. exc – the exception
Returns:	a `WsgiResponse`

pulsar.apps.wsgi.utils.parse_accept_header(value, cls=None)[source]¶

Parses an HTTP Accept-* header. This does not implement a complete valid algorithm but one that supports at least value and quality extraction.

Returns a new Accept object (basically a list of (value, quality) tuples sorted by the quality with some additional accessor methods).

The second parameter can be a subclass of Accept that is created with the parsed values and returned.

Parameters:	value – the accept header string to be parsed. cls – the wrapper class for the return value (can be `Accept` or a subclass thereof)
Returns:	an instance of cls.

pulsar.apps.wsgi.utils.parse_cache_control_header(value, on_update=None, cls=None)[source]¶

Parse a cache control header. The RFC differs between response and request cache control, this method does not. It’s your responsibility to not use the wrong control statements.

Parameters:	value – a cache control header to be parsed. on_update – an optional callable that is called every time a value on the `CacheControl` object is changed. cls – the class for the returned object. By default `RequestCacheControl` is used.
Returns:	a cls object.

pulsar.apps.wsgi.utils.render_error(request, exc)[source]¶: Default renderer for errors.

pulsar.apps.wsgi.utils.render_error_debug(request, exception, is_html)[source]¶: Render the exception traceback

pulsar.apps.wsgi.utils.set_cookie(cookies, key, value='', max_age=None, expires=None, path='/', domain=None, secure=False, httponly=False)[source]¶: Set a cookie key into the cookies dictionary cookies.