Home | Trees | Indices | Help |
---|
|
Based on the standard Python ConfigParser module, this module provides an enhanced configuration parser capabilities. Configuration is a drop-in replacement for ConfigParser.
A configuration file is broken into sections, and each section is introduced by a section name in brackets. For example:
[main] installationDirectory=/usr/local/foo programDirectory: /usr/local/foo/programs [search] searchCommand: find /usr/local/foo -type f -name "*.class" [display] searchFailedMessage=Search failed, sorry.
A section name can consist of alphabetics, numerics, underscores and periods. There can be any amount of whitespace before and after the brackets in a section name; the whitespace is ignored.
Each section contains zero or more variable settings.
- Similar to a Java Properties file, the variables are specified as name/value pairs, separated by an equal sign ("=") or a colon (":").
- Variable names are case-sensitive and may contain alphabetics, numerics, underscores and periods (".").
- Variable values may contain anything at all. Leading whitespace in the value is skipped. The way to include leading whitespace in a value is escape the whitespace characters with backslashes.
A variable value can interpolate the values of other variables, using a variable substitution syntax. The general form of a variable reference is ${section_name:var_name}.
- section_name is the name of the section containing the variable to substitute; if omitted, it defaults to the current section.
- var_name is the name of the variable to substitute.
You can also specify a default value for a variable, using this syntax:
${foo?default} ${section:foo?default}
That is, the sequence ?default after a variable name specifies the default value if the variable has no value. (Normally, if a variable has no value, it is replaced with an empty string.) Defaults can be useful, for instance, to allow overrides from the environment. The following example defines a log file directory that defaults to "/tmp", unless environment variable LOGDIR is set to a non-empty value:
logDirectory: ${env:LOGDIR?/var/log}
The section names "env", and "program" are reserved for special pseudosections.
The "env" pseudosection is used to interpolate values from the environment. On UNIX systems, for instance, ${env:HOME} substitutes home directory of the current user. On some versions of Windows, ${env:USERNAME} will substitute the name of the user.
Note: On UNIX systems, environment variable names are typically case-sensitive; for instance, ${env:USER} and ${env:user} refer to different environment variables. On Windows systems, environment variable names are typically case-insensitive; ${env:USERNAME} and ${env:username} are equivalent.
The "program" pseudosection is a placeholder for various special variables provided by the Configuration class. Those variables are:
A special include directive permits inline inclusion of another configuration file. The include directive takes two forms:
%include "path" %include "URL"
For example:
%include "/home/bmc/mytools/common.cfg" %include "http://configs.example.com/mytools/common.cfg"
The included file may contain any content that is valid for this parser. It may contain just variable definitions (i.e., the contents of a section, without the section header), or it may contain a complete configuration file, with individual sections.
Note: Attempting to include a file from itself, either directly or indirectly, will cause the parser to throw an exception.
You can use this class anywhere you would use the standard Python ConfigParser class. Thus, to change a piece of code to use enhanced configuration, you might change this:
import ConfigParser
config = ConfigParser.SafeConfigParser()
config.read(configPath)
to this:
from grizzled.config import Configuration config = Configuration() config.read(configPath)
Sometimes, however, you have to use an API that expects a path to a configuration file that can only be parsed with the (unenhanced) ConfigParser class. In that case, you simply use the preprocess() method:
import logging from grizzled import config logging.config.fileConfig(config.preprocess(pathToConfig))
That will preprocess the enhanced configuration file, producing a file that is suitable for parsing by the standard Python config module.
|
|||
NoOptionError A requested option was not found. |
|||
NoSectionError Raised when no section matches a requested option. |
|||
NoVariableError Thrown when a configuration file attempts to substitute a nonexistent variable, and the Configuration object was instantiated with strict_substitution set to True. |
|||
Configuration Configuration file parser. |
|||
_ConfigTemplate Subclass of string.Template that handles our configuration variable reference syntax. |
|||
_ConfigDict Dictionary that knows how to dereference variables within a parsed config. |
|
|||
string |
|
|
|||
log = logging.getLogger('grizzled.config')
|
|||
SECTION_OPTION_DELIM =
|
|||
SECTION_NAME_PATTERN =
|
|||
VARIABLE_NAME_PATTERN =
|
|||
VARIABLE_REF_PATTERN =
|
|||
SIMPLE_VARIABLE_REF_PATTERN =
|
|||
ENV_SECTION =
|
|||
PROGRAM_SECTION =
|
|||
__package__ = None hash(x) |
|
This function preprocesses a file or URL for a configuration file, processing all includes and substituting all variables. It writes a new configuration file to a temporary file (or specified output file). The new configuration file can be read by a standard ConfigParser object. Thus, this method is useful when you have an extended configuration file that must be passed to a function or object that can only read a standard ConfigParser file. For example, here's how you might use the Python logging API with an extended configuration file: from grizzled.config import Configuration import logging logging.config.fileConfig(Configuration.preprocess('/path/to/config')
|
|
VARIABLE_REF_PATTERN
|
SIMPLE_VARIABLE_REF_PATTERN
|
Home | Trees | Indices | Help |
---|
Generated by Epydoc 3.0.1 on Mon Mar 14 15:21:05 2016 | http://epydoc.sourceforge.net |