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

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

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

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

### 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`(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.