Contents
TurboGears is designed to get running with a minimum of trouble and very little external configuration. For many applications, the only thing that will need to change from the basic tg quickstart configuration is the location of the database.
A quickstarted application comes with five configuration files:
- dev.cfg
- sample-prod.cfg
- test.cfg
- <package_name>/config/app.cfg
- <package_name>/config/log.cfg
The dev.cfg file is the deployment configuration used while you are developing your application.
The sample-prod.cfg contains appropriate settings for a “real” deployment. We recommend that you rename this file to prod.cfg and tweak the settings before deploying an application.
The test.cfg file is used when you run the test suite of your project. See Testing Your Application for more information about test suites.
Of these three files, only one will be used at a time, depending on how you start the server, that’s why they are located in the top-directory and not in your application’s package.
The app.cfg holds options that are always the same regardless of the environment your program runs in. While dev.cfg and prod.cfg are mostly concerned with database config strings, ports, and auto-reloading, app.cfg contains encoding, output, and identity settings.
The log.cfg holds logging configuration that is independent of of the environment your program runs in, e.g. different log handlers and log formatting profiles. Environment-specific logging configuration should go into dev.cfg or prod.cfg. See the logging documentation for more information on how logging works.
Running the server using start-*appname*.py will use the dev.cfg config file by default. You can change this by passing the path to another config file as a command line parameter:
python start-*appname*.py prod.cfg
The syntax is an extended version of the standard INI/ConfigParser format. The main extensions are an increased importance of sections and the addition some pre-defined variables for string interpolation, to reduce the number of hard coded file paths. If want to know more about this format, you can refer to the ConfigObj documentation.
The [global] section of the config file is intended for settings that apply server-wide and at start-up time. CherryPy also uses path-based config sections that are for setting filters and settings that apply only to one part of your site. The example below, will set tg.allow_json only for the /admin part of the site.
[/admin]
tg.allow_json = True
Like with the ConfigParser format, you can also use string interpolation, to refer to values of one configuration setting in the value of another setting within the config file. See the ConfigObj documentation on string interpolation for more information on this.
There are three pre-defined variables for string interpolation. The first is current_dir_uri, which is the absolute file system path to the current working directory. This is primarily used in the default sqlite’s dburi but can be used elsewhere:
sqlobject.dburi = "sqlite://%(current_dir_uri)s/devdata.sqlite"
The second is package_dir, the absolute file system path to the package containing the configuration of your application (the location of the config directory and the controllers.py module in a quickstarted project). It is used primarily in app.cfg to get a working filepath to the static content when the project is moved to a different server. Then there is also top_level_dir which is the directory of the top level package of your application (which is usually the same as package_dir unless your application is a subpackage of a larger package).
Retrieving values is done using the turbogears.config.get('key'[,default]) function:
>>> from turbogears import config
>>> config.get('sqlobject.dburi','sqlite:///:memory:') #second value is optional default value
'sqlite:///:memory:'
In your templates the turbogears.config.get function is available as tg-config, so you can do something like this:
${tg.config('myproject.mysetting', 'default')}
Alternatively, you can pass the config object as part of your template dictionary:
from turbogears import config
#...
def ...(self, ...)
return dict(config=config)
Or, if you prefer, you can import config in your Kid template:
<?python from turbogears import config ?>
In both cases, the syntax for retrieving configuration settings is the same as in your controller code.
TurboGears uses CherryPy’s configuration system. This document doesn’t cover the CherryPy settings and conventions in detail, but here is a short list of the most common options.
Specifies the root of the site for use when generating URLs. Use this if your whole TurboGears instance is not at the root of your webserver. So if your application was located at /turbogears/my_app rather than /my_app, you would set server.webpath = "/turbogears/".
Note: Despite the name, this option is a TurboGears extension to CherryPy and is used with the tg.url() function.
For a more complete treatment of CherryPy options, we defer you to the CherryPy site, specifically section 1.3 an overview of the configuration system and section 1.3.2 reference of some configuration options.
The SQLObject URI that identifies the database to use for this application. The general form of the URI is databasetype://username:password@hostname:port/databasename.
If you put :doc:`/notrans` in front of the URI, the automatic database transactions will be turned off.
Note that for sqlite, the format is more like that of a file:// URL: sqlite:///absolute_path_to_file.
Also note that on Windows systems, sqlite used | instead of : As of Turbogears 0.9a6, it is smart enough to undestand both ways. For example: sqlite:///d|databases/foo.db and sqlite:///d:databases/foo.db are both valid points to D:\databases\foo.db.
Note to MySQL users: If you use a different socket than /tmp/mysql.sock, you may specify which socket to use by adding a unix_socket argument to the dburi. i.e., mysql://user:pass@host:port/db?unix_socket=/path/to/mysql.sock.
Determines which template engine to use by default. If this is not set, Kid will be used to render the templates you specify in your controller. The template engine is identified by the file extension used.
See the alternative templating section for an overview of non-Kid options.
This option automatically includes the listed widgets in all pages on the site. This is primarily useful for javascript libraries that have been packaged as widgets, such as the tg.mochikit.
Note: This option has replaced the tg.mochikit_all option from older TurboGears releases. To achieve the same effect, you’ll want to set tg.include_widgets = ['turbogears.mochikit'].
Answering “yes” to the identity prompt during tg-admin quickstart will fill in your model with a number of tables and will add the following options to your app.cfg:
Domain name to specify when setting the cookie (must begin with a . (dot) according to RFC 2109). This is useful when your computer is at spam.eggs.foo.com and you want to set a cookie for your whole foo.com domain for use in other applications.
The default (None) should work for most cases and will default to the machine to which the request was made. Note: localhost is NEVER a valid value and will NOT work.
Where to look for the key of an existing visit in the request.
This should be a comma-separated list of the possible values: 'cookie', 'form'. The given methods will be tried one-after-another in the given order until a valid visit key is found or the list is exhausted. By default only use the visit key found in a session cookie. New in 1.0.6.
Comma-separated list of sources the identity should provider consider when determining the identity associated with a request. The given methods will be tried one-after-another in the given order until a valid identity is found or the list is exhausted.
Available options:
When identity.*provider.encryption_algorithm (see below under Provider) is set to "custom" you can provide a custom password encryption function through this setting. The value should be the full name of the callable (including the module (and possibly class) name) in dotted-path notation. The callable should accept the password to be encrypted as a string (utf-8 encoded) and return a unicode string with the encrypted password. Example:
identity.custom_encryption = 'mypkg.utils.encrypt_password'
These options are only applicable when using one of the default identity provider plugins. TurboGears supplies both a SQLObject and a SQLAlchemy identity provider, they are named soprovider and saprovider respectively and take the same options.
The password encryption algorithm used when comparing passwords against what’s stored in the database. Valid values are md5 or sha1 or custom.
If you do not specify an encryption algorithm, passwords are expected to be clear text. If the value is custom you must also set the the identity.custom.encryption setting (see above under Identity) to the name of an appropriate callable in dotted-path notation.
If this is set to a valid encryption algorithm the TurboGears identity provider will encrypt passwords supplied as part of your login form. If you set the password through the password property, like my_user.password = 'secret' the password will be saved in encrypted form in the database, provided identity is up and running, or you have loaded the configuration specifying what encryption to use (the latter may be necessary in situations where identity may not yet be running, like tests).