Module configobj :: Class ConfigObj

Class ConfigObj

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}

Class ConfigObj

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

_initialise(self, options=None)

__repr__(self) (Representation operator)

_handle_bom(self, infile)

_decode(self, infile, encoding)

_match_depth(self, sect, depth)

_handle_error(self, text, ErrorClass, infile, cur_index)

_quote(self, value, multiline=True)

_handle_value(self, value)

write(self, outfile=None, section=None)

validate(self, validator, preserve_errors=False, copy=False, section=None)

reload(self)

_keyword

_sectionmarker

_valueexp

_listvalueexp

_nolistvalue

_triple_quote

_bools

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

repr(self)
(Representation operator)