add user documentation for get_location()
Change-Id: I35ef216552b0b8def9c70b262825acb4a50083f4 Signed-off-by: Doug Hellmann <doug@doughellmann.com>
This commit is contained in:
parent
2fce6fc40a
commit
835cad6aa0
|
@ -17,8 +17,8 @@
|
|||
namespaces
|
||||
styleguide
|
||||
mutable
|
||||
locations
|
||||
builtins
|
||||
sphinxext
|
||||
sphinxconfiggen
|
||||
faq
|
||||
|
||||
|
|
|
@ -0,0 +1,65 @@
|
|||
==========================
|
||||
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.
|
||||
|
||||
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')
|
||||
if loc.is_user_controlled:
|
||||
print('normal_opt was set by the user')
|
||||
else:
|
||||
print('normal_opt was set by the application')
|
Loading…
Reference in New Issue