Classes and Functions

This page provides a quick access reference to the classes and functions provided by TurboGears

Configuration

class tg.Configurator

Manages a configuration process with multiple components and steps.

Multiple registered components will be configured by applying the options provided during configuration on top of a bluepint (a set of default options).

The result will be a configuration dictionary and whatever side effect each component triggered when being configured.

This doesn’t really know anything about that it is configuring and is not TurboGears specific. An ApplicationConfigurator is provided which is a specialised Configurator for configuring TurboGears applications.

New in version 2.4.

configure(global_conf=None, app_conf=None)

Prepare a configuration using the configurator.

Once it’s ready the configuration is returned.

get_blueprint_value(name)

Get an option registered into the configuration blueprint.

get_blueprint_view(key)

A view is a subset of the blueprint options.

If the blueprint contains multiple values that share a common prefix it is possible to get a view that contains them all. A view acts like a dictionary where it is possible to get or set the values.

Given a blueprint that contains section.option1 and section.option2 it is possible to ask for the view of section and get back a dictionary like object that contains option1 and option2.

get_component(component_id)

Retrieve a registered configuration component.

register(component_type, after=None)

Registers a new configuration component to be performed by the Configurator

replace(component_id, new_component_type)

Replaces an existing configuration component with another one.

Any default value set in the blueprint by the previous component won’t be discarded and won’t be replaced. So if you tuned the configuration of the previous component, the new one will preserve it.

Also the id at which the component is registered won’t be the one of the new component, but will be the one of the old component.

In theory you should only replace components with components that provide same id and same default options.

Note that replacing a component will only influence the applications created after it was replaced.

setup(conf)

Given a configuration setup the environment.

Applies ConfigReadyConfigurationAction configuration actions from the registered components.

This usually involves all the configuration steps that already need to have all configuration options available before they can proceed.

update_blueprint(config)

Add options from config to the configuration blueprint.

class tg.ApplicationConfigurator

Bases: tg.configurator.base.Configurator

A Configurator specialised in creating TurboGears applications.

The configuration blueprint will be used as configuration foundation for every new application built from the Configurator, configuration blueprint is merged with deployment configuration loaded from config files before creating the application.

Refer to each registered configuration component for configuration options available in the Configurator.

New in version 2.4.

configure(global_conf=None, app_conf=None)

Initializes configuration of the application.

Applies all the blueprints, components defaults, global_conf, app_confg and components coercions then returns the resulting configuration. Also the configuration is set as the currently active one in the process.

This is the first step invoked by make_wsgi_app() to create a new TurboGears application.

classmethod current()

Retrieves the current ApplicationConfigurator given that a configuration is in place.

The current configurator is saved within the configuration itself, so whenever a configuration is in place it is possible to get access to the configurator and then access any of its componenets:

ApplicationConfigurator.current().get('componentid')
make_wsgi_app(global_conf=None, app_conf=None, wrap_app=None)

Creates a new WSGI TurboGears application with provided configuration.

register_application_wrapper(wrapper, after=None)

Registers a TurboGears application wrapper.

Application wrappers are like WSGI middlewares but are executed in the context of TurboGears and work with abstractions like Request and Respone objects.

See tg.appwrappers.base.ApplicationWrapper for complete definition of application wrappers.

The after parameter defines their position into the wrappers chain. The default value None means they are executed in a middle point, so they run after the TurboGears wrappers like ErrorPageApplicationWrapper which can intercept their response and return an error page.

Builtin TurboGears wrappers are usually registered with after=True which means they run furthest away from the application itself and can intercept the response of any other wrapper.

Providing after=False means the wrapper will be registered near to the application itself (so wrappers registered at default position and with after=True will be able to see its response).

after parameter can also accept an application wrapper class. In such case the registered wrapper will be registered right after the specified wrapper and so will be a little further from the application then the specified one (can see the response of the specified one).

replace_application_wrapper(key, wrapper)

Replaces a registered application wrapper with another one.

Note that this only applies to future applications that will be created, not to already existing ones.

setup(conf)

Setup a TurboGears application environment given a configuration.

This usually involves any configuration step that requires all configuration options to be available before it can be executed.

It’s also the place where ApplicationWrappers and ControllerWrappers are resolved.

class tg.MinimalApplicationConfigurator

Bases: tg.configurator.application.ApplicationConfigurator

An ApplicationConfigurator that enables minimum set of components.

This is meant to create small self contained applications that might serve the purpose of simple JSON webservices or micro web applications.

Enables components for:

  • mimetypes
  • load controllers and templates from paths
  • dispatch requests to a root controller
  • provide tg.app_globals
  • provide helpers in templates
  • support templates rendering
  • enable requests local registry for tg.request, tg.response, etc…
class tg.FullStackApplicationConfigurator

Bases: tg.configurator.minimal.MinimalApplicationConfigurator

An ApplicationConfigurator that enables all TurboGears components.

This is meant to create full stack applications or generally applications where most components are needed and some can be explicitly disabled.

Enables all components from MinimalApplicationConfigurator plus:

  • I18N support
  • Authentication
  • Sessions
  • Caching
  • Widgets (ToscaWidgets2)
  • Databases (Ming and SQLAlchemy)
  • Transaction Manager
  • Custom Error Pages
  • Seekable Requests
  • Slow Requests Reporting
  • Errors Reporting
  • Static Files
  • Interactive Debugger
class tg.configurator.base.ConfigurationComponent

Represents a configuration component that will collaborate in configuring an application.

Each component once registered in a Configurator can perform multiple actions at different times, each action can be registered by returing them through get_actions().

New in version 2.4.

get_actions()

Can be overridden to provide a set of actions the component has the perform.

Must return an iterable containing all the actions that must be performed by this configuration component at any given time:

(BeforeConfigConfigurationAction(self.setup_config),
 ConfigReadyConfigurationAction(self.initialize_things),
 EnvironmentLoadedConfigurationAction(self.add_middleware))
get_coercion()

Can be overridden to provide coercion methods for options.

Must return a dictionary in the form:

{'option_name': coerce_function}
get_defaults()

Can be overridden to provide default values for configuration blueprint.

This is used when the configuration component is added to a Configurator to retrieve any default value for configuration options.

Must return a dictionary in the form:

{'option_name': 'value'}
on_bind(configurator)

Called when component is bound to a Configurator.

This should be overridden to register global settings and entities like ApplicationWrappers and RenderingEngines into the configurator. It won’t be called more than once per Configurator.

class tg.configurator.base.BeforeConfigConfigurationAction(perform=None)

An action to be executed before the app configuration is initialised.

class tg.configurator.base.ConfigReadyConfigurationAction(perform=None)

An action to be executed once the configuration is loaded and ready.

class tg.configurator.base.EnvironmentLoadedConfigurationAction(perform=None)

An action to be executed once the environment needed to create the app is ready.

class tg.configurator.base.AppReadyConfigurationAction(perform=None)

An action to be executed once the application has been created.

It’s typically the best time where to wrap WSGI middlewares around the application.

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

class tg.decorators.cached(key=<class 'tg.support.NoDefault'>, expire='never', type=None, query_args=None, cache_headers=('content-type', 'content-length'), invalidate_on_startup=False, cache_response=True, **b_kwargs)

Decorator to cache the controller.

The namespace and cache key used to cache the controller are available as request.caching.namespace and request.caching.key. This only caches the controller, not the template, validation or the hooks associated to the controller. If you also want to cache template remember to return tg_cache option with the same cache key from the controller.

The following parameters are accepted:

key - Specifies the controller parameters used to generate the cache key.

NoDefault - Uses function name and parameters (excluding args) as the key (default)

None - No variable key, uses only function name as key

string - Use function name and only “key” parameter

list - Use function name and all parameters listed

expire
Time in seconds before cache expires, or the string “never”. Defaults to “never”
type
Type of cache to use: dbm, memory, file, memcached, or None for Beaker’s default
cache_headers
A tuple of header names indicating response headers that will also be cached.
invalidate_on_startup
If True, the cache will be invalidated each time the application starts or is restarted.
cache_response

Determines whether the response at the time the cache is used should be cached or not, defaults to True.

Note

When cache_response is set to False, the cache_headers argument is ignored as none of the response is cached.

class tg.decorators.decode_params(format='json')

Decorator that enables parsing parameters from request body.

By default the arguments are parsed in JSON format (which is currently the only supported format).

This should be used like:

Image you are posting a payload of type application/json like:

{
    "ticketlist_id": 2,
    "typology": "Xmas Discount",
    "quantity": 3,
    "price": 4.75
}

Your controller’s method will be something like

@expose('json')
@decode_params(format='json')
def create(
    self, typology=None,
    quantity=None, price=None,
    ticketlist_id=None, **kw
):
    print('*' * 60)
    print('ticket', typology, quantity, price, ticketlist_id)
    ...do stuff...
    return dict(ticket=something)
class tg.decorators.expose(template='', content_type=None, exclude_names=None, custom_format=None, render_params=None, inherit=False)

Register 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

custom_format

Registers as a custom format which can later be activated calling use_custom_format

render_params

Assign parameters that shall be passed to the rendering method.

inherit

Inherit all the decorations from the same method in the parent class. This will let the exposed method expose the same template as the overridden method template and keep the same hooks and validation that the parent method had.

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 dictionary before passing it on to the rendering engine. This is particularly useful for JSON.

The render_parameters is also new. It takes a dictionary of arguments that ought to be sent to the rendering engine, like this:

render_params={'method': 'xml', 'doctype': None}

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 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 decorator example 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.override_template(view, template)

Override the template to be used.

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

The view argument is the actual controller method for which you want to replace the template.

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.

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

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:

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

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

max_items_per_page

the maximum number of items allowed to be set via parameter. Defaults to 0 (does not allow to change that value).

use_prefix

if True, the parameters the paginate decorator renders and reacts to are prefixed with “<name>_”. This allows for multi-pagination.
class tg.decorators.require(predicate, denial_handler=None, smart_denial=False)

Decorator that checks if the specified predicate it met, if it isn’t it calls the denial_handler to prevent access to the decorated method.

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.

Parameters:
  • predicate – An object with a check_authorization(environ) method which must raise a tg.predicates.NotAuthorizedError if not met.
  • denial_handler – The callable to be run if authorization is denied (overrides default_denial_handler if defined).
  • smart_denial – A list of response types for which to trigger the smart denial, which will act as an API providing a pass-through tg.controllers.util.abort(). If True, ('application/json', 'text/xml') will be used.

If called, denial_handler will be passed a positional argument which represents a message on why authorization was denied.

Use allow_only property of TGController for controller-wide authorization.

default_denial_handler(reason)

Authorization denial handler for 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, chain_validation=False)

Registers which validators ought to be applied.

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

Parameters:
  • validators – A dictionary of FormEncode/TW2 validators, a tg.validation.Convert or any callable that might throw tg.validation.TGValidationError.
  • error_handler – Function or action that should be used to handle the errors.
  • form – A TW2 or ToscaWidgets form to validate ( to be provided instead of validators )
  • chain_validation – Whenever error_handler should perform validation too in case it’s a controller action or not. By default it’s disabled.

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

class tg.decorators.with_engine(engine_name=None, master_params=None)

Decorator to force usage of a specific database engine in TurboGears SQLAlchemy BalancedSession.

Parameters:
  • engine_name – ‘master’ or the name of one of the slaves, if is None it will not force any specific engine.
  • master_params – A dictionary or GET parameters that when present will force usage of the master node. The keys of the dictionary will be the name of the parameters to look for, while the values must be whenever to pop the parameter from the parameters passed to the controller (True/False). If master_params is a list then it is converted to a dictionary where the keys are the entries of the list and the value is always True.
class tg.caching.cached_property(func)

Works like python @property but the decorated function only gets executed once, successive accesses to the property will just return the value previously stored into the object.

The @cached_property decorator can be executed within a provided context, for example to make the cached property thread safe a Lock can be provided:

from threading import Lock
from tg.caching import cached_property

class MyClass(object):
    @cached_property
    def my_property(self):
        return 'Value!'
    my_property.context = Lock()

Validation

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

Registers which validators ought to be applied.

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

Parameters:
  • validators – A dictionary of FormEncode/TW2 validators, a tg.validation.Convert or any callable that might throw tg.validation.TGValidationError.
  • error_handler – Function or action that should be used to handle the errors.
  • form – A TW2 or ToscaWidgets form to validate ( to be provided instead of validators )
  • chain_validation – Whenever error_handler should perform validation too in case it’s a controller action or not. By default it’s disabled.

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

class tg.validation.Convert(func, msg=<tg.util.lazystring.LazyString object>, default=None)

Applies a conversion function as a validator.

This is meant to implement simple validation mechanism.

Any callable can be used for func as far as it accepts an argument and returns the converted object. In case of exceptions the validation is considered failed and the msg parameter is displayed as an error.

A default value can be provided for values that are missing (evaluate to false) which will be used in place of the missing value.

Example:

@expose()
@validate({
    'num': Convert(int, 'Must be a number')
}, error_handler=insert_number)
def post_pow2(self, num):
    return str(num*num)
exception tg.validation.TGValidationError(msg, value=None, error_dict=None)

Invalid data was encountered during validation.

The constructor can be passed a short message with the reason of the failed validation.

Authorization

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

Decorator that checks if the specified predicate it met, if it isn’t it calls the denial_handler to prevent access to the decorated method.

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.

Parameters:
  • predicate – An object with a check_authorization(environ) method which must raise a tg.predicates.NotAuthorizedError if not met.
  • denial_handler – The callable to be run if authorization is denied (overrides default_denial_handler if defined).
  • smart_denial – A list of response types for which to trigger the smart denial, which will act as an API providing a pass-through tg.controllers.util.abort(). If True, ('application/json', 'text/xml') will be used.

If called, denial_handler will be passed a positional argument which represents a message on why authorization was denied.

Use allow_only property of TGController for controller-wide authorization.

Built-in predicate checkers.

This is mostly took from repoze.what.precidates

This is module provides the predicate checkers that were present in the original “identity” framework of TurboGears 1, plus others.

class tg.predicates.CompoundPredicate(*predicates, **kwargs)

A predicate composed of other predicates.

class tg.predicates.All(*predicates, **kwargs)

Check that all of the specified predicates are met.

Parameters:predicates – All of the predicates that must be met.

Example:

# Grant access if the current month is July and the user belongs to
# the human resources group.
p = All(is_month(7), in_group('hr'))
evaluate(environ, credentials)

Evaluate all the predicates it contains.

Parameters:
  • environ – The WSGI environment.
  • credentials – The repoze.what credentials.
Raises:

NotAuthorizedError – If one of the predicates is not met.
class tg.predicates.Any(*predicates, **kwargs)

Check that at least one of the specified predicates is met.

Parameters:predicates – Any of the predicates that must be met.

Example:

# Grant access if the currest user is Richard Stallman or Linus
# Torvalds.
p = Any(is_user('rms'), is_user('linus'))
evaluate(environ, credentials)

Evaluate all the predicates it contains.

Parameters:
  • environ – The WSGI environment.
  • credentials – The repoze.what credentials.
Raises:

NotAuthorizedError – If none of the predicates is met.
class tg.predicates.has_all_permissions(*permissions, **kwargs)

Check that the current user has been granted all of the specified permissions.

Parameters:permissions – The names of all the permissions that must be granted to the user.

Example:

p = has_all_permissions('view-users', 'edit-users')
class tg.predicates.has_any_permission(*permissions, **kwargs)

Check that the user has at least one of the specified permissions.

Parameters:permissions – The names of any of the permissions that have to be granted to the user.

Example:

p = has_any_permission('manage-users', 'edit-users')
class tg.predicates.has_permission(permission_name, **kwargs)

Check that the current user has the specified permission.

Parameters:permission_name – The name of the permission that must be granted to the user.

Example:

p = has_permission('hire')
class tg.predicates.in_all_groups(*groups, **kwargs)

Check that the user belongs to all of the specified groups.

Parameters:groups – The name of all the groups the user must belong to.

Example:

p = in_all_groups('developers', 'designers')
class tg.predicates.in_any_group(*groups, **kwargs)

Check that the user belongs to at least one of the specified groups.

Parameters:groups – The name of any of the groups the user may belong to.

Example:

p = in_any_group('directors', 'hr')
class tg.predicates.in_group(group_name, **kwargs)

Check that the user belongs to the specified group.

Parameters:group_name (str) – The name of the group to which the user must belong.

Example:

p = in_group('customers')
class tg.predicates.is_user(user_name, **kwargs)

Check that the authenticated user’s username is the specified one.

Parameters:user_name (str) – The required user name.

Example:

p = is_user('linus')
class tg.predicates.is_anonymous(msg=None)

Check that the current user is anonymous.

Example:

# The user must be anonymous!
p = is_anonymous()

New in version 1.0.7.

class tg.predicates.not_anonymous(msg=None)

Check that the current user has been authenticated.

Example:

# The user must have been authenticated!
p = not_anonymous()
exception tg.predicates.NotAuthorizedError

Configuration

class tg.FullStackApplicationConfigurator

An ApplicationConfigurator that enables all TurboGears components.

This is meant to create full stack applications or generally applications where most components are needed and some can be explicitly disabled.

Enables all components from MinimalApplicationConfigurator plus:

  • I18N support
  • Authentication
  • Sessions
  • Caching
  • Widgets (ToscaWidgets2)
  • Databases (Ming and SQLAlchemy)
  • Transaction Manager
  • Custom Error Pages
  • Seekable Requests
  • Slow Requests Reporting
  • Errors Reporting
  • Static Files
  • Interactive Debugger
class tg.MinimalApplicationConfigurator

An ApplicationConfigurator that enables minimum set of components.

This is meant to create small self contained applications that might serve the purpose of simple JSON webservices or micro web applications.

Enables components for:

  • mimetypes
  • load controllers and templates from paths
  • dispatch requests to a root controller
  • provide tg.app_globals
  • provide helpers in templates
  • support templates rendering
  • enable requests local registry for tg.request, tg.response, etc…
class tg.wsgiapp.TGApp(config=None, **kwargs)
find_controller(controller)

Locates a controller for this TGApp.

This is the same af lookup_controller() but will reuse configuration of the application and will cache results.

Parameters:controller (str) – The controller name, this will be the name of the python module containing the controller.
classmethod lookup_controller(config, controller)

Locates a controller by attempting to import it then grab the SomeController instance from the imported module.

Override this to change how the controller object is found once the URL has been resolved.

Parameters:
  • config (dict) – The configuration options for the application, usually this will be tg.config.
  • controller (str) – The controller name, this will be the name of the python module containing the controller.

WebFlash

Flash messaging system for sending info to the user in a non-obtrusive way

class tg.flash.TGFlash(**options)

Support for flash messages stored in a plain cookie.

Supports both fetching flash messages on server side and on client side through Javascript.

When used from Python itself, the flash object provides a TGFlash.render() method that can be used from templates to render the flash message.

When used on Javascript, calling the TGFlash.render() provides a webflash javascript object which exposes .payload() and .render() methods that can be used to get current message and render it from javascript.

For a complete list of options supported by Flash objects see TGFlash.configure().

configure(cookie_name='webflash', default_status='ok', template=<string.Template object>, js_call='webflash.render()', js_template=<string.Template object>, allow_html=False)

Flash messages can be configured through ApplicationConfigurator using the following options:

  • flash.cookie_name -> Name of the cookie used to store flash messages
  • flash.default_status -> Default message status if not specified (ok by default)
  • flash.template -> string.Template instance used as the flash template when rendered from server side, will receive $container_id, $message and $status variables.
  • flash.allow_html -> Turns on/off escaping in flash messages, by default HTML is not allowed.
  • flash.js_call -> javascript code which will be run when displaying the flash from javascript. Default is webflash.render(), you can use webflash.payload() to retrieve the message and show it with your favourite library.
  • flash.js_template -> string.Template instance used to replace full javascript support for flash messages. When rendering flash message for javascript usage the following code will be used instead of providing the standard webflash object. If you replace js_template you must also ensure cookie parsing and delete it for already displayed messages. The template will receive: $container_id, $cookie_name, $js_call variables.
message

Get only current flash message, getting the flash message will delete the cookie.

pop_payload()

Fetch current flash message, status and related information.

Fetching flash message deletes the associated cookie.

render(container_id, use_js=True)

Render the flash message inside template or provide Javascript support for them.

container_id is the DIV where the messages will be displayed, while use_js switches between rendering the flash as HTML or for Javascript usage.

status

Get only current flash status, getting the flash status will delete the cookie.

Rendering

tg.render_template(template_vars, template_engine=None, template_name=None, **kwargs)

Renders a specific template in current TurboGears context.

Permits to manually render any template like TurboGears would for expositions. It also guarantees that the before_render_call and after_render_call hooks are called in the process.

Parameters:
  • template_vars (dict) – This is the dictonary of variables that should become available to the template. Template vars can also include the tg_cache dictionary which enables template caching.
  • template_engine (str) – This is the template engine name, same as specified inside tg.config['renderers'].
  • template_name (str) – This is the template to render, can be specified both as a path or using dotted notation if available.

TurboGears injects some additional variables in the template context, those include:

  • tg.config -> like tg.config in controllers
  • tg.flash_obj -> the flash object, call render on it to display it.
  • tg.quote_plus -> function to perform percentage escaping (%xx)
  • tg.url -> like tg.url in controllers
  • tg.identity -> like tg.request.identity in controllers
  • tg.session -> like tg.session in controllers
  • tg.locale -> Languages of the current request
  • tg.errors -> Validation errors
  • tg.inputs -> Values submitted for validation
  • tg.request -> like tg.request in controllers
  • tg.auth_stack_enabled -> if authentication is enabled or not
  • tg.predicates -> like tg.predicates in controllers
  • tmpl_context -> like tg.tmpl_context in controllers
  • response -> like tg.response in controllers
  • request -> like tg.request in controllers
  • config -> like tg.config in controllers
  • app_globals -> like tg.app_globals in controllers
  • session -> like tg.session in controllers
  • url -> like tg.url in controllers
  • h -> Your application helpers
  • translator -> The current gettext translator
  • _ -> like tg.i18n.ugettext

Additional variables can be added to every template by a variable_provider function inside the application configuration. This function is expected to return a dict with any variable that should be added the default template variables. It can even replace existing variables.

exception tg.render.MissingRendererError(template_engine)
tg.render.cached_template(template_name, render_func, ns_options=(), cache_key=None, cache_type=None, cache_expire=None, **kwargs)

Cache and render a template, took from Pylons

Cache a template to the namespace template_name, along with a specific key if provided.

Basic Options

template_name
Name of the template, which is used as the template namespace.
render_func
Function used to generate the template should it no longer be valid or doesn’t exist in the cache.
ns_options
Tuple of strings, that should correspond to keys likely to be in the kwargs that should be used to construct the namespace used for the cache. For example, if the template language supports the ‘fragment’ option, the namespace should include it so that the cached copy for a template is not the same as the fragment version of it.

Caching options (uses Beaker caching middleware)

cache_key
Key to cache this copy of the template under.
cache_type
Valid options are dbm, file, memory, database, or memcached.
cache_expire
Time in seconds to cache this template with this cache_key for. Or use ‘never’ to designate that the cache should never expire.

The minimum key required to trigger caching is cache_expire='never' which will cache the template forever seconds with no key.

class tg.renderers.base.RendererFactory

Factory that creates one or multiple rendering engines for TurboGears. Subclasses have to be registered with TemplateRenderingConfigurationComponent.register_engine() and must implement the create method accordingly.

classmethod create(config, app_globals)

Given the TurboGears configuration and application globals it must create a rendering engine for each one specified into the engines list.

It must return a dictionary in the form:

{'engine_name': rendering_engine_callable,
 'other_engine': other_rendering_callable}

Rendering engine callables are callables in the form:

func(template_name, template_vars,
     cache_key=None, cache_type=None, cache_expire=None,
     **render_params)

render_params parameter will contain all the values provide through @expose(render_params={}).

options = {}

Here specify the list of engines for which this factory will create a rendering engine and their options. They must be specified like:

engines = {'json': {'content_type': 'application/json'}}

Currently only supported option is content_type.

with_tg_vars = True

Here specify if turbogears variables have to be injected in the template context before using any of the declared engines. Usually True unless engines are protocols (ie JSON).

class tg.jsonify.JSONEncoder(**kwargs)

TurboGears custom JSONEncoder.

Provides support for encoding objects commonly used in TurboGears apps, like:

  • SQLAlchemy queries
  • Ming queries
  • Dates
  • Decimals
  • Generators

Support for additional types is provided through the __json__ method that will be called on the object by the JSONEncoder when provided and through the ability to register custom encoder for specific types using JSONEncoder.register_custom_encoder().

configure(isodates=False, custom_encoders=None, allow_lists=False, **kwargs)

JSON encoder can be configured through ApplicationConfigurator (app_cfg.base_config) using the following options:

  • json.isodates -> encode dates using ISO8601 format
  • json.custom_encoders -> List of tuples (type, encode_func) to register custom encoders for specific types.
  • json.allow_lists -> Allows lists to be encoded, this is usually disabled for security reasons due to JSON hijacking. See http://stackoverflow.com/questions/16289894 for additional details.
default(obj)

Implement this method in a subclass such that it returns a serializable object for o, or calls the base implementation (to raise a TypeError).

For example, to support arbitrary iterators, you could implement default like this:

def default(self, o):
    try:
        iterable = iter(o)
    except TypeError:
        pass
    else:
        return list(iterable)
    # Let the base class default method raise the TypeError
    return JSONEncoder.default(self, o)
register_custom_encoder(objtype, encoder)

Register a custom encoder for the given type.

Instead of using standard behavior for encoding the given type to JSON, the encoder will used instead. encoder must be a callable that takes the object as argument and returns an object that can be encoded in JSON (usually a dict).

tg.jsonify.encode(obj, encoder=None, iterencode=False)

Return a JSON string representation of a Python object.

tg.jsonify.encode_iter(obj, encoder=None)

Encode object, yielding each string representation as available.

Request & Response

class tg.request_local.Request(environ, charset=None, unicode_errors=None, decode_param_names=None, **kw)

WebOb Request subclass

The WebOb webob.Request has no charset, or other defaults. This subclass adds defaults, along with several methods for backwards compatibility with paste.wsgiwrappers.WSGIRequest.

args_params

Arguments used for dispatching the request.

This mixes GET and POST arguments.

controller_url

Url of the current controller.

disable_auth_challenger()

Disable authentication challenger for current request.

This will forward your response as is in case of 401 bypassing any repoze.who challenger.

disable_error_pages()

Disable custom error pages for the current request.

This will forward your response as is bypassing the ErrorPageApplicationWrapper

dispatch_state

Details and info about dispatcher that handled this request.

languages

Return the list of browser preferred languages ensuring that i18n.lang is listed.

plain_languages

Return the list of browser preferred languages

quoted_path_info

PATH used for dispatching the request.

response_ext

URL extension when URL Extensions are enabled.

In case URL Request Extension is enabled this will be the extension of the url. disable_request_extensions drives this is enabled or not.

response_type

Expected response content type when URL Extensions are enabled.

In case URL Request Extension is enabled this will be the content type of the expected response. disable_request_extensions drives this is enabled or not.

Extract a signed cookie of name from the request

The cookie is expected to have been created with Response.signed_cookie, and the secret should be the same as the one used to sign it.

Any failure in the signature of the data will result in None being returned.

class tg.request_local.Response(body=None, status=None, headerlist=None, app_iter=None, content_type=None, conditional_response=None, charset=<object object>, **kw)

WebOb Response subclass

content

The body of the response, as a bytes. This will read in the entire app_iter if necessary.

Save a signed cookie with secret signature

Saves a signed cookie of the pickled data. All other keyword arguments that WebOb.set_cookie accepts are usable and passed to the WebOb set_cookie method after creating the signed cookie value.

class crank.dispatchstate.DispatchState(request, dispatcher, params=None, path_info=None, ignore_parameters=None, strip_extension=True, path_translator=None)

This class keeps around all the pertainent info for the state of the dispatch as it traverses through the tree. This allows us to attach things like routing args and to keep track of the path the controller takes along the system.

Arguments:
request
object, must have a path_info attribute if path_info is not provided
dispatcher
dispatcher object to get the ball rolling
params
parameters to pass into the dispatch state will use request.params
path_info
pre-split list of path elements, will use request.pathinfo if not used
strip_extension
Whenever crank should strip the url extension or not resolving the path
path_translator
Function used to perform path escaping when looking for controller methods, can be None to perform no escaping or True to use default escaping function.

DispatchState instance for current request is made available in TurboGears2 as tg.request.dispatch_state as soon as the dispatch process is completed.

action

Method in charge of processing the request

add_controller(location, controller)

Add a controller object to the stack

add_routing_args(current_path, remainder, fixed_args, var_args)

Add the “intermediate” routing args for a given controller mounted at the current_path. This is mostly used during REST dispatch to keep track of intermediate arguments and make them always available.

controller

Controller currently handling the request

controller_path

Controllers that got traversed to dispatch the request

extension

Extension of the URL (only if strip_extension is enabled).

If the path ends with an extension and strip_extension is enabled the extension is stripped from the url and is available here.

params

Parameters passed to the action

path

The path (URL) that has to be dispatched

remainder

Part of the URL path remaining after lookup of the action.

Those is usually passed as positional arguments to the method in charge of the action together with params.

request

The request that originated the dispatch process

resolve()

Once a DispatchState is created resolving it performs the dispatch.

Returns the updated DispatchState where .controller, .action, .params and .remainder properties all point to the controller and method that should process the request and to the method arguments.

root_dispatcher

Root Dispatcher instance that initiated the dispatch flow

routing_args

Parameters detected by the routing system.

This includes Request parameters and parameters extracted in other ways (usually added through add_routing_args()). In case of REST it will include intermediate arguments retrieved during dispatch of parent controllers.

set_action(method, remainder)

Add the final method that will be called in the _call method

set_params(params)

Set parameters that will be passed to the called action

set_path(path_info)

Update path that needs to be dispatched.

In case this is changed during the dispatch process it won’t have any effect on the dispatch currently under execution.

Hooks

class tg.configuration.hooks.HooksNamespace

Manages hooks registrations and notifications

disconnect(hook_name, func, controller=None)

Disconnect an hook.

The registered function is removed from the hook notification list.

notify(hook_name, args=None, kwargs=None, controller=None, trap_exceptions=False)

Notifies a TurboGears hook.

Each function registered for the given hook will be executed, args and kwargs will be passed to the registered functions as arguments.

It permits to notify both application hooks:

tg.hooks.notify('custom_global_hook')

Or controller hooks:

tg.hooks.notify('before_render', args=(remainder, params, output),
                controller=RootController.index)
notify_with_value(hook_name, value, controller=None)

Notifies a TurboGears hook which is expected to return a value.

hooks with values are expected to accept an input value an return a replacement for it. Each registered function will receive as input the value returned by the previous function in chain.

The resulting value will be returned by the notify_with_value call itself:

app = tg.hooks.notify_with_value('before_config', app)
register(hook_name, func, controller=None)

Registers a TurboGears hook.

Given an hook name and a function it registers the provided function for that role. For a complete list of hooks provided by default have a look at Hooks and Wrappers.

It permits to register hooks both application wide or for specific controllers:

tg.hooks.register('before_render', hook_func, controller=RootController.index)
tg.hooks.register('startup', startup_function)
class tg.appwrappers.base.ApplicationWrapper(next_handler, config)

Basic interface of the TurboGears Application Wrappers.

Application wrappers are like WSGI middlewares but are executed in the context of TurboGears and work with abstractions like Request and Respone objects.

Application Wrappers can be registered using ApplicationConfigurator.register_application_wrapper() which will inject them into the next TGApp created.

While they can be any callable, inheriting from this base class is strongly suggested as enables additional behaviours and third party code might depend on them.

Application Wrappers require a next_handler which is the next handler to call in the chain and config which is the current application configuration.

__call__(controller, environ, context)

This is the actual wrapper implementation.

Wrappers are called for each request with the controller in charge of handling the request, the environ of the request and the TurboGears context of the request.

They should call the next_handler (which will accept the same parameters) and return a tg.request_local.Response instance which is the request response. Usually they will return the same response object provided by the next handler unless they want to replace it.

A simple logging wrapper might look like:

class LogAppWrapper(ApplicationWrapper):
    def __init__(self, handler, config):
        super(LogAppWrapper, self).__init__(handler, config)

    def __call__(self, controller, environ, context):
        print 'Going to run %s' % context.request.path
        return self.next_handler(controller, environ, context)
__init__(next_handler, config)

x.__init__(…) initializes x; see help(type(x)) for signature

injected

Whenever the Application Wrapper should be injected.

By default all application wrappers are injected into the wrappers chain, you might want to make so that they are injected or not depending on configuration options.

next_handler

The next handler in the chain

Milestones

class tg.configuration.milestones._ConfigMilestoneTracker(name)

Tracks actions that need to be performed when a specific configuration point is reached and required options are correctly initialized

reach()

Marks the milestone as reached.

Runs the registered actions. Calling this method multiple times should lead to nothing.

register(action, persist_on_reset=False)

Registers an action to be called on milestone completion.

If milestone is already passed action is immediately called

Internationalization

tg.i18n.set_lang(languages, **kwargs)

Set the current language(s) used for translations in current call and session.

languages should be a string or a list of strings. First lang will be used as main lang, others as fallbacks.

tg.i18n.get_lang(all=True)

Return the current i18n languages used

returns None if no supported language is available (no translations are in place) or a list of languages.

In case all parameter is False only the languages for which the application is providing a translation are returned. Otherwise all the languages preferred by the user are returned.

tg.i18n.add_fallback(lang, **kwargs)

Add a fallback language from which words not matched in other languages will be translated to.

This fallback will be associated with the currently selected language – that is, resetting the language via set_lang() resets the current fallbacks.

This function can be called multiple times to add multiple fallbacks.

tg.i18n.set_request_lang(languages, tgl=None)

Set the current request language(s) used for translations without touching the session language.

languages should be a string or a list of strings. First lang will be used as main lang, others as fallbacks.

tg.i18n.ugettext(value)

Mark a string for translation. Returns the localized unicode string of value.

Mark a string to be localized as follows:

_('This should be in lots of languages')
tg.i18n.lazy_ugettext(*args, **kwargs)

Lazy-evaluated version of the ugettext function

Mark a string for translation. Returns the localized unicode

string of value.

Mark a string to be localized as follows:

_('This should be in lots of languages')
tg.i18n.ungettext(singular, plural, n)

Mark a string for translation. Returns the localized unicode string of the pluralized value.

This does a plural-forms lookup of a message id. singular is used as the message id for purposes of lookup in the catalog, while n is used to determine which plural form to use. The returned message is a Unicode string.

Mark a string to be localized as follows:

ungettext('There is %(num)d file here', 'There are %(num)d files here',
          n) % {'num': n}
tg.i18n.lazy_ungettext(*args, **kwargs)

Lazy-evaluated version of the ungettext function

Mark a string for translation. Returns the localized unicode

string of the pluralized value.

This does a plural-forms lookup of a message id. singular is used as the message id for purposes of lookup in the catalog, while n is used to determine which plural form to use. The returned message is a Unicode string.

Mark a string to be localized as follows:

ungettext('There is %(num)d file here', 'There are %(num)d files here',
          n) % {'num': n}

Controller Utilities

Helper functions for controller operation.

URL definition and browser redirection are defined here.

tg.controllers.util.url(base_url='/', params=None, qualified=False, scheme=None)

Generate an absolute URL that’s specific to this application.

The URL function takes a string (base_url) and, appends the SCRIPT_NAME and adds parameters for all of the parameters passed into the params dict.

scheme can be passed in case of a qualified url to create an url with the given scheme.

tg.controllers.util.lurl(base_url=None, params=None, **kwargs)

Like tg.url but is lazily evaluated.

This is useful when creating global variables as no request is in place.

As without a request it wouldn’t be possible to correctly calculate the url using the SCRIPT_NAME this demands the url resolution to when it is displayed for the first time.

tg.controllers.util.redirect(base_url='/', params=None, redirect_with=<class 'tg.exceptions.HTTPFound'>, scheme=None)

Generate an HTTP redirect.

The function raises an exception internally, which is handled by the framework. The URL may be either absolute (e.g. http://example.com or /myfile.html) or relative. Relative URLs are automatically converted to absolute URLs. Parameters may be specified, which are appended to the URL. This causes an external redirect via the browser; if the request is POST, the browser will issue GET for the second request.

tg.controllers.util.etag_cache(key=None)

Use the HTTP Entity Tag cache for Browser side caching

If a “If-None-Match” header is found, and equivilant to key, then a 304 HTTP message will be returned with the ETag to tell the browser that it should use its current cache of the page.

Otherwise, the ETag header will be added to the response headers.

tg.controllers.util.abort(status_code=None, detail='', headers=None, comment=None, passthrough=False, error_handler=False)

Aborts the request immediately by returning an HTTP exception

In the event that the status_code is a 300 series error, the detail attribute will be used as the Location header should one not be specified in the headers attribute.

passthrough

When True instead of displaying the custom error document for errors or the authentication page for failed authorizations the response will just pass through as is.

Set to "json" to send out the response body in JSON format.

error_handler

When True instead of immediately abort the request it will create a callable that can be used as @validate error_handler.

A common case is abort(404, error_handler=True) as error_handler for validation that retrieves objects from database:

from formencode.validators import Wrapper

@validate({'team': Wrapper(to_python=lambda value:
                            Group.query.find({'group_name': value}).one())},
          error_handler=abort(404, error_handler=True))
def view_team(self, team):
    return dict(team=team)
tg.controllers.util.auth_force_logout()

Forces user logout if authentication is enabled.

tg.controllers.util.auth_force_login(user_name)

Forces user login if authentication is enabled.

As TurboGears identifies users by user_name the passed parameter should be anything your application declares being the user_name field in models.

tg.controllers.util.validation_errors_response(*args, **kwargs)

Returns a Response object with validation errors.

The response will be created with a 412 Precondition Failed status code and errors are reported in JSON format as response body.

Typical usage is as error_handler for JSON based api:

@expose('json')
@validate({'display_name': validators.NotEmpty(),
           'group_name': validators.NotEmpty()},
          error_handler=validation_errors_response)
def post(self, **params):
    group = Group(**params)
    return dict(group=group)

General Utilities

class tg.util.bunch.Bunch

A dictionary that provides attribute-style access.

tg.util.dates.get_fixed_timezone(offset)

Returns a tzinfo instance with a fixed offset from UTC.

offset should be provided in minutes or as a timedelta.

tg.util.dates.parse_datetime(value)

Parses a string and return a datetime.datetime.

This function supports time zone offsets. When the input contains one, the output uses a timezone with a fixed offset from UTC.

Raises ValueError if the input isn’t well formatted.

tg.util.dates.utctz = <UTC>

UTC tzinfo instance

tg.util.decorators.no_warn(f, *args, **kwargs)

Decorator that suppresses warnings inside the decorated function

exception tg.util.files.DottedFileLocatorError
class tg.util.files.DottedFileNameFinder

this class implements a cache system above the get_dotted_filename function and is designed to be stuffed inside the app_globals.

It exposes a method named get_dotted_filename with the exact same signature as the function of the same name in this module.

The reason is that is uses this function itself and just adds caching mechanism on top.

get_dotted_filename(template_name, template_extension='.html')

this helper function is designed to search a template or any other file by python module name.

Given a string containing the file/template name passed to the @expose decorator we will return a resource useable as a filename even if the file is in fact inside a zipped egg or in a frozen library.

The actual implementation is a revamp of the Genshi buffet support plugin, but could be used with any kind a file inside a python package.

Parameters:
  • template_name (str) – the string representation of the template name as it has been given by the user on his @expose decorator. Basically this will be a string in the form of: “myapp.templates.somename”
  • template_extension (str) – the extension we excpect the template to have, this MUST be the full extension as returned by the os.path.splitext function. This means it should contain the dot. ie: ‘.html’ This argument is optional and the default value if nothing is provided will be ‘.html’

The template_name parameter also accepts a form with explicit extension myapp.templates.somename!xhtml that will override the template_exstesion argument and will always use .xhtml as the extension. This is usually convenient in extensions and libraries that expose a template and want to ensure they work even in the case the application using them has a different extension for templates on the same engine.

classmethod lookup(name, extension='.html')

Convenience method that permits to quickly get a file by dotted notation.

Creates a DottedFileNameFinder and uses it to lookup the given file using dotted notation. As DottedFileNameFinder provides a lookup cache, using this method actually disables the cache as a new finder is created each time, for this reason if you have recurring lookups it’s better to actually create a dotted filename finder and reuse it.

tg.util.files.safe_filename(filename)

Escapes a filename to ensure is valid and secure.

Filename can then safely be stored on a regular file system and passed to os.path.join(). The filename returned is an ASCII only string for maximum portability:

>>> safe_filename("My cool movie.mov")
'My_cool_movie.mov'
>>> safe_filename("../../../etc/passwd")
'etc_passwd'
>>> safe_filename(u'i contain cool ümläuts.txt')
'i_contain_cool_umlauts.txt'

The function might return an empty filename. .

tg.util.html.script_json_encode(obj, encoder=<tg.jsonify.JSONEncoder object>, **kwargs)

Works exactly like tg.jsonify.encode() but is safe for use in <script> tags.

The following characters are escaped in strings:
  • <
  • >
  • &
  • '

This makes it safe to embed such strings in any place in HTML with the notable exception of double quoted attributes. In that case single quote your attributes or HTML escape it in addition.

class tg.util.lazystring.LazyString(func, *args, **kwargs)

Behaves like a string, but no instance is created until the string is actually used.

Takes a function which should be a string factory and a set of arguments to pass to the factory. Whenever the string is accessed or manipulated the factory is called to create the actual string. This is used mostly by lazy internationalization.

tg.util.lazystring.lazify(func)

Decorator to return a lazy-evaluated version of the original

Applying decorator to a function it will create a LazyString with the decorated function as factory.

tg.util.webtest.test_context(app, url=None, environ=None)

Sets up a TurboGears context allowing to use turbogears functions outside of a real request.

Everything inside the with statement will have a TurboGears context available

In case app is a TGApp instance (as the one that can be retrieved through configure_new_app hook) a context for such application is set in place.

In case of a WebTest application a request to /_test_vars is performed to setup the test variables.

In case app is None a fake application is created for which to setup the context.

url parameter is provided to simulate the context as being for that url and environ parameter is provided to allow changing WSGI environ entries for the context.

tg.util.sqlalchemy.dictify(obj)

Converts a SQLAlchemy model instance to a dictionary

tg.util.sqlalchemy.is_saobject(obj)

Checks if the provided object is a SQLAlchemy model instance

tg.util.ming.dictify(obj)

Converts a Ming model instance to a dictionary

tg.util.ming.is_mingobject(obj)

Checks if the provided object is a Ming model instance

tg.util.misc.unless(func, check=None)

Wraps func ensuring it returns a value different from check.

A new function that calls func and checks its value is returned. In case func returns a value equal to check a ValueError is raised.

A common usage pattern is to join this with Convert to fail validation when querying objects from the database if they do not exist:

Convert(unless(DBSession.query(User).get))
class tg.configuration.utils.DependenciesList(*entries)

Manages a list of entries which might depend one from the other.

This powers everything that needs to keep track of a list of entries that might have dependencies one to the other and keeps them linearised according to the dependencies. This powers the resolution of ConfigurationComponenets, ApplicationsWrappers and so on…

Note

This is highly inefficient as it is only meant to run at configuration time, a new implementation will probably be provided based on heapq in the future.

DEPENDENCY_HEADS = (False, None, True)

Those are the heads of the dependencies tree - False means before everything else - None means in the middle. - True means after everything else.

add(entry, key=None, after=None)

Adds an entry to the dependencies list.

Parameters:
  • entry – Entry that must be added to the list.
  • key (str|type|None) – An identifier of the object being inserted. This is used by later insertions as after argument to specify after which object the new one should be inserted.
  • after (str|type|None|False|True) – After which element this one should be inserted. This is the key of a previously inserted item. In case no item with key has been inserted, the entry will be inserted in normal order of insertion. Also accepts one of DependenciesList.DEPENDENCY_HEADS as key to add entries at begin or end of the list.
replace(key, newvalue)

Replaces entry associated to key with a new one.

Parameters:
  • newvalue – Entry that must replace the previous value.
  • key (str|type) – An identifier of the object being inserted.
values()

Returns all the inserted values without their key as a generator

class tg.configuration.utils.DictionaryView(d, keypath)

Provides a view on a slice of a dictionary.

This allows to expose all keys in a dictionary that start with a common prefix as a subdictionary.

For example you might expose all keys starting with sqlalchemy.* as a standalone dictionary, all changes to the view will reflect into the dictionary updating the original keys.

class tg.configuration.utils.GlobalConfigurable

Defines a configurable TurboGears object with a global default instance.

GlobalConfigurable are objects which the user can create multiple instances to use in its own application or third party module, but for which TurboGears provides a default instance.

Common examples are tg.flash and the default JSON encoder for which TurboGears provides default instances of .TGFlash and .JSONEncoder classes but users can create their own.

While user created versions are configured calling the GlobalConfigurable.configure() method, global versions are configured by ApplicationConfigurator which configures them when config_ready milestone is reached.

configure(**options)

Expected to be implemented by each object to proceed with actualy configuration.

Configure method will receive all the options whose name starts with CONFIG_NAMESPACE (example json.isodates has json. namespace).

If CONFIG_OPTIONS is specified options values will be converted with coerce_config() passing CONFIG_OPTIONS as the converters dictionary.

classmethod create_global()

Creates a global instance whose configuration is linked to tg.config.

exception tg.configuration.utils.TGConfigError
tg.configuration.utils.coerce_config(configuration, prefix, converters)

Extracts a set of options with a common prefix and converts them.

To extract all options starting with trace_errors. from the conf dictionary and conver them:

trace_errors_config = coerce_config(conf, 'trace_errors.', {
    'smtp_use_tls': asbool,
    'dump_request_size': asint,
    'dump_request': asbool,
    'dump_local_frames': asbool,
    'dump_local_frames_count': asint
})
tg.configuration.utils.coerce_options(options, converters)

Convert some configuration options to expected types.

To replace given options with the converted values in a dictionary you might do:

conf.update(coerce_options(conf, {
    'debug': asbool,
    'serve_static': asbool,
    'auto_reload_templates': asbool
}))
tg.configuration.utils.copyoption(v)

Copies a dictionary and all its nested dictionaries and lists.

Much like copy.deepcopy it provides a deep copy of a dictionary but instead of trying to copy everything it will only make a copy of dictionaries, lists, tuples and sets. All the containers typically used in configuration blueprints. All the other objects will be preserved by reference.

tg.configuration.utils.get_partial_dict(prefix, dictionary, container_type=<type 'dict'>, ignore_missing=False, pop_keys=False)

Given a dictionary and a prefix, return a Bunch, with just items that start with prefix

The returned dictionary will have ‘prefix.’ stripped so:

get_partial_dict('prefix', {'prefix.xyz':1, 'prefix.zyx':2, 'xy':3})

would return:

{'xyz':1,'zyx':2}
© Copyright by the TurboGears Doc Team. Created using Sphinx 1.8.5.