Documentation for pulsar 0.9.2. For development docs, go here.

Asynchronous Content

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

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 AsyncString, which can be considered as the atomic component of an asynchronous web framework:

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

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

>>> a = Future()
>>> string = AsyncString('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 AsyncString 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.AsyncString(*children, **params)[source]

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

parent

The AsyncString element which contains this AsyncString.

children

A copy of all children of this AsyncString.

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

has_default_content_type

True if this is as the default content type.

append(child)[source]

Append child to the list of children.

Parameters:child – String, bytes or another AsyncString. If it is an AsyncString, this instance will be set as its parent. If child is None, this method does nothing.
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 AsyncString. If it is an AsyncString, this instance will be set as its parent. If child is None, this method does nothing.
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 AsyncString. If it is an AsyncString, 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.

append_to(parent)[source]

Append itself to parent. Return self.

stream(request)[source]

An iterable over strings or asynchronous elements.

This is the most important method of an AsyncString. It is called by http_response() or by the parent of this AsyncString. 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.

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.

http_response(request, *stream)[source]

Return a WsgiResponse or a Future.

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

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

render(request=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 AsyncString always returns a Future.

Asynchronous Json

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

An AsyncString which renders into a json string.

The AsyncString.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 AsyncString 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).
tag

The tag for this HTML element.

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

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.

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.

attr(*args)[source]

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

data(*args)[source]

Add or retrieve data values for this Html.

addClass(cn)[source]

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

hasClass(cn)[source]

True if cn is a class of self.

removeClass(cn)[source]

Remove classes

flatatt(**attr)[source]

Return a string with atributes to add to the tag

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.

hide()[source]

Same as jQuery hide method.

show()[source]

Same as jQuery show method.

add_media(request)[source]

Invoked just before streaming this content.

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

TODO: more docs

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

Default: False

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://.

absolute_path(path, minify=True)[source]

Return a suitable absolute url for path.

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

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

Add a list (iterable) of media to this container

Scripts

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

A Media container for script tags.

Supports javascript Asynchronous Module Definition

append(src=None, type=None, **kwargs)[source]

add a new script to the container.

Parameters:src – 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.
require_script()[source]

Can be used for requirejs

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


Table Of Contents

Previous topic

Response Middleware

Next topic

Utilities

This Page