Public API

The RawConditionalConfig class

The main component of CondConfigParser’s API is the RawConditionalConfig class:

class condconfigparser.RawConditionalConfig(input, extvars=())[source]

Bases: object

Class for dealing with files conforming to CondConfigParser syntax.

This class provides the main part of the API for using CondConfigParser.

__init__(input, extvars=())[source]

Initialize a RawConditionalConfig instance.

Parameters
  • input (file-like or string) – input stream or string (“configuration file”)

  • extvars (sequence or set) – indicates the external variables

Returns

a RawConditionalConfig instance

Read the configuration from input and check that the variables used therein can all be computed, directly or indirectly from the variables whose names are listed in extvars.

computeVars(context)[source]

Perform all variable assignments.

Parameters

context (dict) – mapping giving the value to use for every external variable. More precisely, for each name of an external variable, it gives the value for initialization of this variable before starting to perform variable assignments.

Returns

a new dictionary giving the value of every variable, be it external or not.

eval(context, *, flat=False)[source]

Compute the values of variables and evaluate predicates.

Parameters
  • context (dict) – mapping giving the value to use for every external variable. More precisely, for each name of an external variable, it gives the value for initialization of this variable before starting to perform variable assignments.

  • flat (bool) – if true, the second element of the return value will be a list of raw configuration lines; otherwise, it will be a list of lists of raw configuration lines, one for each section, starting with the default, unconditional section.

Returns

a tuple of the form (variables, lines) where:

  • variables is a new dictionary giving the value of every variable, be it external or not;

  • lines is a list as indicated above in the flat parameter description.

The following interactive session illustrates the effect of the flat argument:

>>> cfg = '''\
... { var1 = (extvar1 == "foobar") # parentheses only for clarity
...   var2 = var1 and "baz" in extvar2 }
...
... raw cfg default1
... raw cfg default2
...
... [ var2 or extvar1 == "quux" ]
... raw cfg a1
... raw cfg a2
... raw cfg a3
...
... [ var1 ]
... raw cfg b1
... raw cfg b2
...
... [ not var1 ]
... raw cfg c1
... raw cfg c2
... '''
>>> config = RawConditionalConfig(cfg, extvars=("extvar1", "extvar2"))
>>> context = {"extvar1": "quux",
...            "extvar2": [12, "abc", [False, "def"]]}
>>> [config.eval(context), config.eval(context, flat=True)] == \
... [({'extvar1': 'quux',
...    'extvar2': [12, 'abc', [False, 'def']],
...    'var1': False,
...    'var2': False},
...   [['raw cfg default1', 'raw cfg default2'],
...    ['raw cfg a1', 'raw cfg a2', 'raw cfg a3'],
...    ['raw cfg c1', 'raw cfg c2']]),
...  ({'extvar1': 'quux',
...    'extvar2': [12, 'abc', [False, 'def']],
...    'var1': False,
...    'var2': False},
...   ['raw cfg default1',
...    'raw cfg default2',
...    'raw cfg a1',
...    'raw cfg a2',
...    'raw cfg a3',
...    'raw cfg c1',
...    'raw cfg c2'])]
True
>>>

The default value for the flat parameter (False) preserves as much information as possible, allowing user applications to implement things such as conditional sections overriding the default, unconditional section.

Exceptions defined in CondConfigParser

The following exceptions are defined in the condconfigparser package for public use:

exception condconfigparser.error(message=None)[source]

Base class for exceptions in CondConfigParser.

exception condconfigparser.ParseError(pos, msg)[source]

Bases: condconfigparser.exceptions.error

Exception raised when CondConfigParser finds a syntax error in the stream to parse.

exception condconfigparser.InvalidUsage(message=None)[source]

Bases: condconfigparser.exceptions.error

Exception raised when CondConfigParser is used in an incorrect way.

exception condconfigparser.UndefinedVariablesInAssignmentOrPredicate(production, startToken, undef)[source]

Bases: condconfigparser.exceptions.error

Exception raised when an assignment or predicate uses a variable before it is defined.

This exception should not be seen by user code. Please report if you find this is not the case.

exception condconfigparser.UndefinedVariablesInAssignment(startToken, undef)[source]

Bases: condconfigparser.exceptions.UndefinedVariablesInAssignmentOrPredicate

Exception raised when an assignment uses a variable before it is defined.

exception condconfigparser.UndefinedVariablesInPredicate(startToken, undef)[source]

Bases: condconfigparser.exceptions.UndefinedVariablesInAssignmentOrPredicate

Exception raised when a predicate uses a variable before it is defined.

exception condconfigparser.InTestTypeError(inToken, origExc)[source]

Bases: condconfigparser.exceptions.error

Exception raised when an inTest can’t be eval()ed because of a type mismatch.