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, **kwargs)
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_value(self, configspec, section)
Used to recursively set configspec values.
source code
 
_handle_repeat(self, section, configspec)
Dynamically assign configspec for repeated section.
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__, __setitem__, __str__, as_bool, as_float, as_int, clear, decode, dict, encode, get, istrue, 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__, __hash__, __le__, __len__, __lt__, __ne__, __new__, copy, fromkeys, has_key

Inherited from object: __delattr__, __reduce__, __reduce_ex__, __setattr__

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, ...
Properties [hide private]

Inherited from object: __class__

Method Details [hide private]

__init__(self, infile=None, options=None, **kwargs)
(Constructor)

source code 

Parse a config file or create a config file object.

``ConfigObj(infile=None, options=None, **kwargs)``

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 ``
`` (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)

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

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}