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, 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}

Class ConfigObj

__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)

_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)

_set_configspec(self, section, copy)

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, 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)

repr(self)
(Representation operator)