Asynchronous Content

The pulsar.apps.wsgi.content introduces several utility classes for handling asynchronous content within a WSGI handler or middleware.

These classes can operate instead or in conjunction with a template engine, their main purpose is to do what a web framework does: to provide a set of tools working together to concatenate strings to return as a response to an HTTP client request.

A string can be html, json, plain text or any other valid HTTP content type.

The main class of this module is the String, which can be considered as the atomic component of an asynchronous web framework:

>>> from pulsar.apps.wsgi import String
>>> string = String('Hello')
>>> string.render()
'Hello'
>>> string.render()
...
RuntimeError: String already streamed

An String can only be rendered once, and it accepts asynchronous components:

>>> a = Future()
>>> string = String('Hello, ', a)
>>> value = string.render()
>>> value
MultiFuture (pending)
>>> value.done()
False

Once the future is done, we have the concatenated string:

>>> a.set_result('World!')
'World!'
>>> value.done()
True
>>> value.result()
'Hello, World!'

Design

The do_stream() method is responsible for the streaming of strings or asynchronous components. It can be overwritten by subclasses to customise the way an String streams its children.

On the other hand, the to_string() method is responsible for the concatenation of strings and, like do_stream(), it can be customised by subclasses.

Asynchronous String

class pulsar.apps.wsgi.content.String(*children, **params)[source]

An asynchronous string which can be used with pulsar WSGI servers.

append(child)[source]

Append child to the list of children.

Parameters:child – String, bytes or another String. If it is an String, this instance will be set as its parent. If child is None, this method does nothing.
append_to(parent)[source]

Append itself to parent. Return self.

before_render(callback)[source]

Add a callback to be executed before this content is rendered

The callback accept request and self as the only two arguments

children

A copy of all children of this String.

Children can be other String or string or bytes, depending on implementation. children are added and removed via the append() and remove() methods.

do_stream(request)[source]

Returns an iterable over strings or asynchronous components.

If asynchronous elements are included in the iterable, when called, they must result in strings. This method can be re-implemented by subclasses and should not be invoked directly. Use the stream() method instead.

extend(iterable)[source]

Extend this string with an iterable

has_default_content_type

True if this is as the default content type.

http_response(request, *stream)[source]

Return a WsgiResponse or a Future.

This method asynchronously wait for stream() and subsequently returns a WsgiResponse.

insert(index, child)[source]

Insert child into the list of children at index.

Parameters:
  • index – The index (positive integer) where to insert child.
  • child – String, bytes or another String. If it is an String, this instance will be set as its parent. If child is None, this method does nothing.
parent

The String element which contains this String.

prepend(child)[source]

Prepend child to the list of children.

This is a shortcut for the insert() method at index 0.

Parameters:child – String, bytes or another String. If it is an String, this instance will be set as its parent. If child is None, this method does nothing.
remove(child)[source]

Remove a child from the list of children.

remove_all()[source]

Remove all children.

render(request=None, callback=None)[source]

Render this string.

This method returns a string or a Future which results in a string. On the other hand, the callable method of a String always returns a Future.

stream(request)[source]

An iterable over strings or asynchronous elements.

This is the most important method of an String. It is called by http_response() or by the parent of this String. It returns an iterable (list, tuple or a generator) over strings (unicode/str for python 2, str only for python 3) or asynchronous elements which result in strings. This method can be called once only, otherwise a RuntimeError occurs.

This method should not be overwritten, instead one should use the do_stream() to customise behaviour.

to_string(streams)[source]

Called to transform the collection of streams into the content string. This method can be overwritten by derived classes.

Parameters:streams – a collection (list or dictionary) containing strings/bytes used to build the final string/bytes.
Returns:a string or bytes

Asynchronous Json

class pulsar.apps.wsgi.content.Json(*children, **params)[source]

An String which renders into a json string.

The String.content_type attribute is set to application/json.

as_list

If True, the content is always a list of objects. Default False.

parameters

Additional dictionary of parameters passed during initialisation.

Asynchronous Html

class pulsar.apps.wsgi.content.Html(tag, *children, **params)[source]

An String for html content.

The content_type attribute is set to text/html.

Parameters:
  • tag – Set the tag attribute. Must be given and can be None.
  • children – Optional children which will be added via the append() method.
  • params –

    Optional keyed-value parameters including:

    • cn class name or list of class names.
    • attr dictionary of attributes to add.
    • data dictionary of data to add (rendered as HTML data attribute).
    • type type of element, only supported for tags which accept the type attribute (for example the input tag).
addClass(cn)[source]

Add the specific class names to the class set and return self.

add_media(request)[source]

Invoked just before streaming this content.

It can be used to add media entries to the document.

TODO: more docs

attr(*args)[source]

Add the specific attribute to the attribute dictionary with key name and value value and return self.

css(mapping=None)[source]

Update the css dictionary if mapping is a dictionary, otherwise return the css value at mapping.

If mapping is not given, return the whole css dictionary if available.

data(*args)[source]

Add or retrieve data values for this Html.

flatatt(**attr)[source]

Return a string with attributes to add to the tag

get_form_value()[source]

Return the value of this Html element when it is contained in a Html form element.

For most element it gets the value attribute.

hasClass(cn)[source]

True if cn is a class of self.

hide()[source]

Same as jQuery hide method.

removeClass(cn)[source]

Remove classes

set_form_value(value)[source]

Set the value of this Html element when it is contained in a Html form element. For most element it sets the value attribute.

show()[source]

Same as jQuery show method.

tag

The tag for this HTML element.

One of div, a, table and so forth. It can be None.

Html Document

The HtmlDocument class is a python representation of an HTML5 document, the latest standard for HTML. It can be used to build a web site page in a pythonic fashion rather than using template languages:

>>> from pulsar.apps.wsgi import HtmlDocument

>>> doc = HtmlDocument(title='My great page title')
>>> doc.head.add_meta(name="description", content=...)
>>> doc.head.scripts.append('jquery')
...
>>> doc.body.append(...)

Document

class pulsar.apps.wsgi.content.HtmlDocument(title=None, media_path='/media/', charset=None, minified=False, loop=None, asset_protocol=None, **params)[source]

An Html component rendered as an HTML5 document.

An instance of this class can be obtained via the WsgiRequest.html_document attribute.

head

The Head part of this HtmlDocument

body

The body part of this HtmlDocument, an Html element

Media

class pulsar.apps.wsgi.content.Media(media_path, minified=False, asset_protocol=None)[source]

A container for both Links and Scripts.

media_path

The base url path to the local media files, for example /media/. Must include both slashes.

minified

Optional flag indicating if relative media files should be modified to end with .min.js or .min.css rather than .js or .css respectively.

Default: False

absolute_path(path, minify=True)[source]

Return a suitable absolute url for path.

If path is_relative() build a suitable url by prepending the media_path attribute.

Returns:A url path to insert in a HTML link or script.
is_relative(path)[source]

Check if path is a local relative path.

A path is local relative when it does not start with a slash / nor http:// nor https://.

Scripts

class pulsar.apps.wsgi.content.Scripts(*args, **kwargs)[source]

A Media container for script tags.

Supports javascript Asynchronous Module Definition

insert(index, child, **kwargs)[source]

add a new script to the container.

Parameters:child – a string representing an absolute path to the script or relative path (does not start with http or /), in which case the Media.media_path attribute is prepended.

Html Factory

pulsar.apps.wsgi.content.html_factory(tag, **defaults)[source]

Returns an Html factory function for tag and a given dictionary of defaults parameters. For example:

>>> input_factory = html_factory('input', type='text')
>>> html = input_factory(value='bla')