summaryrefslogtreecommitdiffstats
path: root/ipalib/config.py
diff options
context:
space:
mode:
Diffstat (limited to 'ipalib/config.py')
-rw-r--r--ipalib/config.py50
1 files changed, 37 insertions, 13 deletions
diff --git a/ipalib/config.py b/ipalib/config.py
index c3c3a95ce..84c0aab4c 100644
--- a/ipalib/config.py
+++ b/ipalib/config.py
@@ -18,11 +18,14 @@
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
"""
-Basic configuration management.
+Process-wide static configuration and environment.
-This module handles the reading and representation of basic local settings.
-It will also take care of settings that can be discovered by different
-methods, such as DNS.
+The standard run-time instance of the `Env` class is initialized early in the
+`ipalib` process and is then locked into a read-only state, after which no
+further changes can be made to the environment throughout the remaining life
+of the process.
+
+For the per-request thread-local information, see `ipalib.request`.
"""
from ConfigParser import RawConfigParser, ParsingError
@@ -288,6 +291,8 @@ class Env(object):
(0, 3)
Also see `Env._merge_from_file()`.
+
+ :param kw: Variables provides as keyword arguments.
"""
i = 0
for (key, value) in kw.iteritems():
@@ -311,8 +316,23 @@ class Env(object):
containing first the number of variables that were actually set, and
second the total number of variables found in ``config_file``.
+ This method will raise a ``ValueError`` if ``config_file`` is not an
+ absolute path. For example:
+
+ >>> env = Env()
+ >>> env._merge_from_file('my/config.conf')
+ Traceback (most recent call last):
+ ...
+ ValueError: config_file must be an absolute path; got 'my/config.conf'
+
Also see `Env._merge()`.
+
+ :param config_file: Absolute path of the configuration file to load.
"""
+ if path.abspath(config_file) != config_file:
+ raise ValueError(
+ 'config_file must be an absolute path; got %r' % config_file
+ )
if not path.isfile(config_file):
return
parser = RawConfigParser()
@@ -361,8 +381,8 @@ class Env(object):
`Env._merge()`. The intended use of ``overrides`` is to merge-in
variables specified on the command-line.
- 3. Intelligently fill-in the ``in_tree``, ``context``, ``conf``,
- and ``conf_default`` variables if they haven`t been set already.
+ 3. Intelligently fill-in the *in_tree*, *context*, *conf*, and
+ *conf_default* variables if they haven`t been set already.
Also see `Env._finalize_core()`, the next method in the bootstrap
sequence.
@@ -413,22 +433,24 @@ class Env(object):
``self.conf_default`` (if it exists) by calling
`Env._merge_from_file()`.
- 4. Intelligently fill-in the ``in_server`` and ``log`` variables
+ 4. Intelligently fill-in the *in_server* and *log* variables
if they haven't already been set.
- 5. Merge in the internal defaults by calling `Env._merge()`. In
- normal circumstances, these internal defaults will simply be
- those specified in `constants.DEFAULT_CONFIG`.
+ 5. Merge-in the variables in ``defaults`` by calling `Env._merge()`.
+ In normal circumstances ``defaults`` will simply be those
+ specified in `constants.DEFAULT_CONFIG`.
- After this method is called, the all environment variables
- used by all the built-in plugins will be available. As such, this
- method should be called *before* any plugins are loaded.
+ After this method is called, all the environment variables used by all
+ the built-in plugins will be available. As such, this method should be
+ called *before* any plugins are loaded.
After this method has finished, the `Env` instance is still writable
so that 3rd-party plugins can set variables they may require as the
plugins are registered.
Also see `Env._finalize()`, the final method in the bootstrap sequence.
+
+ :param defaults: Internal defaults for all built-in variables.
"""
self.__doing('_finalize_core')
self.__do_if_not_done('_bootstrap')
@@ -464,6 +486,8 @@ class Env(object):
This method should be called after all plugins have been loaded and
after `plugable.API.finalize()` has been called.
+
+ :param lastchance: Any final variables to merge-in before locking.
"""
self.__doing('_finalize')
self.__do_if_not_done('_finalize_core')