Configuration Options¶

This section reports a reference of various configuration options available inside TurboGears app_cfg or .ini file. As they are automatically extracted from the source code this list might be incomplete until the whole configuration process is updated to automatically declare the expected options.

For example if you want to enable isodates in your application JSON encoder you might want to add to your app_cfg.base_config the following:

base_config['json.isodates'] = True

All the configuration options provided by Application Wrappers can usually be set both through the app_cfg.py or through your .ini file, while AppConfig configuration options can only be set through the app_cfg.py unless explicitly stated otherwise.

AppConfig¶

class tg.configuration.AppConfig(minimal=False, root_controller=None)

Class to store application configuration.

This class should have configuration/setup information that is necessary for proper application function. Deployment specific configuration information should go in the config files (e.g. development.ini or deployment.ini).

AppConfig instances have a number of methods that are meant to be overridden by users who wish to have finer grained control over the setup of the WSGI environment in which their application is run.

This is the place to configure your application, database, transaction handling, error handling, etc.

Configuration Options provided:

debug -> Enables / Disables debug mode. Can be set from .ini file

serve_static -> Enable / Disable serving static files. Can be set from .ini file

use_dotted_templatenames -> Use template names as packages in @expose instead of file paths. This is usually the default unless TG is started in Minimal Mode. Can be set from .ini file

registry_streaming -> Enable streaming of responses, this is enabled by default. Can be set from .ini file
paths -> Dictionary of directories where templates, static files and controllers are found:
{
    'controllers': 'my/path/to/controlllers',
    'static_files': 'my/path/to/files',
    'templates': ['list/of/paths/to/templates']
)
use_toscawidgets -> Enable ToscaWidgets1, this is deprecated.

use_toscawidgets2 -> Enable ToscaWidgets2

prefer_toscawidgets2 -> When both TW2 and TW1 are enabled prefer TW2. Can be set from .ini file

custom_tw2_config -> Dictionary of configuration options for TW2, refer to tw2.core.middleware.Config for available options.

auth_backend -> Authentication Backend, can be None, sqlalchemy or ming.

sa_auth -> Simple Authentication configuration dictionary. This is a Dictionary that contains the configuration options for repoze.who, see Identification & Authentication Layer for available options. Basic options include:

cookie_secret -> Secret phrase used to verify auth cookies.

authmetadata -> Authentication and User Metadata Provider for TurboGears

post_login_url -> Redirect users here after login

post_logout_url -> Redirect users here when they logout

package -> Application Package, this is used to configure paths as being inside a python

app_globals -> Application Globals class, by default build from package.lib.app_globals. package. Which enables serving templates, controllers, app globals and so on from the package itself.

helpers -> Template Helpers, by default package.lib.helpers is used.

model -> The models module (or object) where all the models, DBSession and init_models method are

available. By default package.model is used.

renderers -> List of enabled renderers names.

default_renderer -> When not specified, use this renderer for templates.

auto_reload_templates -> Automatically reload templates when modified (disable this on production for a performance gain). Can be set from .ini file

use_ming -> Enable/Disable Ming as Models storage.

ming.url -> Url of the MongoDB database

ming.db -> If Database is not provided in ming.url it can be specified here.

ming.connection.* -> Options to configure the ming connection, refer to ming.datastore.create_datastore() for available options.

use_sqlalchemy -> Enable/Disable SQLalchemy as Models storage.

sqlalchemy.url -> Url of the SQLAlchemy database. Refer to SQLAlchemy Master Slave Load Balancing for configuring master-slave urls.

Error Reporting¶

tg.error.ErrorReporter(app, global_conf, **errorware)¶

Provides Error reporting through Backlash on TurboGears.

This is enabled/disabled through the debug configuration option. Currently EMail and Sentry backlash reporters can be enabled.

All the options available for error reporting are configured as trace_errors.* options in your app_cfg or .ini files.

The available options for EMail reporter are:

trace_errors.enable -> Enable or disable error reporting, by default is enabled if backlash is available and debug=false

trace_errors.smtp_server -> SMTP Server to connect to for sending emails

trace_errors.smtp_port -> SMTP port to connect to

trace_errors.from_address -> Address sending the error emails

trace_errors.error_email -> Address the error emails should be sent to.

trace_errors.smtp_username -> Username to authenticate on SMTP server.

trace_errors.smtp_password -> Password to authenticate on SMTP server.

trace_errors.smtp_use_tls -> Whenever to enable or not TLS for SMTP.

trace_errors.error_subject_prefix -> Prefix to append to error emails, by default WebApp Error: is prepended.

trace_errors.dump_request -> Whenever to attach a request dump to the email so that all request data is provided.

trace_errors.dump_request_size -> Do not dump request if it’s bigger than this value, useful for uploaded files. By default 50K.

trace_errors.dump_local_frames -> Enable dumping local variables in case of crashes.

trace_errors.dump_local_frames_count -> Dump up to X frames when dumping local variables. The default is 2

Available options for Sentry reporter are:

trace_errors.sentry_dsn -> Sentry instance where to send the errors.

Slow Requests Reporting¶

tg.error.SlowReqsReporter(app, global_conf, **errorware)¶

Provides slow requests reporting for TurboGears through BackLash.

This is enabled through the trace_slowreqs.enable option and is only enabled when debug=false.

All the options available for error reporting are configured as trace_slowreqs.* options in your app_cfg or .ini files:

trace_slowreqs.enable -> Enable/Disable slow requests reporting, by default it’s disabled.

trace_slowreqs.interval -> Report requests slower than this value (default: 25s)

trace_slowreqs.exclude -> List of urls that should be excluded

Slow requests are reported using EMail or Sentry, the same options available in ErrorReporter apply with trace_slowreqs. instead of trace_errors..

JSON Encoding¶

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

JSON encoder can be configured through AppConfig (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.

Flash Messages¶

TGFlash.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 AppConfig (app_cfg.base_config) 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.

Sessions¶

class tg.appwrappers.session.SessionApplicationWrapper(handler, config)¶

Provides the Session Support

The Session Application Wrapper will make a lazy session instance available every request under the environ['beaker.session'] key and inside TurboGears context as session.

Supported options which can be provided by config are:

session.enabled: Whenever sessions are enabled or not.
Beaker Options prefixed with session., see https://beaker.readthedocs.org/en/latest/configuration.html#session-options

Caching¶

class tg.appwrappers.caching.CacheApplicationWrapper(handler, config)¶

Provides Caching Support.

The Cache Application Wrapper will make a CacheManager instance available every request under the environ['beaker.cache'] key and inside the TurboGears request context as cache.

Supported options which can be provided by config are:

cache.enabled: Whenever caching is enabled or not.
Beaker Options prefixed with cache., see https://beaker.readthedocs.org/en/latest/configuration.html#cache-options

Internationalization¶

class tg.appwrappers.i18n.I18NApplicationWrapper(handler, config)¶

Provides Language detection from request and session.

The session language(s) take priority over the request languages.

Supported options which can be provided by config are:

i18n.enabled: Whenever language detection is enabled or not.
i18n.lang: Fallback language for the application, works both when language detection is enabled or disabled. If this is set and language detection is dislabled, the application will consider that all gettext wrapped strings must be translated to this language.
i18n.lang_session_key: Session key from which to read the saved language (tg_lang by default).
i18n.no_session_touch: Avoid causing a session save when reading it to retrieve the favourite user language. This is False by default, setting it to False causes TurboGears to save and update the session for each request.

User Identity¶

class tg.appwrappers.identity.IdentityApplicationWrapper(handler, config)¶

Provides user identity when authentication is enabled.

The repoze.who provided identity takes precedence over the identity provided by IdentityApplicationWrapper if available.

Supported options which can be provided by config are:

sa_auth.authmetadata: The TGAuthMetadata object that should be used to retrieve identity metadata.
identity.enabled: Enable the Identity Application Wrapper. By default enabled if authmetadata available.
identity.allow_missing_user: Whenever the identity should be discarded or not when the authmetadata is unable to find an user.

Transaction Manager¶

class tg.appwrappers.transaction_manager.TransactionApplicationWrapper(handler, config)¶

Wraps the whole application in zope.transaction transaction manager and rollbacks transaction in case of crashes.

Supported options which can be provided by config are:

tm.enabled: Wenever the transaction manager is enabled or not.

tm.attempts: Number of times the transaction should be retried if it fails (no retry by default)

tm.commit_veto: A function that will be called for every transaction to check if it should abort transaction or let it go. Function signature should be: function(environ, status_code, headers) -> bool.

Custom Error Pages¶

class tg.appwrappers.errorpage.ErrorPageApplicationWrapper(handler, config)¶

Given an Application it intercepts the response code and shows a custom page.

Supported options are:

errorpage.enabled: Whenever the custom error page is enabled or not.

errorpage.status_codes: List of HTTP errors that should be trapped. By default 403, 404, 500.

errorpage.content_types: List of Content-Types for which the custom error page should be displayed. IE: ["text/html"]. An empty list means all. An entry with value None means no content type provided. Default is ["text/html", None].

errorpage.handle_exceptions: Whenever exceptions should be trapped and treated as a 500 error or not. By default this is True when debug=false.

errorapge.path: Path of the controller should be displayed in case of errors. By default /error/document.

Ming Session Manager¶

class tg.appwrappers.mingflush.MingApplicationWrapper(handler, config)¶

Automatically flushes the Ming ODMSession.

In case an exception raised during excution it won’t flush the session and it will instead close it throwing away any change.

Supported options which can be provided by config are:

ming.autoflush: Whenever to flush session at end of request if no exceptions happened.

Rendering Engines¶

Genshi¶

class tg.renderers.genshi.GenshiRenderer(loader, config)¶

Configuration Options available as templating.genshi.*:

templating.genshi.name_constant_patch -> Enable/Disable patch for Python3.4 compatibility.

templating.genshi.max_cache_size -> Maximum number of templates to keep cached, by default 30.

templating.genshi.method -> Genshi rendering method (html or xhtml).

Supported render_params:

Caching options supported by cached_template()

doctype -> To override the global doctype

method -> To override the global rendering method

Kajiki¶

class tg.renderers.kajiki.KajikiRenderer(loader)¶

Configuration Options available as templating.kajiki.*:

templating.kajiki.force_mode -> Kajiki Rendering Mode (html, html5, xml). Default html5.

templating.kajiki.template_extension -> Kajiki Templates extension, default .xhtml

templating.kajiki.xml_autoblocks -> List of tags that should be automatically converted to blocks.

templating.kajiki.cdata_scripts -> Automatically wrap scripts in CDATA.

templating.kajiki.html_optional_tags -> Allow unclosed html, head and body tags.

templating.kajiki.strip_text -> Strip leading/trailing spaces from text nodes.

Supported render_params:

Caching options supported by cached_template()

All arguments supported by kajiki.xml_template.XMLTemplate()

Jinja2¶

class tg.renderers.jinja.JinjaRenderer(jinja2_env)¶: Currently Jinja2 support uses a bunch of options from the AppConfig and doesn’t provide its own namespace.

Mako¶

class tg.renderers.mako.MakoRenderer(use_dotted_templatenames, template_extension, dotted_loader, normal_loader)¶

Configuration Options available as templating.mako.*:

templating.mako.template_extension -> Mako Templates extension, default .mak

templating.mako.compiled_templates_dir -> Where to store mako precompiled templates. By default templates are only stored in memory and not on disk.

JSON¶

class tg.renderers.json.JSONRenderer¶

JSON rendering can be configured using options supported by JSONEncoder.configure()

Supported render_params:

All supported by JSONEncoder.configure()
key -> Render a single key of the dictionary returned by controller instead of rendering the dictionary itself.
callback_param -> Name of the callback to call in rendered JS for jsonp

Table Of Contents

Previous topic

Next topic

Configuration Options¶

AppConfig¶

Error Reporting¶

Slow Requests Reporting¶

JSON Encoding¶

Flash Messages¶

Sessions¶

Caching¶

Internationalization¶

User Identity¶

Transaction Manager¶

Custom Error Pages¶

Ming Session Manager¶

Rendering Engines¶

Genshi¶

Kajiki¶

Jinja2¶

Mako¶

JSON¶