API Documentation¶

View rendering framework¶

class aurora.views.Engine¶

Provide syntax specific template based view rendering support.

A Views engine is any callable object that takes a string containing the absolute filesystem path of the View template as first positional argument and any named argument used as context and return a string containing the rendered content.

class aurora.views.Views¶

Provide generic template based view rendering support.

The template file extension is very important, is used to map template file to the engine capable of handling correctly the template syntax.

Template composition support is provided (the render() method is mapped into the default context). This allow composing templates with different syntax as long as the Template Engine of the composed view support using a context element as callable.

The only template engine available by default is one based on suba and created on the fly the first time the template engine cache is hit (either because a new template engine is added using add_engine() or because render() is called). A copy of the suba module is shipped with the Aurora library (the aurora.webcomponents._suba Python source module.) because it can’t be added as a library dependency because this library is not on PYPI Python package index.

add_default(key: str, value)¶

Add a default context item.

Parameters:	key – Item key string. value – Item value

add_engine(engine: aurora.views.Engine, *extensions)¶

Register an Engine-like object for rendering files.

Parameters:	engine – An `Engine`-like object. extensions – List of template file extensions.

add_path(path: str)¶

Add an absolute path as template file source.

Parameters:	path – The absolute path (string) to a folder that store templates files.

render(template_name: str, **context) → str¶

Render a template into content with context.

Parameters:	template_name – The relative template name string without the last extension. context – The context mapping.
Returns:	The rendered output string.

Web application framework¶

class aurora.webapp.Application¶

Web application.

This class built on top of the infrastructure add a default service invoked for not mapped Web requests.

class aurora.webapp.foundation.Request(environ, charset=None, unicode_errors=None, decode_param_names=None, **kw)¶

Web request.

The Web request provide access to the information sent by the client browser to the Web application.

response_factory¶: Factory used to produce a Web response object.

class aurora.webapp.foundation.Response(body=None, status=None, headerlist=None, app_iter=None, content_type=None, conditional_response=None, charset=<object object>, **kw)¶

Web response.

The Web response is created by the Web request handler and is used to store the information that is going to be sent to the client browser in return.

class aurora.webapp.foundation.Handler¶

Web request handler.

A Web request handler is any callable object that accept as first positional argument a Web request object and return a Web response object.

The Web request handler must create the Web response object by calling the factory referenced by the response_factory attribute of the Web request object. This way the Web handler can be called using different request-response pairs (for testing purposes for example).

Example Hello World! Web request handler:

def say_hello(request):
    return request.response_factory(text='Hello World!')

aurora.webapp.foundation.wsgi(handler)¶

Wrap handler with a WSGI application interface.

Parameters:	handler – A `Web request handler`.
Returns:	A WSGI application.

class aurora.webapp.mapping.Rule¶

Map a Web request path and its characteristics back and forth.

A rule implement the logic needed to perform the mapping between a specific Web request path and its associated characteristics. This mapping can be addressed direct or reverse.

This class is not meant to be inherited it is here just for interface documentation purposes.

assemble(**characteristics) → str¶

Map characteristics into its associated Web request path.

If the characteristics mapping can be mapped by this rule then a string containing the Web request path unique respect to the Rule is returned otherwise return False.

Parameters:	characteristics – The characteristics mapping.
Returns:	The Web request path or False.

match(path: str) → collections.abc.Mapping¶

Map the Web request path into its associated characteristics.

If the Web request path can be mapped by this rule then a mapping of the characteristics that make this Web request path unique respect to the Rule is returned otherwise return False.

Parameters:	path – The Web request path.
Returns:	The characteristic mapping or False

class aurora.webapp.mapping.Route(pattern: str, **defaults)¶

A Web request path mapping Rule that use pattern matching.

The pattern matching algorithm used is plain regex. The expressions allowed in the pattern in order to be reassembled into a valid Web request path are described by the dialect attribute of this class. Any deviation may result in an incorrectly assembled Web request path.

At initialization the pattern is passed as first positional argument, other named arguments are used as default values for any optional pattern group.

class aurora.webapp.mapping.DefaultRule¶

A Web request path mapping Rule that map all Web requests.

This is a simple Web request path mapping Rule very useful for mapping the Web request handler for not mapped Web requests. It match all Web request paths and return always False on assemble() method calls.

class aurora.webapp.mapping.Mapper¶

Map a Web request path and its characteristics using multiple rules.

The Mapper implement the same interface provided by Rule and add the possibility of tagging rules using an additional mapping of elements known as metadata. Additionally metadata can be used to override Web request path characteristics with default values.

Every time the match() or assemble() methods are called all added rules are evaluated in the reverse order of addition. This implementation detail imply that in order to function correctly generic rules must be added first and specific ones latter.

add_rule(rule: aurora.webapp.mapping.Rule, **metadata)¶

Add a Rule and its associated metadata to the mapping.

Parameters:	rule – A mapping `Rule`. metadata – The `Rule` associated metadata.

assemble(**characteristics) → str¶

Map characteristics into its associated Web request path.

A Rule is mapped only in the case that all Rule associated metadata are present in the characteristics mapping and have the same value.

Parameters:	characteristics – The characteristics mapping.
Returns:	The Web request path or False.

match(path: str) → collections.abc.Mapping¶

Map the Web request path into its associated characteristics.

Once a Rule is mapped successfully its associated metadata is used to update the Web request path characteristics mapping.

Parameters:	path – The Web request path.
Returns:	The characteristic mapping or False

class aurora.webapp.infrastructure.Application¶

Web application.

This class provide the basic infrastructure needed to build a Web application based on multiple handlers and with a extensible Web request handling mechanism.

Web application objects implement the Web request handler protocol. The Web request handling strategy has been built on top of the Web request path mapping components. The characteristic used as Web request handler is _handler. All characteristics except _handler update the Web request GET mapping.

The Web request handling strategy can be extended by implementing the pre_dispatch() and post_dispatch() services. In order to provide plug-able extension points this services can be replaced with event dispatchers.

get_request() → aurora.webapp.foundation.Request¶

The Web request been handled by the application.

The Web application can handle one Web request at a time. This service return the Web request currently been handled. It is intended to be used by components that provide a request centered service (like HTTP session support).

mapper¶: Web request path mapper.

not_found(request: aurora.webapp.foundation.Request) → aurora.webapp.foundation.Response¶

Service invoked for not mapped Web requests.

This service is the first Rule registered with the application’s Web request path mapper using the DefaultRule Rule. It shows a basic not found message on the client browser.

post_dispatch(response: aurora.webapp.foundation.Response)¶

Web request handling strategy extension.

This service is invoked by the Web request handling strategy after the Web request handler is invoked. :param response: The Web response.

pre_dispatch(request: aurora.webapp.foundation.Request)¶

Web request handling strategy extension.

This service is invoked by the Web request handling strategy after the Web request path is mapped into its characteristics and before the Web request handler is invoked. :param request: The Web request.

url_for(**characteristics) → str¶

Create a fully usable url.

This method fill the void left by the lack of integration between the Web request path mapping components and the Web application framework foundation. The url is produced by concatenating the Web request application url and the relative url produced by the associated rule assemble() method call. If the last element is a absolute url then no concatenation is done.

Parameters:	characteristics – The Web request path characteristics.
Returns:	A fully usable url.

class aurora.webapp.testing.TestHandler(methodName='runTest')¶

Tests for Web request handlers.

This test case provide common tests to all Web request handlers. Is is not a framework test case but a base class for Web request handler tests.

You need to override the handler_factory class attribute used to set the Web request handler factory used at test suite setup.

handler_factory¶: alias of aurora.webapp.foundation.Handler

request_factory¶: alias of aurora.webapp.foundation.Request

setUp()¶: Hook method for setting up the test fixture before exercising it.

test_response_type()¶

Response object type test.

The Web response object returned by the call to the Web request handler should be an instance of the same type of the objects returned by calls to the Web request response_factory attribute.

class aurora.webapp.testing.TestRule(methodName='runTest')¶

Tests for Web request path mapping rules.

This test case provide common tests to all Web request path mapping rules. Is is not a framework test case but a base class for Web request path mapping rule tests.

You need to override the rule_factory class attribute used to set the Web request path mapping rule factory used at test suite setup.

The set of test is permissive, they test if the Web request path mapping rule object implement the Web request path mapping rule protocol but don’t fail if the Web request path mapping rule object provide additional features (an augmented argument list for example).

rule_factory¶: alias of aurora.webapp.mapping.Rule

setUp()¶: Hook method for setting up the test fixture before exercising it.

test_assemble_accept_arbitrary_named_arguments()¶

Test if the rule assemble method accept arbitrary named arguments.

This test call the assemble method of the rule and assert if the result is False or a string.

test_assemble_without_arguments()¶

Test if the rule assemble method can be called without arguments.

This test call the assemble method of the rule and assert if the result is False or a string.

test_match_accept_one_positional_argument()¶

Test if the rule match method accept one positional argument.

This test call the match method of the rule and assert if the result is False or a Mapping.

Web application components¶

class aurora.webcomponents.views.Views¶

Provide generic template based view rendering support.

This component is based on the aurora.views.Views class from the Views framework. It provide the same services plus a new one (the render2response() service) specific for usage in the context of Web applications.

The component add a escape default content item designed to escape all content that represent a XSS attack vulnerability.

add_default(key: str, value)¶

Add a default context item.

Parameters:	key – Item key string. value – Item value

add_engine(engine: aurora.views.Engine, *extensions)¶

Register an Engine-like object for rendering files.

Parameters:	engine – An `Engine`-like object. extensions – List of template file extensions.

add_path(path: str)¶

Add an absolute path as template file source.

Parameters:	path – The absolute path (string) to a folder that store templates files.

handler4template(template_name: str, **context) → aurora.webapp.foundation.Handler¶

Produce a Web request handler that simply render a template.

This service use the render2response() service and the same rules about template names are applied.

`

param template_name:

The relative template name string without the last extension.

param context: The context mapping.

return: A Web request handler.

render(template_name: str, **context) → str¶

Render a template into content with context.

Parameters:	template_name – The relative template name string without the last extension. context – The context mapping.
Returns:	The rendered output string.

render2response(request: aurora.webapp.foundation.Request, template_name: str, **context) → aurora.webapp.foundation.Response¶

Render a template into a Response object with context.

Template file names must have two extensions. The first extension is used to identify the content type of the output and the second extension is used to identify the engine capable of handling correctly the syntax used in the template.

Parameters:	request – The request object used to build the response. template_name – The relative template name string without the last extension. context – The context mapping.
Returns:	The rendered `Response` object.

API Documentation¶

View rendering framework¶

Web application framework¶

Web application components¶

Table Of Contents

Previous topic

This Page

param template_name:
	The relative template name string without the last extension.
param context:	The context mapping.
return:	A Web request `handler`.