105 lines
3 KiB
ReStructuredText
105 lines
3 KiB
ReStructuredText
|
|
||
|
|
Config Settings
|
||
|
|
===============
|
||
|
|
|
||
|
|
The app uses :term:`config settings<config setting>` to control its
|
||
|
|
behavior at runtime.
|
||
|
|
|
||
|
|
The term "config setting" may be thought of as a combination of these
|
||
|
|
terms:
|
||
|
|
|
||
|
|
* :term:`config file`
|
||
|
|
* :term:`settings table`
|
||
|
|
|
||
|
|
It really refers to the **value** of such a config setting, when you
|
||
|
|
get right down to it. The app uses a :term:`config object` to keep
|
||
|
|
track of its config settings.
|
||
|
|
|
||
|
|
|
||
|
|
.. _reading-config-settings:
|
||
|
|
|
||
|
|
Reading Values via Python
|
||
|
|
-------------------------
|
||
|
|
|
||
|
|
Call the config object's :meth:`~wuttjamaican.conf.WuttaConfig.get()`
|
||
|
|
method to retrieve a value based on the setting name.
|
||
|
|
|
||
|
|
Note that raw values are always strings. The config object has other
|
||
|
|
methods if you want to interpret the value as a particular type::
|
||
|
|
|
||
|
|
from wuttjamaican.conf import make_config
|
||
|
|
|
||
|
|
config = make_config()
|
||
|
|
|
||
|
|
config.get('foo.bar')
|
||
|
|
config.get_int('foo.baz')
|
||
|
|
config.get_bool('foo.feature')
|
||
|
|
config.get_list('foo.words')
|
||
|
|
|
||
|
|
See :class:`~wuttjamaican.conf.WuttaConfig` for full details.
|
||
|
|
|
||
|
|
|
||
|
|
.. _where-config-settings-come-from:
|
||
|
|
|
||
|
|
Where Values Come From
|
||
|
|
----------------------
|
||
|
|
|
||
|
|
Config settings usually come from either a :term:`config file` or a
|
||
|
|
:term:`settings table`. The :term:`config object` is ultimately
|
||
|
|
responsible for sorting out which value to return.
|
||
|
|
|
||
|
|
Technically the app may also specify some fallback/default values; for
|
||
|
|
sake of this discussion we'll treat those as if they come from config
|
||
|
|
file.
|
||
|
|
|
||
|
|
All apps are expected to use config file(s), but not all will have a
|
||
|
|
settings table. The config file(s) may specify whether a settings
|
||
|
|
table should be used.
|
||
|
|
|
||
|
|
There are only 2 config settings which control this behavior. For a
|
||
|
|
typical example which enables both:
|
||
|
|
|
||
|
|
.. code-block:: ini
|
||
|
|
|
||
|
|
[wutta.config]
|
||
|
|
usedb = true
|
||
|
|
preferdb = true
|
||
|
|
|
||
|
|
[wutta.db]
|
||
|
|
default.url = sqlite://
|
||
|
|
|
||
|
|
Note that to use a settings table you must of course define a DB
|
||
|
|
connection.
|
||
|
|
|
||
|
|
So the ``usedb`` and ``preferdb`` flags may be set to accomplish any
|
||
|
|
of these scenarios:
|
||
|
|
|
||
|
|
* enable both - settings table is checked first, config files used as
|
||
|
|
fallback
|
||
|
|
* enable ``usedb`` but not ``preferdb`` - config files are checked
|
||
|
|
first, settings table used as fallback
|
||
|
|
* disable ``usedb`` - config files only; do not use settings table
|
||
|
|
|
||
|
|
Most apps will want to enable both flags so that when the settings
|
||
|
|
table is updated, it will immediately affect app behavior regardless
|
||
|
|
of what values are in the config files.
|
||
|
|
|
||
|
|
The values for these flags is available at runtime as:
|
||
|
|
|
||
|
|
* :attr:`~wuttjamaican.conf.WuttaConfig.usedb`
|
||
|
|
* :attr:`~wuttjamaican.conf.WuttaConfig.preferdb`
|
||
|
|
|
||
|
|
Regardless of what the "normal" behavior is for the config object (per
|
||
|
|
those flags), you can explcitly request other behavior by passing
|
||
|
|
similar flags to the config object's
|
||
|
|
:meth:`~wuttjamaican.conf.WuttaConfig.get()` method::
|
||
|
|
|
||
|
|
config.get('foo.bar', usedb=True, preferdb=True)
|
||
|
|
|
||
|
|
config.get('foo.baz', usedb=False)
|
||
|
|
|
||
|
|
Some of the "core" settings in the framework are fetched with
|
||
|
|
``usedb=False`` so they will never be read from the settings table.
|
||
|
|
Canonical example of this would be the setting(s) which defines the DB
|
||
|
|
connection itself.
|