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.


Handle basic and digest authentication on the server.


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.


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' in a
>>> 'UTF8' in a
>>> 'utf7' in a

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

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

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.

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

Get the position of an entry or return -1.

Parameters:key – The key to be looked up.

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.


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


Convert the header set into an HTTP header string.


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.


True if this object accepts HTML.


True if this object accepts JSON.


True if this object accepts XHTML.

class pulsar.apps.wsgi.structures.LanguageAccept[source]

Like Accept but with normalisation for languages.


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


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.

  • environ – The WSGI environment.
  • exc – the exception

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.

  • value – the accept header string to be parsed.
  • cls – the wrapper class for the return value (can be Accept or a subclass thereof)

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.

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

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.