Class Section

helper for pickle

Overrides: object.__reduce__

(inherited documentation)

* parent is the section above * depth is the depth level of this section * main is the main ConfigObj * indict is a dictionary to initialise the section with

Returns:

new empty dictionary

Overrides: object.__init__

Fetch the item and do string interpolation.

Overrides: dict.__getitem__

Correctly set a value.

Making dictionary values Section instances. (We have to special case 'Section' instances - which are also dicts)

Keys must be strings. Values need only be strings (or lists of strings) if ``main.stringify`` is set.

``unrepr`` must be set when setting a value to a dictionary, without creating a new sub-section.

Overrides: dict.__setitem__

Remove items from the sequence when deleting.

Overrides: dict.__delitem__

A version of ``get`` that doesn't bypass string interpolation.

Returns: D[k] if k in D, else d

Overrides: dict.get

A version of update that uses our ``__setitem__``.

Returns: None

Overrides: dict.update

'D.pop(k[,d]) -> v, remove specified key and return the corresponding value. If key is not found, d is returned if given, otherwise KeyError is raised'

Returns: v, remove specified key and return the corresponding value

Overrides: dict.pop

Pops the first (key,val)

Returns: (k, v), remove and return some (key, value) pair as a

Overrides: dict.popitem

A version of clear that also affects scalars/sections
Also clears comments and configspec.

Leaves other attributes alone :
    depth/main/parent are not affected

Returns: None

Overrides: dict.clear

A version of setdefault that sets sequence if appropriate.

Returns: D.get(k,d), also set D[k]=d if k not in D

Overrides: dict.setdefault

Returns: list of D's (key, value) pairs, as 2-tuples

Overrides: dict.items

Returns: list of D's keys

Overrides: dict.keys

Returns: list of D's values

Overrides: dict.values

Returns: an iterator over the (key, value) items of D

Overrides: dict.iteritems

iter(x)

Returns: an iterator over the keys of D

Overrides: dict.iterkeys

iter(x)

Returns: an iterator over the keys of D

Overrides: dict.__iter__

Returns: an iterator over the values of D

Overrides: dict.itervalues

str(x)

Overrides: object.__repr__

str(x)

Overrides: object.__str__

Return a deepcopy of self as a dictionary.

All members that are ``Section`` instances are recursively turned to ordinary dictionaries - by calling their ``dict`` method.

>>> n = a.dict()
>>> n == a
1
>>> n is a
0

A recursive update - useful for merging config files.

>>> a = '''[section1]
...     option1 = True
...     [[subsection]]
...     more_options = False
...     # end of file'''.splitlines()
>>> b = '''# File is user.ini
...     [section1]
...     option1 = False
...     # end of file'''.splitlines()
>>> c1 = ConfigObj(b)
>>> c2 = ConfigObj(a)
>>> c2.merge(c1)
>>> c2
ConfigObj({'section1': {'option1': 'False', 'subsection': {'more_options': 'False'}}})

Change a keyname to another, without changing position in sequence.

Implemented so that transformations can be made on keys, as well as on values. (used by encode and decode)

Also renames comments.

Walk every member and call a function on the keyword and value.

Return a dictionary of the return values

If the function raises an exception, raise the errror
unless ``raise_errors=False``, in which case set the return value to
``False``.

Any unrecognised keyword arguments you pass to walk, will be pased on
to the function you pass in.

Note: if ``call_on_sections`` is ``True`` then - on encountering a
subsection, *first* the function is called for the *whole* subsection,
and then recurses into it's members. This means your function must be
able to handle strings, dictionaries and lists. This allows you
to change the key of subsections as well as for ordinary members. The
return value when called on the whole subsection has to be discarded.

See  the encode and decode methods for examples, including functions.

.. admonition:: caution

    You can use ``walk`` to transform the names of members of a section
    but you mustn't add or delete members.

>>> config = '''[XXXXsection]
... XXXXkey = XXXXvalue'''.splitlines()
>>> cfg = ConfigObj(config)
>>> cfg
ConfigObj({'XXXXsection': {'XXXXkey': 'XXXXvalue'}})
>>> def transform(section, key):
...     val = section[key]
...     newkey = key.replace('XXXX', 'CLIENT1')
...     section.rename(key, newkey)
...     if isinstance(val, (tuple, list, dict)):
...         pass
...     else:
...         val = val.replace('XXXX', 'CLIENT1')
...         section[newkey] = val
>>> cfg.walk(transform, call_on_sections=True)
{'CLIENT1section': {'CLIENT1key': None}}
>>> cfg
ConfigObj({'CLIENT1section': {'CLIENT1key': 'CLIENT1value'}})

Accepts a key as input. The corresponding value must be a string or the objects (``True`` or 1) or (``False`` or 0). We allow 0 and 1 to retain compatibility with Python 2.2.

If the string is one of ``True``, ``On``, ``Yes``, or ``1`` it returns ``True``.

If the string is one of ``False``, ``Off``, ``No``, or ``0`` it returns ``False``.

``as_bool`` is not case sensitive.

Any other input will raise a ``ValueError``.

>>> a = ConfigObj()
>>> a['a'] = 'fish'
>>> a.as_bool('a')
Traceback (most recent call last):
ValueError: Value "fish" is neither True nor False
>>> a['b'] = 'True'
>>> a.as_bool('b')
1
>>> a['b'] = 'off'
>>> a.as_bool('b')
0

A convenience method which coerces the specified value to an integer.

If the value is an invalid literal for ``int``, a ``ValueError`` will be raised.

>>> a = ConfigObj()
>>> a['a'] = 'fish'
>>> a.as_int('a')
Traceback (most recent call last):
ValueError: invalid literal for int() with base 10: 'fish'
>>> a['b'] = '1'
>>> a.as_int('b')
1
>>> a['b'] = '3.2'
>>> a.as_int('b')
Traceback (most recent call last):
ValueError: invalid literal for int() with base 10: '3.2'

A convenience method which coerces the specified value to a float.

If the value is an invalid literal for ``float``, a ``ValueError`` will be raised.

A convenience method which fetches the specified value, guaranteeing that it is a list.

>>> a = ConfigObj()
>>> a['a'] = 1
>>> a.as_list('a')
[1]
>>> a['a'] = (1,)
>>> a.as_list('a')
[1]
>>> a['a'] = [1]
>>> a.as_list('a')
[1]

Restore (and return) default value for the specified key.

This method will only work for a ConfigObj that was created with a configspec and has been validated.

If there is no default value for this key, ``KeyError`` is raised.

Recursively restore default values to all members that have them.

This method will only work for a ConfigObj that was created with a configspec and has been validated.

It doesn't delete or modify entries without default values.