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 pulsar.apps.wsgi.structures.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

Set a cookie key into the cookies dictionary cookies.