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 or through your .ini file, while AppConfig configuration options can only be set through the unless explicitly stated otherwise.


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 custom routes, 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 Authentication in TurboGears 2 applications 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 Ming 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.smtp_server -> SMTP Server to connect to for sending emails
  • 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
  • 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, **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.

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.


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:


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:


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


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


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.


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.


class tg.renderers.mako.MakoRenderer(dotted_finder, mako_lookup, use_dotted_templatenames)

Configuration Options available as templating.mako.*:

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