Previous topic

pylons.wsgiapp – PylonsWSGI App Creator

Next topic

tg.flash – Flash

tg.decorators – Decorators

Decorators use by the TurboGears controllers.

Not all of these decorators are traditional wrappers. They are much simplified from the turbogears 1 decorators, because all they do is register attributes on the functions they wrap, and then the DecoratedController provides the hooks needed to support these decorators.

class tg.decorators.Decoration(controller)

Simple class to support ‘simple registration’ type decorators

lookup_template_engine(request)

Return the template engine data.

Provides a convenience method to get the proper engine, content_type, template, and exclude_names for a particular tg_format (which is pulled off of the request headers).

register_custom_template_engine(custom_format, content_type, engine, template, exclude_names)

Registers a custom engine on the controller.

Mulitple engines can be registered, but only one engine per custom_format.

The engine is registered when @expose is used with the custom_format parameter and controllers render using this engine when the use_custom_format() function is called with the corresponding custom_format.

exclude_names keeps track of a list of keys which will be removed from the controller’s dictionary before it is loaded into the template. This allows you to exclude some information from JSONification, and other ‘automatic’ engines which don’t require a template.

register_hook(hook_name, func)

Registers the specified function as a hook.

We now have four core hooks that can be applied by adding decorators: before_validate, before_call, before_render, and after_render. register_hook attaches the function to the hook which get’s called at the apropriate time in the request life cycle.)

register_template_engine(content_type, engine, template, exclude_names)

Registers an engine on the controller.

Multiple engines can be registered, but only one engine per content_type. If no content type is specified the engine is registered at / which is the default, and will be used whenever no content type is specified.

exclude_names keeps track of a list of keys which will be removed from the controller’s dictionary before it is loaded into the template. This allows you to exclude some information from JSONification, and other ‘automatic’ engines which don’t require a template.

class tg.decorators.after_render(hook_func)

A list of callables to be run after the template is rendered.

Will be run before it is returned returned up the WSGI stack

class tg.decorators.allow_only(predicate, denial_handler=None)

TurboGears-specific repoze.what-pylons controller protector.

The default authorization denial handler of this protector will flash the message of the unmet predicate with warning or error as the flash status if the HTTP status code is 401 or 403, respectively, since by default the __before__ method of the controller is decorated with require.

If the controller class has the _failed_authorization class method, it will replace the default denial handler.

protector

alias of require

class tg.decorators.before_call(hook_func)

A list of callables to be run before the controller method is called

class tg.decorators.before_render(hook_func)

A list of callables to be run before the template is rendered

class tg.decorators.before_validate(hook_func)

A list of callables to be run before validation is performed

tg.decorators.default(func)

Registers a method as the “default” controller method

class tg.decorators.expose(template='', content_type=None, exclude_names=None, custom_format=None)

Registers attributes on the decorated function

Parameters :
template

Assign a template, you could use the syntax ‘genshi:template’ to use different templates. The default template engine is genshi.

content_type

Assign content type. The default content type is ‘text/html’.

exclude_names

Assign exclude names

The expose decorator registers a number of attributes on the decorated function, but does not actually wrap the function the way TurboGears 1.0 style expose decorators did.

This means that we don’t have to play any kind of special tricks to maintain the signature of the exposed function.

The exclude_names parameter is new, and it takes a list of keys that ought to be scrubbed from the dictinary before passing it on to the rendering engine. This is particularly usefull for JSON.

Expose decorator can be stacked like this:

@expose('json', exclude_names='d')
@expose('kid:blogtutorial.templates.test_form',
        content_type='text/html')
@expose('kid:blogtutorial.templates.test_form_xml',
        content_type='text/xml', custom_format='special_xml')
def my_exposed_method(self):
    return dict(a=1, b=2, d="username")

The expose(‘json’) syntax is a special case. json is a buffet rendering engine, but unlike others it does not require a template, and expose assumes that it matches content_type=’application/json’

If you want to declare a desired content_type in a url, you can use the mime-type style dotted notation:

"/mypage.json" ==> for json
"/mypage.html" ==> for text/html
"/mypage.xml" ==> for xml.

If you’re doing an http post, you can also declare the desired content type in the accept headers, with standard content type strings.

By default expose assumes that the template is for html. All other content_types must be explicitly matched to a template and engine.

The last expose uses the custom_format parameter which takes an arbitrary value (in this case ‘special_xml’). You can then use the`use_custom_format` function within the method to decide which of the ‘custom_format’ registered expose decorators to use to render the template.

tg.decorators.lookup(func)

Registers a method as the “lookup” controller method

tg.decorators.override_template(controller, template)

Use overide_template in a controller in order to change the template that will be used to render the response dictionary dynamically.

The template string passed in requires that you include the template engine name, even if you’re using the default.

So you have to pass in a template id string like:

"genshi:myproject.templates.index2"

future versions may make the genshi: optional if you want to use the default engine.

tg.decorators.paginate(name, items_per_page=10, use_prefix=False)

Paginate a given collection.

This decorator is mainly exposing the functionality of webhelpers.paginate().

Usage :

You use this decorator as follows:

class MyController(object):

    @expose()
    @paginate("collection")
    def sample(self, *args):
        collection = get_a_collection()
        return dict(collection=collection)

To render the actual pager, use:

${c.paginators.<name>.pager()}

where c is the tmpl_context.

It is possible to have several paginate()-decorators for one controller action to paginate several collections independently from each other. If this is desired, don’t forget to set the use_prefix-parameter to True.

Parameters :
name

the collection to be paginated.

items_per_page

the number of items to be rendered. Defaults to 10

use_prefix

if True, the parameters the paginate decorator renders and reacts to are prefixed with “<name>_”. This allows for multi-pagination.

tg.decorators.postpone_commits(func)

Turns sqlalchemy commits into flushes in the decorated method

This has the end-result of postponing the commit to the normal TG2 transaction boundry.

class tg.decorators.require(predicate, denial_handler=None)

TurboGears-specific repoze.what-pylons action protector.

The default authorization denial handler of this protector will flash the message of the unmet predicate with warning or error as the flash status if the HTTP status code is 401 or 403, respectively.

See allow_only for controller-wide authorization.

default_denial_handler(reason)

Authorization denial handler for repoze.what-pylons protectors.

tg.decorators.use_custom_format(controller, custom_format)

Use use_custom_format in a controller in order to change the active @expose decorator when available.

class tg.decorators.validate(validators=None, error_handler=None, form=None)

Regesters which validators ought to be applied

If you want to validate the contents of your form, you can use the @validate() decorator to regester the validators that ought to be called.

Parameters :
validators

Pass in a dictionary of FormEncode validators. The keys should match the form field names.

error_handler

Pass in the controller method which shoudl be used to handle any form errors

form

Pass in a ToscaWidget based form with validators

The first positional parameter can either be a dictonary of validators, a FormEncode schema validator, or a callable which acts like a FormEncode validator.

tg.decorators.with_trailing_slash(func)

This decorator allows you to ensure that the URL ends in “/” The decorator accomplish this by redirecting to the correct URL.

Usage :

You use this decorator as follows:

class MyController(object):

    @with_trailing_slash
    @expose()
    def sample(self, *args):
        return "found sample"

In the above example http://localhost:8080/sample redirects to http://localhost:8080/sample/ In addition, the URL http://localhost:8080/sample/1 redirects to http://localhost:8080/sample/1/

tg.decorators.without_trailing_slash(func)

This decorator allows you to ensure that the URL does not end in “/” The decorator accomplish this by redirecting to the correct URL.

Usage :

You use this decorator as follows:

class MyController(object):

    @without_trailing_slash
    @expose()
    def sample(self, *args):
        return "found sample"

In the above example http://localhost:8080/sample/ redirects to http://localhost:8080/sample In addition, the URL http://localhost:8080/sample/1/ redirects to http://localhost:8080/sample/1