Documentation for pulsar 0.9.2. For development docs, go here.
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!'
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.
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: |
|
---|
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
.
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.
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
¶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
.
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(...)
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
pulsar.apps.wsgi.content.
Head
(media_path=None, title=None, meta=None, minified=False, asset_protocol=None, **params)[source]¶HtmlDocument
head
tag element.
Contains Html
attributes for the various part of an HTML
Head element. The head element is accessed via the
HtmlDocument.head
attribute.
title
¶Text in the title
tag.
meta
¶A container of Html
meta
tags.
To add new meta tags use the
add_meta()
method rather than accessing the meta
attribute directly.
embedded_js
¶Javascript embedded in the html page.
Rendered just after the embedded_css
container
scripts
¶A Scripts
container.
Rendered just after the embedded_js
container.
To add new javascript files simply use the append()
method on this attribute. You can add relative paths:
html.head.scripts.append('/media/js/scripts.js')
as well as absolute paths:
html.head.scripts.append(
'https://ajax.googleapis.com/ajax/libs/jquery/1.7.2/jquery.js')
get_meta
(name, meta_key=None)[source]¶Get the content
attribute of a meta tag name
.
For example:
head.get_meta('decription')
returns the content
attribute of the meta tag with attribute
name
equal to description
or None
.
If a different meta key needs to be matched, it can be specified via
the meta_key
parameter:
head.get_meta('og:title', meta_key='property')
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 . |
---|
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. |
---|
pulsar.apps.wsgi.content.
Links
(media_path, minified=False, asset_protocol=None)[source]¶A Media
container for link
tags.
The <link>
tag defines the relationship between a
HtmlDocument
and an external resource.
It is most used to link to style sheets.
append
(href=None, rel=None, type=None, media=None, condition=None, **kwargs)[source]¶Append a link to this container.
Parameters: |
|
---|