configobj.ConfigObj

Module configobj :: Class ConfigObj |
[hide private]
[frames] | no frames]

# Class ConfigObj

source code

    object --+
             |
          dict --+
                 |
           Section --+
                     |
                    ConfigObj

An object to read, create, and write config files.

Instance Methods | [hide private]
    new empty dictionary
__init__(self, infile=None, options=None, configspec=None, encoding=None, interpolation=True, raise_errors=False, list_values=True, create_empty=False, file_error=False, stringify=True, indent_type=None, default_encoding=None, unrepr=False, write_empty_values=False, _inspec=False) Parse a config file or create a config file object. | source code
_load(self, infile, configspec) | source code
_initialise(self, options=None) | source code
__repr__(self) str(x) | source code
_handle_bom(self, infile) Handle any BOM, and decode if necessary. | source code
_a_to_u(self, aString) Decode ASCII strings to unicode if a self.encoding is specified. | source code
_decode(self, infile, encoding) Decode infile to unicode. | source code
_decode_element(self, line) Decode element to unicode if necessary. | source code
_str(self, value) Used by ``stringify`` within validate, to turn non-string values into strings. | source code
_parse(self, infile) Actually parse the config file. | source code
_match_depth(self, sect, depth) Given a section and a depth level, walk back through the sections parents to see if the depth level matches a previous section. | source code
_handle_error(self, text, ErrorClass, infile, cur_index) Handle an error according to the error settings. | source code
_unquote(self, value) Return an unquoted version of a value | source code
_quote(self, value, multiline=True) Return a safely quoted version of a value. | source code
_get_single_quote(self, value) | source code
_get_triple_quote(self, value) | source code
_handle_value(self, value) Given a value string, unquote, remove comment, handle lists. | source code
_multiline(self, value, infile, cur_index, maxline) Extract the value, where we are in a multiline situation. | source code
_handle_configspec(self, configspec) Parse the configspec. | source code
_set_configspec(self, section, copy) Called by validate. | source code
_write_line(self, indent_string, entry, this_entry, comment) Write an individual line, for the write method | source code
_write_marker(self, indent_string, depth, entry, comment) Write a section marker line | source code
_handle_comment(self, comment) Deal with a comment. | source code
write(self, outfile=None, section=None) Write the current ConfigObj as a file | source code
validate(self, validator, preserve_errors=False, copy=False, section=None) Test the ConfigObj against a configspec. | source code
reset(self) Clear ConfigObj instance and restore to 'freshly created' state. | source code
reload(self) Reload a ConfigObj from file. | source code
Inherited from `Section`: `__delitem__`, `__getitem__`, `__iter__`, `__reduce__`, `__setitem__`, `__setstate__`, `__str__`, `as_bool`, `as_float`, `as_int`, `as_list`, `clear`, `dict`, `get`, `items`, `iteritems`, `iterkeys`, `itervalues`, `keys`, `merge`, `pop`, `popitem`, `rename`, `restore_default`, `restore_defaults`, `setdefault`, `update`, `values`, `walk` Inherited from `Section` (private): `_interpolate` Inherited from `dict`: `__cmp__`, `__contains__`, `__eq__`, `__ge__`, `__getattribute__`, `__gt__`, `__le__`, `__len__`, `__lt__`, `__ne__`, `__new__`, `__sizeof__`, `copy`, `fromkeys`, `has_key`, `viewitems`, `viewkeys`, `viewvalues` Inherited from `object`: `__delattr__`, `__format__`, `__reduce_ex__`, `__setattr__`, `__subclasshook__`

Class Variables | [hide private]
| _keyword = `re.compile(r'`(?x)`^`(`\s`*``)``(``(?:`".`*?`"`)``|``(?:`\'.`*?`\'`)``|``(?:``[``^``...``
| _sectionmarker = `re.compile(r'`(?x)`^`(`\s`*``)``(``(?:`\[\s`*``)``+``)``(``(?:`"\s`*`\S`...``
| _valueexp = `re.compile(r'`(?x)`^`(?:``(?:``(``(?:``(?:``(?:`".`*?`"`)``|``(?:`\'.`*?`\`...``
| _listvalueexp = `re.compile(r'`(?x)``(``(?:`".`*?`"`)``|``(?:`\'.`*?`\'`)``|``(?:``[``^`\`...``
| _nolistvalue = `re.compile(r'`(?x)`^`(``(?:`".`*?`"`)``|``(?:`\'.`*?`\'`)``|``(?:``[``^`\`...``
| _single_line_single = `re.compile(r'^\'\'\'`(`.`*?``)`\'\'\'\s`*``(`#.`*``)``?`$')`
| _single_line_double = `re.compile(r'^"""`(`.`*?``)`"""\s`*``(`#.`*``)``?`$')`
| _multi_line_single = `re.compile(r'^`(`.`*?``)`\'\'\'\s`*``(`#.`*``)``?`$')`
| _multi_line_double = `re.compile(r'^`(`.`*?``)`"""\s`*``(`#.`*``)``?`$')`
| _triple_quote = ``{``'``"""``'``:` `(`re.compile(r'^"""`(`.`*?``)`"""\s`*``(`#.`*``)``?`$')`...``
| _bools = ``{``'``0``'``:` False`,` `'``1``'``:` True`,` `'``false``'``:` False`,` `'``no``'``:` False`,` `...``
Inherited from `dict`: `__hash__`

Properties | [hide private]
Inherited from `object`: `__class__`

Method Details | [hide private]

### __init__(self, infile=None, options=None, configspec=None, encoding=None, interpolation=True, raise_errors=False, list_values=True, create_empty=False, file_error=False, stringify=True, indent_type=None, default_encoding=None, unrepr=False, write_empty_values=False, _inspec=False) (Constructor) | source code
    Parse a config file or create a config file object.

    ``ConfigObj(infile=None, configspec=None, encoding=None,
                interpolation=True, raise_errors=False, list_values=True,
                create_empty=False, file_error=False, stringify=True,
                indent_type=None, default_encoding=None, unrepr=False,
                write_empty_values=False, _inspec=False)``
Returns:
    new empty dictionary
Overrides: object.__init__

### _initialise(self, options=None) | source code
Overrides: Section._initialise

### __repr__(self) (Representation operator) | source code
str(x) Overrides: object.__repr__ (inherited documentation)

### _handle_bom(self, infile) | source code
Handle any BOM, and decode if necessary. If an encoding is specified, that *must* be used - but the BOM should still be removed (and the BOM attribute set). (If the encoding is wrongly specified, then a BOM for an alternative encoding won't be discovered or removed.) If an encoding is not specified, UTF8 or UTF16 BOM will be detected and removed. The BOM attribute will be set. UTF16 will be decoded to unicode. NOTE: This method must not be called with an empty ``infile``. Specifying the *wrong* encoding is likely to cause a ``UnicodeDecodeError``. ``infile`` must always be returned as a list of lines, but may be passed in as a single string.

### _decode(self, infile, encoding) | source code
Decode infile to unicode. Using the specified encoding. if is a string, it also needs converting to a list.

### _match_depth(self, sect, depth) | source code
Given a section and a depth level, walk back through the sections parents to see if the depth level matches a previous section. Return a reference to the right section, or raise a SyntaxError.

### _handle_error(self, text, ErrorClass, infile, cur_index) | source code
Handle an error according to the error settings. Either raise the error or store it. The error will have occured at ``cur_index``

### _quote(self, value, multiline=True) | source code
Return a safely quoted version of a value. Raise a ConfigObjError if the value cannot be safely quoted. If multiline is ``True`` (default) then use triple quotes if necessary. * Don't quote values that don't need it. * Recursively quote members of a list and return a comma joined list. * Multiline is ``False`` for lists. * Obey list syntax for empty and single member lists. If ``list_values=False`` then the value is only quoted if it contains a ``\n`` (is multiline) or '#'. If ``write_empty_values`` is set, and the value is an empty string, it won't be quoted.

### _handle_value(self, value) | source code
Given a value string, unquote, remove comment, handle lists. (including empty and single member lists)

### _set_configspec(self, section, copy) | source code
Called by validate. Handles setting the configspec on subsections including sections to be validated by __many__

### write(self, outfile=None, section=None) | source code
Write the current ConfigObj as a file tekNico: FIXME: use StringIO instead of real files
    >>> filename = a.filename
    >>> a.filename = 'test.ini'
    >>> a.write()
    >>> a.filename = filename
    >>> a == ConfigObj('test.ini', raise_errors=True)
    1
    >>> import os
    >>> os.remove('test.ini')

### validate(self, validator, preserve_errors=False, copy=False, section=None) | source code
Test the ConfigObj against a configspec. It uses the ``validator`` object from *validate.py*. To run ``validate`` on the current ConfigObj, call: :
       test = config.validate(validator)
(Normally having previously passed in the configspec when the ConfigObj was created - you can dynamically assign a dictionary of checks to the ``configspec`` attribute of a section though). It returns ``True`` if everything passes, or a dictionary of pass/fails (True/False). If every member of a subsection passes, it will just have the value ``True``. (It also returns ``False`` if all members fail). In addition, it converts the values from strings to their native types if their checks pass (and ``stringify`` is set). If ``preserve_errors`` is ``True`` (``False`` is default) then instead of a marking a fail with a ``False``, it will preserve the actual exception object. This can contain info about the reason for failure. For example the ``VdtValueTooSmallError`` indicates that the value supplied was too small. If a value (or section) is missing it will still be marked as ``False``. You must have the validate module to use ``preserve_errors=True``. You can then use the ``flatten_errors`` function to turn your nested results dictionary into a flattened list of failures - useful for displaying meaningful error messages.

### reload(self) | source code
Reload a ConfigObj from file. This method raises a ``ReloadError`` if the ConfigObj doesn't have a filename attribute pointing to a file.

Class Variable Details | [hide private]

  ### _keyword Value:
      re.compile(r'(?x)^(\s*)((?:".*?")|(?:\'.*?\')|(?:[^\'"=].*?))\s*=\s*(.
      *)$')

  ### _sectionmarker Value:
      re.compile(r'(?x)^(\s*)((?:\[\s*)+)((?:"\s*\S.*?\s*")|(?:\'\s*\S.*?\s*
      \')|(?:[^\'"\s].*?))((?:\s*\])+)\s*(#.*)?$')

  ### _valueexp Value:
      re.compile(r'(?x)^(?:(?:((?:(?:(?:".*?")|(?:\'.*?\')|(?:[^\'",#][^,#]*
      ?))\s*,\s*)*)((?:".*?")|(?:\'.*?\')|(?:[^\'",#\s][^,]*?)|(?:(?<!,)))?)
      |(,))\s*(#.*)?$')

  ### _listvalueexp Value:
      re.compile(r'(?x)((?:".*?")|(?:\'.*?\')|(?:[^\'",#]?.*?))\s*,\s*')

  ### _nolistvalue Value:
      re.compile(r'(?x)^((?:".*?")|(?:\'.*?\')|(?:[^\'"#].*?)|(?:))\s*(#.*)?
      $')

  ### _triple_quote Value:
      {'"""': (re.compile(r'^"""(.*?)"""\s*(#.*)?$'),
               re.compile(r'^(.*?)"""\s*(#.*)?$')),
       '\'\'\'': (re.compile(r'^\'\'\'(.*?)\'\'\'\s*(#.*)?$'),
                  re.compile(r'^(.*?)\'\'\'\s*(#.*)?$'))}

  ### _bools Value:
      {'0': False,
       '1': True,
       'false': False,
       'no': False,
       'off': False,
       'on': True,
       'true': True,
       'yes': True}