ea8a0f6a8b
An _environment source is added that looks in os.environ for values. Using the environment is on by default, but can be shut down by setting `use_env` to False when __call__ is called. The enviroment is inspected before any other sources of config data but the value is used after command line arguments and before config file options. This is done by checking both the command line and config files and then inspecting the location of the result. If it is command_line, we use it. If not, we use the environment value (if any). If there's no environment value, the config file value is used. If checking the command line and config file results in a KeyError, the environment value is used, if set. The names of the environment variables follow the rules described in oslo_config.sources._environment. A new exception has been added: ConfigSourceValueError, this is the superclass of the existing ConfigFileValueError. The code in _do_get has been updated to only use ConfigFileValueError when it is in fact a file from whence a ValueError came. Documentation has been updated and a rlease note created to indicate the new functionality. Change-Id: I3245c40ebdcc96f8e3b2dc0bab3b4aa71d07ad15
70 lines
2.3 KiB
ReStructuredText
70 lines
2.3 KiB
ReStructuredText
==========================
|
|
Option Setting Locations
|
|
==========================
|
|
|
|
.. currentmodule:: oslo_config.cfg
|
|
|
|
The :func:`~ConfigOpts.get_location` method of :class:`ConfigOpts` can
|
|
be used to determine where the value for an option was set, either by
|
|
the user or by the application code. The return value is a
|
|
:class:`LocationInfo` instance, which includes 2 fields: ``location``
|
|
and ``detail``.
|
|
|
|
The ``location`` value is a member of the :class:`Locations` enum,
|
|
which has 5 possible values. The ``detail`` value is a string
|
|
describing the location. Its value depends on the ``location``.
|
|
|
|
.. list-table::
|
|
:header-rows: 1
|
|
:widths: 15 15 35 35
|
|
|
|
* - Value
|
|
- ``is_user_controlled``
|
|
- Description
|
|
- ``detail``
|
|
* - ``opt_default``
|
|
- ``False``
|
|
- The original default set when the option was defined.
|
|
- The source file name where the option is defined.
|
|
* - ``set_default``
|
|
- ``False``
|
|
- A default value set by the application as an override of the
|
|
original default. This usually only applies to options defined
|
|
in libraries.
|
|
- The source file name where :func:`~ConfigOpts.set_default` or
|
|
:func:`set_defaults` was called.
|
|
* - ``set_override``
|
|
- ``False``
|
|
- A forced value set by the application.
|
|
- The source file name where :func:`~ConfigOpts.set_override` was
|
|
called.
|
|
* - ``user``
|
|
- ``True``
|
|
- A value set by the user through a configuration backend such as
|
|
a file.
|
|
- The configuration file where the option is set.
|
|
* - ``command_line``
|
|
- ``True``
|
|
- A value set by the user on the command line.
|
|
- Empty string.
|
|
* - ``environment``
|
|
- ``True``
|
|
- A value set by the user in the process environment.
|
|
- The name of the environment variable.
|
|
|
|
Did a user set a configuration option?
|
|
======================================
|
|
|
|
Each :class:`Locations` enum value has a boolean property indicating
|
|
whether that type of location is managed by the user. This eliminates
|
|
the need for application code to track which types of locations are
|
|
user-controlled separately.
|
|
|
|
.. code-block:: python
|
|
|
|
loc = CONF.get_location('normal_opt').location
|
|
if loc.is_user_controlled:
|
|
print('normal_opt was set by the user')
|
|
else:
|
|
print('normal_opt was set by the application')
|