configobj.py

Go to the documentation of this file.

# configobj.py
# A config file reader/writer that supports nested sections in config files.
# Copyright (C) 2005-2014:
# (name) : (email)
# Michael Foord: fuzzyman AT voidspace DOT org DOT uk
# Nicola Larosa: nico AT tekNico DOT net
# Rob Dennis: rdennis AT gmail DOT com
# Eli Courtwright: eli AT courtwright DOT org
 
# This software is licensed under the terms of the BSD license.
# http://opensource.org/licenses/BSD-3-Clause
 
# ConfigObj 5 - main repository for documentation and issue tracking:
# https://github.com/DiffSK/configobj
 
import os
import re
import sys
from codecs import BOM_UTF8, BOM_UTF16, BOM_UTF16_BE, BOM_UTF16_LE
 
import six
 
# imported lazily to avoid startup performance hit if it isn't used
compiler = None
 
# A dictionary mapping BOM to
# the encoding to decode with, and what to set the
# encoding attribute to.
BOMS = {
    BOM_UTF8: ('utf_8', None),
    BOM_UTF16_BE: ('utf16_be', 'utf_16'),
    BOM_UTF16_LE: ('utf16_le', 'utf_16'),
    BOM_UTF16: ('utf_16', 'utf_16'),
    }
# All legal variants of the BOM codecs.
# TODO: the list of aliases is not meant to be exhaustive, is there a
#   better way ?
BOM_LIST = {
    'utf_16': 'utf_16',
    'u16': 'utf_16',
    'utf16': 'utf_16',
    'utf-16': 'utf_16',
    'utf16_be': 'utf16_be',
    'utf_16_be': 'utf16_be',
    'utf-16be': 'utf16_be',
    'utf16_le': 'utf16_le',
    'utf_16_le': 'utf16_le',
    'utf-16le': 'utf16_le',
    'utf_8': 'utf_8',
    'u8': 'utf_8',
    'utf': 'utf_8',
    'utf8': 'utf_8',
    'utf-8': 'utf_8',
    }
 
# Map of encodings to the BOM to write.
BOM_SET = {
    'utf_8': BOM_UTF8,
    'utf_16': BOM_UTF16,
    'utf16_be': BOM_UTF16_BE,
    'utf16_le': BOM_UTF16_LE,
    None: BOM_UTF8
    }
 
 
def match_utf8(encoding):
    return BOM_LIST.get(encoding.lower()) == 'utf_8'
 
 
# Quote strings used for writing values
squot = "'%s'"
dquot = '"%s"'
noquot = "%s"
wspace_plus = ' \r\n\v\t\'"'
tsquot = '"""%s"""'
tdquot = "'''%s'''"
 
# Sentinel for use in getattr calls to replace hasattr
MISSING = object()
 
__all__ = (
    'DEFAULT_INDENT_TYPE',
    'DEFAULT_INTERPOLATION',
    'ConfigObjError',
    'NestingError',
    'ParseError',
    'DuplicateError',
    'ConfigspecError',
    'ConfigObj',
    'SimpleVal',
    'InterpolationError',
    'InterpolationLoopError',
    'MissingInterpolationOption',
    'RepeatSectionError',
    'ReloadError',
    'UnreprError',
    'UnknownType',
    'flatten_errors',
    'get_extra_values'
)
 
DEFAULT_INTERPOLATION = 'configparser'
DEFAULT_INDENT_TYPE = '    '
MAX_INTERPOL_DEPTH = 10
 
OPTION_DEFAULTS = {
    'interpolation': True,
    'raise_errors': False,
    'list_values': True,
    'create_empty': False,
    'file_error': False,
    'configspec': None,
    'stringify': True,
    # option may be set to one of ('', ' ', '\t')
    'indent_type': None,
    'encoding': None,
    'default_encoding': None,
    'unrepr': False,
    'write_empty_values': False,
}
 
# this could be replaced if six is used for compatibility, or there are no
# more assertions about items being a string
 
 
def getObj(s):
    global compiler
    if compiler is None:
        import compiler
    s = "a=" + s
    p = compiler.parse(s)
    return p.getChildren()[1].getChildren()[0].getChildren()[1]
 
 
class UnknownType(Exception):
    pass
 
 
class Builder():
 
    def build(self, o):
        if m is None:
            raise UnknownType(o.__class__.__name__)
        return m(o)
 
    def build_List(self, o):
        return list(map(self.buildbuild, o.getChildren()))
 
    def build_Const(self, o):
        return o.value
 
    def build_Dict(self, o):
        d = {}
        i = iter(map(self.buildbuild, o.getChildren()))
        for el in i:
            d[el] = next(i)
        return d
 
    def build_Tuple(self, o):
        return tuple(self.build_Listbuild_List(o))
 
    def build_Name(self, o):
        if o.name == 'None':
            return None
        if o.name == 'True':
            return True
        if o.name == 'False':
            return False
 
        # An undefined Name
        raise UnknownType('Undefined Name')
 
    def build_Add(self, o):
        real, imag = list(map(self.build_Constbuild_Const, o.getChildren()))
        try:
            real = float(real)
        except TypeError:
            raise UnknownType('Add')
        if not isinstance(imag, complex) or imag.real != 0.0:
            raise UnknownType('Add')
        return real+imag
 
    def build_Getattr(self, o):
        parent = self.buildbuild(o.expr)
        return getattr(parent, o.attrname)
 
    def build_UnarySub(self, o):
        return -self.build_Constbuild_Const(o.getChildren()[0])
 
    def build_UnaryAdd(self, o):
        return self.build_Constbuild_Const(o.getChildren()[0])
 
 
 
_builder = Builder()
 
 
def unrepr(s):
    if not s:
        return s
 
    # this is supposed to be safe
    import ast
    return ast.literal_eval(s)
 
 
 
class ConfigObjError(SyntaxError):
    def __init__(self, message='', line_number=None, line=''):
        self.lineline = line
        self.line_numberline_number = line_number
        SyntaxError.__init__(self, message)
 
 
 
class NestingError(ConfigObjError):
 
 
 
class ParseError(ConfigObjError):
 
 
 
class ReloadError(IOError):
    def __init__(self):
        IOError.__init__(self, 'reload failed, filename is not set.')
 
 
 
class DuplicateError(ConfigObjError):
 
 
 
class ConfigspecError(ConfigObjError):
 
 
 
class InterpolationError(ConfigObjError):
 
 
 
class InterpolationLoopError(InterpolationError):
 
    def __init__(self, option):
        InterpolationError.__init__(
            self,
            'interpolation loop detected in value "%s".' % option)
 
 
 
class RepeatSectionError(ConfigObjError):
 
 
 
class MissingInterpolationOption(InterpolationError):
    def __init__(self, option):
        msg = 'missing option "%s" in interpolation.' % option
        InterpolationError.__init__(self, msg)
 
 
 
class UnreprError(ConfigObjError):
 
 
 
 
class InterpolationEngine():
 
    # compiled regexp to use in self.interpolate()
    
    _KEYCRE = re.compile(r"%\‍(([^)]*)\‍)s")
    
    _cookie = '%'
 
    def __init__(self, section):
        # the Section instance that "owns" this engine
        self.sectionsection = section
 
 
    def interpolate(self, key, value):
        # short-cut
        if not self._cookie_cookie in value:
            return value
 
        
        def recursive_interpolate(key, value, section, backtrail):
            # Have we been here already?
            if (key, section.name) in backtrail:
                # Yes - infinite loop detected
                raise InterpolationLoopError(key)
            # Place a marker on our backtrail so we won't come back here again
            backtrail[(key, section.name)] = 1
 
            # Now start the actual work
            match = self._KEYCRE_KEYCRE.search(value)
            while match:
                # The actual parsing of the match is implementation-dependent,
                # so delegate to our helper function
                k, v, s = self._parse_match_parse_match(match)
                if k is None:
                    # That's the signal that no further interpolation is needed
                    replacement = v
                else:
                    # Further interpolation may be needed to obtain final value
                    replacement = recursive_interpolate(k, v, s, backtrail)
                # Replace the matched string with its final value
                start, end = match.span()
                value = ''.join((value[:start], replacement, value[end:]))
                new_search_start = start + len(replacement)
                # Pick up the next interpolation key, if any, for next time
                # through the while loop
                match = self._KEYCRE_KEYCRE.search(value, new_search_start)
 
            # Now safe to come back here again; remove marker from backtrail
            del backtrail[(key, section.name)]
 
            return value
 
        # Back in interpolate(), all we have to do is kick off the recursive
        # function with appropriate starting values
        value = recursive_interpolate(key, value, self.sectionsection, {})
        return value
 
 
    
    def _fetch(self, key):
        # switch off interpolation before we try and fetch anything !
        save_interp = self.sectionsection.main.interpolation
        self.sectionsection.main.interpolation = False
 
        # Start at section that "owns" this InterpolationEngine
        current_section = self.sectionsection
        while True:
            # try the current section first
            val = current_section.get(key)
            if val is not None and not isinstance(val, Section):
                break
            # try "DEFAULT" next
            val = current_section.get('DEFAULT', {}).get(key)
            if val is not None and not isinstance(val, Section):
                break
            # move up to parent and try again
            # top-level's parent is itself
            if current_section.parent is current_section:
                # reached top level, time to give up
                break
            current_section = current_section.parent
 
        # restore interpolation to previous value before returning
        self.sectionsection.main.interpolation = save_interp
        if val is None:
            raise MissingInterpolationOption(key)
        return val, current_section
 
 
    
    def _parse_match(self, match):
        raise NotImplementedError()
 
 
 
class ConfigParserInterpolation(InterpolationEngine):
    
    _cookie = '%'
    
    _KEYCRE = re.compile(r"%\‍(([^)]*)\‍)s")
 
    def _parse_match(self, match):
        key = match.group(1)
        value, section = self._fetch_fetch(key)
        return key, value, section
 
 
 
 
class TemplateInterpolation(InterpolationEngine):
    
    _cookie = '$'
    
    _delimiter = '$'
    
    _KEYCRE = re.compile(r"""
        \$(?:
          (?P<escaped>\$)              |   # Two $ signs
          (?P<named>[_a-z][_a-z0-9]*)  |   # $name format
          {(?P<braced>[^}]*)}              # ${name} format
        )
        """, re.IGNORECASE | re.VERBOSE)
 
    def _parse_match(self, match):
        # Valid name (in or out of braces): fetch value from section
        key = match.group('named') or match.group('braced')
        if key is not None:
            value, section = self._fetch_fetch(key)
            return key, value, section
        # Escaped delimiter (e.g., $$): return single delimiter
        if match.group('escaped') is not None:
            # Return None for key and section to indicate it's time to stop
            return None, self._delimiter_delimiter, None
        # Anything else: ignore completely, just return it unchanged
        return None, match.group(), None
 
 
interpolation_engines = {
    'configparser': ConfigParserInterpolation,
    'template': TemplateInterpolation,
}
 
 
def __newobj__(cls, *args):
    # Hack for pickle
    return cls.__new__(cls, *args)
 
 
 
class Section(dict):
 
 
    def __setstate__(self, state):
        dict.update(self, state[0])
        self.__dict__.update(state[1])
 
    def __reduce__(self):
        state = (dict(self), self.__dict__)
        return (__newobj__, (self.__class__,), state)
 
 
    
    def __init__(self, parent, depth, main, indict=None, name=None):
        if indict is None:
            indict = {}
        dict.__init__(self)
        # used for nesting level *and* interpolation
        self.parentparent = parent
        # used for the interpolation attribute
        self.mainmain = main
        # level of nesting depth of this Section
        self.depthdepth = depth
        # purely for information
        self.namename = name
        #
        self._initialise_initialise()
        # we do this explicitly so that __setitem__ is used properly
        # (rather than just passing to ``dict.__init__``)
        for entry, value in indict.items():
            self[entry] = value
 
 
    def _initialise(self):
        # the sequence of scalar values in this Section
        self.scalarsscalars = []
        # the sequence of sections in this Section
        self.sectionssections = []
        # for comments :-)
        self.commentscomments = {}
        self.inline_commentsinline_comments = {}
        # the configspec
        self.configspecconfigspec = None
        # for defaults
        self.defaultsdefaults = []
        self.default_valuesdefault_values = {}
        self.extra_valuesextra_values = []
        self._created_created = False
 
 
    def _interpolate(self, key, value):
        try:
            # do we already have an interpolation engine?
            engine = self._interpolation_engine_interpolation_engine
        except AttributeError:
            # not yet: first time running _interpolate(), so pick the engine
            name = self.mainmain.interpolation
            if name == True:  # note that "if name:" would be incorrect here
                # backwards-compatibility: interpolation=True means use default
                name = DEFAULT_INTERPOLATION
            name = name.lower()  # so that "Template", "template", etc. all work
            class_ = interpolation_engines.get(name, None)
            if class_ is None:
                # invalid value for self.main.interpolation
                self.mainmain.interpolation = False
                return value
            else:
                # save reference to engine so we don't have to do this again
                engine = self._interpolation_engine_interpolation_engine = class_(self)
        # let the engine do the actual work
        return engine.interpolate(key, value)
 
 
    
    def __getitem__(self, key):
        val = dict.__getitem__(self, key)
        if self.mainmain.interpolation:
            if isinstance(val, six.string_types):
                return self._interpolate_interpolate(key, val)
            if isinstance(val, list):
                def _check(entry):
                    if isinstance(entry, six.string_types):
                        return self._interpolate_interpolate(key, entry)
                    return entry
                new = [_check(entry) for entry in val]
                if new != val:
                    return new
        return val
 
 
    
    def __setitem__(self, key, value, unrepr=False):
        if not isinstance(key, six.string_types):
            raise ValueError('The key "%s" is not a string.' % key)
 
        # add the comment
        if key not in self.commentscomments:
            self.commentscomments[key] = []
            self.inline_commentsinline_comments[key] = ''
        # remove the entry from defaults
        if key in self.defaultsdefaults:
            self.defaultsdefaults.remove(key)
        #
        if isinstance(value, Section):
            if key not in self:
                self.sectionssections.append(key)
            dict.__setitem__(self, key, value)
        elif isinstance(value, dict) and not unrepr:
            # First create the new depth level,
            # then create the section
            if key not in self:
                self.sectionssections.append(key)
            new_depth = self.depthdepth + 1
            dict.__setitem__(
                self,
                key,
                Section(
                    self,
                    new_depth,
                    self.mainmain,
                    indict=value,
                    name=key))
        else:
            if key not in self:
                self.scalarsscalars.append(key)
            if not self.mainmain.stringify:
                if isinstance(value, six.string_types):
                    pass
                elif isinstance(value, (list, tuple)):
                    for entry in value:
                        if not isinstance(entry, six.string_types):
                            raise TypeError('Value is not a string "%s".' % entry)
                else:
                    raise TypeError('Value is not a string "%s".' % value)
            dict.__setitem__(self, key, value)
 
 
    
    def __delitem__(self, key):
        dict. __delitem__(self, key)
        if key in self.scalarsscalars:
            self.scalarsscalars.remove(key)
        else:
            self.sectionssections.remove(key)
        del self.commentscomments[key]
        del self.inline_commentsinline_comments[key]
 
 
    
    def get(self, key, default=None):
        try:
            return self[key]
        except KeyError:
            return default
 
 
    
    def update(self, indict):
        for entry in indict:
            self[entry] = indict[entry]
 
 
    
    def pop(self, key, default=MISSING):
        try:
            val = self[key]
        except KeyError:
            if default is MISSING:
                raise
            val = default
        else:
            del self[key]
        return val
 
 
    
    def popitem(self):
        sequence = (self.scalarsscalars + self.sectionssections)
        if not sequence:
            raise KeyError(": 'popitem(): dictionary is empty'")
        key = sequence[0]
        val =  self[key]
        del self[key]
        return key, val
 
 
    
    def clear(self):
        dict.clear(self)
        self.scalarsscalars = []
        self.sectionssections = []
        self.commentscomments = {}
        self.inline_commentsinline_comments = {}
        self.configspecconfigspec = None
        self.defaultsdefaults = []
        self.extra_valuesextra_values = []
 
 
    
    def setdefault(self, key, default=None):
        try:
            return self[key]
        except KeyError:
            self[key] = default
            return self[key]
 
 
    
    def items(self):
        return list(zip((self.scalarsscalars + self.sectionssections), list(self.valuesvalues())))
 
 
    
    def keys(self):
        return (self.scalarsscalars + self.sectionssections)
 
 
    
    def values(self):
        return [self[key] for key in (self.scalarsscalars + self.sectionssections)]
 
 
    
    def iteritems(self):
        return iter(list(self.itemsitems()))
 
 
    
    def iterkeys(self):
        return iter((self.scalarsscalars + self.sectionssections))
 
    __iter__ = iterkeys
 
 
    
    def itervalues(self):
        return iter(list(self.valuesvalues()))
 
 
    
    def __repr__(self):
        def _getval(key):
            try:
                return self[key]
            except MissingInterpolationOption:
                return dict.__getitem__(self, key)
        return '{%s}' % ', '.join([('%s: %s' % (repr(key), repr(_getval(key))))
            for key in (self.scalarsscalars + self.sectionssections)])
 
    __str__ = __repr__
    __str__.__doc__ = "x.__str__() <==> str(x)"
 
 
    # Extra methods - not in a normal dictionary
 
    
    def dict(self):
        newdict = {}
        for entry in self:
            this_entry = self[entry]
            if isinstance(this_entry, Section):
                this_entry = this_entry.dict()
            elif isinstance(this_entry, list):
                # create a copy rather than a reference
                this_entry = list(this_entry)
            elif isinstance(this_entry, tuple):
                # create a copy rather than a reference
                this_entry = tuple(this_entry)
            newdict[entry] = this_entry
        return newdict
 
 
    
    def merge(self, indict):
        for key, val in list(indict.items()):
            if (key in self and isinstance(self[key], dict) and
                                isinstance(val, dict)):
                self[key].merge(val)
            else:
                self[key] = val
 
 
    
    def rename(self, oldkey, newkey):
        if oldkey in self.scalarsscalars:
            the_list = self.scalarsscalars
        elif oldkey in self.sectionssections:
            the_list = self.sectionssections
        else:
            raise KeyError('Key "%s" not found.' % oldkey)
        pos = the_list.index(oldkey)
        #
        val = self[oldkey]
        dict.__delitem__(self, oldkey)
        dict.__setitem__(self, newkey, val)
        the_list.remove(oldkey)
        the_list.insert(pos, newkey)
        comm = self.commentscomments[oldkey]
        inline_comment = self.inline_commentsinline_comments[oldkey]
        del self.commentscomments[oldkey]
        del self.inline_commentsinline_comments[oldkey]
        self.commentscomments[newkey] = comm
        self.inline_commentsinline_comments[newkey] = inline_comment
 
 
    
    def walk(self, function, raise_errors=True,
            call_on_sections=False, **keywargs):
        out = {}
        # scalars first
        for i in range(len(self.scalarsscalars)):
            entry = self.scalarsscalars[i]
            try:
                val = function(self, entry, **keywargs)
                # bound again in case name has changed
                entry = self.scalarsscalars[i]
                out[entry] = val
            except Exception:
                if raise_errors:
                    raise
                else:
                    entry = self.scalarsscalars[i]
                    out[entry] = False
        # then sections
        for i in range(len(self.sectionssections)):
            entry = self.sectionssections[i]
            if call_on_sections:
                try:
                    function(self, entry, **keywargs)
                except Exception:
                    if raise_errors:
                        raise
                    else:
                        entry = self.sectionssections[i]
                        out[entry] = False
                # bound again in case name has changed
                entry = self.sectionssections[i]
            # previous result is discarded
            out[entry] = self[entry].walk(
                function,
                raise_errors=raise_errors,
                call_on_sections=call_on_sections,
                **keywargs)
        return out
 
 
    
    def as_bool(self, key):
        val = self[key]
        if val == True:
            return True
        elif val == False:
            return False
        else:
            try:
                if not isinstance(val, six.string_types):
                    # TODO: Why do we raise a KeyError here?
                    raise KeyError()
                else:
                    return self.mainmain._bools[val.lower()]
            except KeyError:
                raise ValueError('Value "%s" is neither True nor False' % val)
 
 
    
    def as_int(self, key):
        return int(self[key])
 
 
    
    def as_float(self, key):
        return float(self[key])
 
 
    
    def as_list(self, key):
        result = self[key]
        if isinstance(result, (tuple, list)):
            return list(result)
        return [result]
 
 
    
    def restore_default(self, key):
        default = self.default_valuesdefault_values[key]
        dict.__setitem__(self, key, default)
        if key not in self.defaultsdefaults:
            self.defaultsdefaults.append(key)
        return default
 
 
    
    def restore_defaults(self):
        for key in self.default_valuesdefault_values:
            self.restore_defaultrestore_default(key)
 
        for section in self.sectionssections:
            self[section].restore_defaults()
 
 
 
class ConfigObj(Section):
 
    
    _keyword = re.compile(r'''^ # line start
        (\s*)                   # indentation
        (                       # keyword
            (?:".*?")|          # double quotes
            (?:'.*?')|          # single quotes
            (?:[^'"=].*?)       # no quotes
        )
        \s*=\s*                 # divider
        (.*)                    # value (including list values and comments)
        $   # line end
        ''',
        re.VERBOSE)
 
    
    _sectionmarker = re.compile(r'''^
        (\s*)                     # 1: indentation
        ((?:\[\s*)+)              # 2: section marker open
        (                         # 3: section name open
            (?:"\s*\S.*?\s*")|    # at least one non-space with double quotes
            (?:'\s*\S.*?\s*')|    # at least one non-space with single quotes
            (?:[^'"\s].*?)        # at least one non-space unquoted
        )                         # section name close
        ((?:\s*\])+)              # 4: section marker close
        \s*(\#.*)?                # 5: optional comment
        $''',
        re.VERBOSE)
 
    # this regexp pulls list values out as a single string
    # or single values and comments
    # FIXME: this regex adds a '' to the end of comma terminated lists
    #   workaround in ``_handle_value``
    
    _valueexp = re.compile(r'''^
        (?:
            (?:
                (
                    (?:
                        (?:
                            (?:".*?")|              # double quotes
                            (?:'.*?')|              # single quotes
                            (?:[^'",\#][^,\#]*?)    # unquoted
                        )
                        \s*,\s*                     # comma
                    )*      # match all list items ending in a comma (if any)
                )
                (
                    (?:".*?")|                      # double quotes
                    (?:'.*?')|                      # single quotes
                    (?:[^'",\#\s][^,]*?)|           # unquoted
                    (?:(?<!,))                      # Empty value
                )?          # last item in a list - or string value
            )|
            (,)             # alternatively a single comma - empty list
        )
        \s*(\#.*)?          # optional comment
        $''',
        re.VERBOSE)
 
    # use findall to get the members of a list value
    
    _listvalueexp = re.compile(r'''
        (
            (?:".*?")|          # double quotes
            (?:'.*?')|          # single quotes
            (?:[^'",\#]?.*?)       # unquoted
        )
        \s*,\s*                 # comma
        ''',
        re.VERBOSE)
 
    # this regexp is used for the value
    # when lists are switched off
    
    _nolistvalue = re.compile(r'''^
        (
            (?:".*?")|          # double quotes
            (?:'.*?')|          # single quotes
            (?:[^'"\#].*?)|     # unquoted
            (?:)                # Empty value
        )
        \s*(\#.*)?              # optional comment
        $''',
        re.VERBOSE)
 
    # regexes for finding triple quoted values on one line
    
    _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 = {
        "'''": (_single_line_single, _multi_line_single),
        '"""': (_single_line_double, _multi_line_double),
    }
 
    # Used by the ``istrue`` Section method
    
    _bools = {
        'yes': True, 'no': False,
        'on': True, 'off': False,
        '1': True, '0': False,
        'true': True, 'false': False,
        }
 
 
    
    def __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):
        self._inspec_inspec = _inspec
        # init the superclass
        Section.__init__(self, self, 0, self)
 
        infile = infile or []
 
        
        _options = {'configspec': configspec,
                    'encoding': encoding, 'interpolation': interpolation,
                    'raise_errors': raise_errors, 'list_values': list_values,
                    'create_empty': create_empty, 'file_error': file_error,
                    'stringify': stringify, 'indent_type': indent_type,
                    'default_encoding': default_encoding, 'unrepr': unrepr,
                    'write_empty_values': write_empty_values}
 
        if options is None:
            options = _options
        else:
            import warnings
            warnings.warn('Passing in an options dictionary to ConfigObj() is '
                          'deprecated. Use **options instead.',
                          DeprecationWarning, stacklevel=2)
 
            # TODO: check the values too.
            for entry in options:
                if entry not in OPTION_DEFAULTS:
                    raise TypeError('Unrecognised option "%s".' % entry)
            for entry, value in list(OPTION_DEFAULTS.items()):
                if entry not in options:
                    options[entry] = value
                keyword_value = _options[entry]
                if value != keyword_value:
                    options[entry] = keyword_value
 
        # XXXX this ignores an explicit list_values = True in combination
        # with _inspec. The user should *never* do that anyway, but still...
        if _inspec:
            options['list_values'] = False
 
        self._initialise_initialise_initialise(options)
        configspec = options['configspec']
        self._original_configspec_original_configspec = configspec
        self._load_load(infile, configspec)
 
 
    def _load(self, infile, configspec):
        if isinstance(infile, six.string_types):
            self.filenamefilename = infile
            if os.path.isfile(infile):
                with open(infile, 'rb') as h:
                    content = h.readlines() or []
            elif self.file_errorfile_error:
                # raise an error if the file doesn't exist
                raise IOError('Config file not found: "%s".' % self.filenamefilename)
            else:
                # file doesn't already exist
                if self.create_emptycreate_empty:
                    # this is a good test that the filename specified
                    # isn't impossible - like on a non-existent device
                    with open(infile, 'w') as h:
                        h.write('')
                content = []
 
        elif isinstance(infile, (list, tuple)):
            content = list(infile)
 
        elif isinstance(infile, dict):
            # initialise self
            # the Section class handles creating subsections
            if isinstance(infile, ConfigObj):
                # get a copy of our ConfigObj
                def set_section(in_section, this_section):
                    for entry in in_section.scalars:
                        this_section[entry] = in_section[entry]
                    for section in in_section.sections:
                        this_section[section] = {}
                        set_section(in_section[section], this_section[section])
                set_section(infile, self)
 
            else:
                for entry in infile:
                    self[entry] = infile[entry]
            del self._errors_errors
 
            if configspec is not None:
                self._handle_configspec_handle_configspec(configspec)
            else:
                self.configspecconfigspecconfigspec = None
            return
 
        elif getattr(infile, 'read', MISSING) is not MISSING:
            # This supports file like objects
            content = infile.read() or []
            # needs splitting into lines - but needs doing *after* decoding
            # in case it's not an 8 bit encoding
        else:
            raise TypeError('infile must be a filename, file like object, or list of lines.')
 
        if content:
            # don't do it for the empty ConfigObj
            content = self._handle_bom_handle_bom(content)
            # infile is now *always* a list
            #
            # Set the newlines attribute (first line ending it finds)
            # and strip trailing '\n' or '\r' from lines
            for line in content:
                if (not line) or (line[-1] not in ('\r', '\n')):
                    continue
                for end in ('\r\n', '\n', '\r'):
                    if line.endswith(end):
                        self.newlinesnewlines = end
                        break
                break
 
        assert all(isinstance(line, six.string_types) for line in content), repr(content)
        content = [line.rstrip('\r\n') for line in content]
 
        self._parse_parse(content)
        # if we had any errors, now is the time to raise them
        if self._errors_errors:
            info = "at line %s." % self._errors_errors[0].line_number
            if len(self._errors_errors) > 1:
                msg = "Parsing failed with several errors.\nFirst error %s" % info
                error = ConfigObjError(msg)
            else:
                error = self._errors_errors[0]
            # set the errors attribute; it's a list of tuples:
            # (error_type, message, line_number)
            error.errors = self._errors_errors
            # set the config attribute
            error.config = self
            raise error
        # delete private attributes
        del self._errors_errors
 
        if configspec is None:
            self.configspecconfigspecconfigspec = None
        else:
            self._handle_configspec_handle_configspec(configspec)
 
 
    def _initialise(self, options=None):
        if options is None:
            options = OPTION_DEFAULTS
 
        # initialise a few variables
        self.filenamefilename = None
        self._errors_errors = []
        self.raise_errorsraise_errors = options['raise_errors']
        self.interpolationinterpolation = options['interpolation']
        self.list_valueslist_values = options['list_values']
        self.create_emptycreate_empty = options['create_empty']
        self.file_errorfile_error = options['file_error']
        self.stringifystringify = options['stringify']
        self.indent_typeindent_type = options['indent_type']
        self.encodingencoding = options['encoding']
        self.default_encodingdefault_encoding = options['default_encoding']
        self.BOMBOM = False
        self.newlinesnewlines = None
        self.write_empty_valueswrite_empty_values = options['write_empty_values']
        self.unreprunrepr = options['unrepr']
 
        self.initial_commentinitial_comment = []
        self.final_commentfinal_comment = []
        self.configspecconfigspecconfigspec = None
 
        if self._inspec_inspec:
            self.list_valueslist_values = False
 
        # Clear section attributes as well
        Section._initialise(self)
 
 
    def __repr__(self):
        def _getval(key):
            try:
                return self[key]
            except MissingInterpolationOption:
                return dict.__getitem__(self, key)
        return ('ConfigObj({%s})' %
                ', '.join([('%s: %s' % (repr(key), repr(_getval(key))))
                for key in (self.scalarsscalars + self.sectionssections)]))
 
 
    
    def _handle_bom(self, infile):
 
        if ((self.encodingencoding is not None) and
            (self.encodingencoding.lower() not in BOM_LIST)):
            # No need to check for a BOM
            # the encoding specified doesn't have one
            # just decode
            return self._decode_decode(infile, self.encodingencoding)
 
        if isinstance(infile, (list, tuple)):
            line = infile[0]
        else:
            line = infile
 
        if isinstance(line, six.text_type):
            # it's already decoded and there's no need to do anything
            # else, just use the _decode utility method to handle
            # listifying appropriately
            return self._decode_decode(infile, self.encodingencoding)
 
        if self.encodingencoding is not None:
            # encoding explicitly supplied
            # And it could have an associated BOM
            # TODO: if encoding is just UTF16 - we ought to check for both
            # TODO: big endian and little endian versions.
            enc = BOM_LIST[self.encodingencoding.lower()]
            if enc == 'utf_16':
                # For UTF16 we try big endian and little endian
                for BOM, (encoding, final_encoding) in list(BOMS.items()):
                    if not final_encoding:
                        # skip UTF8
                        continue
                    if infile.startswith(BOM):
                        
                        return self._decode_decode(infile, encoding)
 
                # If we get this far, will *probably* raise a DecodeError
                # As it doesn't appear to start with a BOM
                return self._decode_decode(infile, self.encodingencoding)
 
            # Must be UTF8
            BOM = BOM_SET[enc]
            if not line.startswith(BOM):
                return self._decode_decode(infile, self.encodingencoding)
 
            newline = line[len(BOM):]
 
            # BOM removed
            if isinstance(infile, (list, tuple)):
                infile[0] = newline
            else:
                infile = newline
            self.BOMBOM = True
            return self._decode_decode(infile, self.encodingencoding)
 
        # No encoding specified - so we need to check for UTF8/UTF16
        for BOM, (encoding, final_encoding) in list(BOMS.items()):
            if not isinstance(line, six.binary_type) or not line.startswith(BOM):
                # didn't specify a BOM, or it's not a bytestring
                continue
            else:
                # BOM discovered
                self.encodingencoding = final_encoding
                if not final_encoding:
                    self.BOMBOM = True
                    # UTF8
                    # remove BOM
                    newline = line[len(BOM):]
                    if isinstance(infile, (list, tuple)):
                        infile[0] = newline
                    else:
                        infile = newline
                    # UTF-8
                    if isinstance(infile, six.text_type):
                        return infile.splitlines(True)
                    elif isinstance(infile, six.binary_type):
                        return infile.decode('utf-8').splitlines(True)
                    else:
                        return self._decode_decode(infile, 'utf-8')
                # UTF16 - have to decode
                return self._decode_decode(infile, encoding)
 
 
        if six.PY2 and isinstance(line, str):
            # don't actually do any decoding, since we're on python 2 and
            # returning a bytestring is fine
            return self._decode_decode(infile, None)
        # No BOM discovered and no encoding specified, default to UTF-8
        if isinstance(infile, six.binary_type):
            return infile.decode('utf-8').splitlines(True)
        else:
            return self._decode_decode(infile, 'utf-8')
 
 
    
    def _a_to_u(self, aString):
        if isinstance(aString, six.binary_type) and self.encodingencoding:
            return aString.decode(self.encodingencoding)
        else:
            return aString
 
 
    
    def _decode(self, infile, encoding):
        if isinstance(infile, six.string_types):
            return infile.splitlines(True)
        if isinstance(infile, six.binary_type):
            # NOTE: Could raise a ``UnicodeDecodeError``
            if encoding:
                return infile.decode(encoding).splitlines(True)
            else:
                return infile.splitlines(True)
 
        if encoding:
            for i, line in enumerate(infile):
                if isinstance(line, six.binary_type):
                    # NOTE: The isinstance test here handles mixed lists of unicode/string
                    # NOTE: But the decode will break on any non-string values
                    # NOTE: Or could raise a ``UnicodeDecodeError``
                    infile[i] = line.decode(encoding)
        return infile
 
 
    
    def _decode_element(self, line):
        if isinstance(line, six.binary_type) and self.default_encodingdefault_encoding:
            return line.decode(self.default_encodingdefault_encoding)
        else:
            return line
 
 
    # TODO: this may need to be modified
    
    def _str(self, value):
        if not isinstance(value, six.string_types):
            # intentially 'str' because it's just whatever the "normal"
            # string type is for the python version we're dealing with
            return str(value)
        else:
            return value
 
 
    
    def _parse(self, infile):
        temp_list_values = self.list_valueslist_values
        if self.unreprunrepr:
            self.list_valueslist_values = False
 
        comment_list = []
        done_start = False
        this_section = self
        maxline = len(infile) - 1
        cur_index = -1
        reset_comment = False
 
        while cur_index < maxline:
            if reset_comment:
                comment_list = []
            cur_index += 1
            line = infile[cur_index]
            sline = line.strip()
            # do we have anything on the line ?
            if not sline or sline.startswith('#'):
                reset_comment = False
                comment_list.append(line)
                continue
 
            if not done_start:
                # preserve initial comment
                self.initial_commentinitial_comment = comment_list
                comment_list = []
                done_start = True
 
            reset_comment = True
            # first we check if it's a section marker
            mat = self._sectionmarker_sectionmarker.match(line)
            if mat is not None:
                # is a section line
                (indent, sect_open, sect_name, sect_close, comment) = mat.groups()
                if indent and (self.indent_typeindent_type is None):
                    self.indent_typeindent_type = indent
                cur_depth = sect_open.count('[')
                if cur_depth != sect_close.count(']'):
                    self._handle_error_handle_error("Cannot compute the section depth",
                                       NestingError, infile, cur_index)
                    continue
 
                if cur_depth < this_section.depth:
                    # the new section is dropping back to a previous level
                    try:
                        parent = self._match_depth_match_depth(this_section,
                                                   cur_depth).parent
                    except SyntaxError:
                        self._handle_error_handle_error("Cannot compute nesting level",
                                           NestingError, infile, cur_index)
                        continue
                elif cur_depth == this_section.depth:
                    # the new section is a sibling of the current section
                    parent = this_section.parent
                elif cur_depth == this_section.depth + 1:
                    # the new section is a child the current section
                    parent = this_section
                else:
                    self._handle_error_handle_error("Section too nested",
                                       NestingError, infile, cur_index)
                    continue
 
                sect_name = self._unquote_unquote(sect_name)
                if sect_name in parent:
                    self._handle_error_handle_error('Duplicate section name',
                                       DuplicateError, infile, cur_index)
                    continue
 
                # create the new section
                this_section = Section(
                    parent,
                    cur_depth,
                    self,
                    name=sect_name)
                parent[sect_name] = this_section
                parent.inline_comments[sect_name] = comment
                parent.comments[sect_name] = comment_list
                continue
            #
            # it's not a section marker,
            # so it should be a valid ``key = value`` line
            mat = self._keyword_keyword.match(line)
            if mat is None:
                self._handle_error_handle_error(
                    'Invalid line ({0!r}) (matched as neither section nor keyword)'.format(line),
                    ParseError, infile, cur_index)
            else:
                # is a keyword value
                # value will include any inline comment
                (indent, key, value) = mat.groups()
                if indent and (self.indent_typeindent_type is None):
                    self.indent_typeindent_type = indent
                # check for a multiline value
                if value[:3] in ['"""', "'''"]:
                    try:
                        value, comment, cur_index = self._multiline_multiline(
                            value, infile, cur_index, maxline)
                    except SyntaxError:
                        self._handle_error_handle_error(
                            'Parse error in multiline value',
                            ParseError, infile, cur_index)
                        continue
                    else:
                        if self.unreprunrepr:
                            comment = ''
                            try:
                                value = unrepr(value)
                            except Exception as e:
                                if type(e) == UnknownType:
                                    msg = 'Unknown name or type in value'
                                else:
                                    msg = 'Parse error from unrepr-ing multiline value'
                                self._handle_error_handle_error(msg, UnreprError, infile,
                                    cur_index)
                                continue
                else:
                    if self.unreprunrepr:
                        comment = ''
                        try:
                            value = unrepr(value)
                        except Exception as e:
                            if isinstance(e, UnknownType):
                                msg = 'Unknown name or type in value'
                            else:
                                msg = 'Parse error from unrepr-ing value'
                            self._handle_error_handle_error(msg, UnreprError, infile,
                                cur_index)
                            continue
                    else:
                        # extract comment and lists
                        try:
                            (value, comment) = self._handle_value_handle_value(value)
                        except SyntaxError:
                            self._handle_error_handle_error(
                                'Parse error in value',
                                ParseError, infile, cur_index)
                            continue
                #
                key = self._unquote_unquote(key)
                if key in this_section:
                    self._handle_error_handle_error(
                        'Duplicate keyword name',
                        DuplicateError, infile, cur_index)
                    continue
                # add the key.
                # we set unrepr because if we have got this far we will never
                # be creating a new section
                this_section.__setitem__(key, value, unrepr=True)
                this_section.inline_comments[key] = comment
                this_section.comments[key] = comment_list
                continue
        #
        if self.indent_typeindent_type is None:
            # no indentation used, set the type accordingly
            self.indent_typeindent_type = ''
 
        # preserve the final comment
        if not self and not self.initial_commentinitial_comment:
            self.initial_commentinitial_comment = comment_list
        elif not reset_comment:
            self.final_commentfinal_comment = comment_list
        self.list_valueslist_values = temp_list_values
 
 
    
    def _match_depth(self, sect, depth):
        while depth < sect.depth:
            if sect is sect.parent:
                # we've reached the top level already
                raise SyntaxError()
            sect = sect.parent
        if sect.depth == depth:
            return sect
        # shouldn't get here
        raise SyntaxError()
 
 
    
    def _handle_error(self, text, ErrorClass, infile, cur_index):
        line = infile[cur_index]
        cur_index += 1
        message = '{0} at line {1}.'.format(text, cur_index)
        error = ErrorClass(message, cur_index, line)
        if self.raise_errorsraise_errors:
            # raise the error - parsing stops here
            raise error
        # store the error
        # reraise when parsing has finished
        self._errors_errors.append(error)
 
 
    
    def _unquote(self, value):
        if not value:
            # should only happen during parsing of lists
            raise SyntaxError
        if (value[0] == value[-1]) and (value[0] in ('"', "'")):
            value = value[1:-1]
        return value
 
 
    
    def _quote(self, value, multiline=True):
        if multiline and self.write_empty_valueswrite_empty_values and value == '':
            # Only if multiline is set, so that it is used for values not
            # keys, and not values that are part of a list
            return ''
 
        if multiline and isinstance(value, (list, tuple)):
            if not value:
                return ','
            elif len(value) == 1:
                return self._quote_quote(value[0], multiline=False) + ','
            return ', '.join([self._quote_quote(val, multiline=False)
                for val in value])
        if not isinstance(value, six.string_types):
            if self.stringifystringify:
                # intentially 'str' because it's just whatever the "normal"
                # string type is for the python version we're dealing with
                value = str(value)
            else:
                raise TypeError('Value "%s" is not a string.' % value)
 
        if not value:
            return '""'
 
        no_lists_no_quotes = not self.list_valueslist_values and '\n' not in value and '#' not in value
        need_triple = multiline and ((("'" in value) and ('"' in value)) or ('\n' in value ))
        hash_triple_quote = multiline and not need_triple and ("'" in value) and ('"' in value) and ('#' in value)
        check_for_single = (no_lists_no_quotes or not need_triple) and not hash_triple_quote
 
        if check_for_single:
            if not self.list_valueslist_values:
                # we don't quote if ``list_values=False``
                quot = noquot
            # for normal values either single or double quotes will do
            elif '\n' in value:
                # will only happen if multiline is off - e.g. '\n' in key
                raise ConfigObjError('Value "%s" cannot be safely quoted.' % value)
            elif ((value[0] not in wspace_plus) and
                    (value[-1] not in wspace_plus) and
                    (',' not in value)):
                quot = noquot
            else:
                quot = self._get_single_quote_get_single_quote(value)
        else:
            # if value has '\n' or "'" *and* '"', it will need triple quotes
            quot = self._get_triple_quote_get_triple_quote(value)
 
        if quot == noquot and '#' in value and self.list_valueslist_values:
            quot = self._get_single_quote_get_single_quote(value)
 
        return quot % value
 
 
    def _get_single_quote(self, value):
        if ("'" in value) and ('"' in value):
            raise ConfigObjError('Value "%s" cannot be safely quoted.' % value)
        elif '"' in value:
            quot = squot
        else:
            quot = dquot
        return quot
 
 
    def _get_triple_quote(self, value):
        if (value.find('"""') != -1) and (value.find("'''") != -1):
            raise ConfigObjError('Value "%s" cannot be safely quoted.' % value)
        if value.find('"""') == -1:
            quot = tdquot
        else:
            quot = tsquot
        return quot
 
 
    
    def _handle_value(self, value):
        if self._inspec_inspec:
            # Parsing a configspec so don't handle comments
            return (value, '')
        # do we look for lists in values ?
        if not self.list_valueslist_values:
            mat = self._nolistvalue_nolistvalue.match(value)
            if mat is None:
                raise SyntaxError()
            # NOTE: we don't unquote here
            return mat.groups()
        #
        mat = self._valueexp_valueexp.match(value)
        if mat is None:
            # the value is badly constructed, probably badly quoted,
            # or an invalid list
            raise SyntaxError()
        (list_values, single, empty_list, comment) = mat.groups()
        if (list_values == '') and (single is None):
            # change this if you want to accept empty values
            raise SyntaxError()
        # NOTE: note there is no error handling from here if the regex
        # is wrong: then incorrect values will slip through
        if empty_list is not None:
            # the single comma - meaning an empty list
            return ([], comment)
        if single is not None:
            # handle empty values
            if list_values and not single:
                # FIXME: the '' is a workaround because our regex now matches
                #   '' at the end of a list if it has a trailing comma
                single = None
            else:
                single = single or '""'
                single = self._unquote_unquote(single)
        if list_values == '':
            # not a list value
            return (single, comment)
        the_list = self._listvalueexp_listvalueexp.findall(list_values)
        the_list = [self._unquote_unquote(val) for val in the_list]
        if single is not None:
            the_list += [single]
        return (the_list, comment)
 
 
    
    def _multiline(self, value, infile, cur_index, maxline):
        quot = value[:3]
        newvalue = value[3:]
        single_line = self._triple_quote_triple_quote[quot][0]
        multi_line = self._triple_quote_triple_quote[quot][1]
        mat = single_line.match(value)
        if mat is not None:
            retval = list(mat.groups())
            retval.append(cur_index)
            return retval
        elif newvalue.find(quot) != -1:
            # somehow the triple quote is missing
            raise SyntaxError()
        #
        while cur_index < maxline:
            cur_index += 1
            newvalue += '\n'
            line = infile[cur_index]
            if line.find(quot) == -1:
                newvalue += line
            else:
                # end of multiline, process it
                break
        else:
            # we've got to the end of the config, oops...
            raise SyntaxError()
        mat = multi_line.match(line)
        if mat is None:
            # a badly formed line
            raise SyntaxError()
        (value, comment) = mat.groups()
        return (newvalue + value, comment, cur_index)
 
 
    
    def _handle_configspec(self, configspec):
        # FIXME: Should we check that the configspec was created with the
        #        correct settings ? (i.e. ``list_values=False``)
        if not isinstance(configspec, ConfigObj):
            try:
                configspec = ConfigObj(configspec,
                                       raise_errors=True,
                                       file_error=True,
                                       _inspec=True)
            except ConfigObjError as e:
                # FIXME: Should these errors have a reference
                #        to the already parsed ConfigObj ?
                raise ConfigspecError('Parsing configspec failed: %s' % e)
            except IOError as e:
                raise IOError('Reading configspec failed: %s' % e)
 
        self.configspecconfigspecconfigspec = configspec
 
 
 
    
    def _set_configspec(self, section, copy):
        configspec = section.configspec
        many = configspec.get('__many__')
        if isinstance(many, dict):
            for entry in section.sections:
                if entry not in configspec:
                    section[entry].configspec = many
 
        for entry in configspec.sections:
            if entry == '__many__':
                continue
            if entry not in section:
                section[entry] = {}
                section[entry]._created = True
                if copy:
                    # copy comments
                    section.comments[entry] = configspec.comments.get(entry, [])
                    section.inline_comments[entry] = configspec.inline_comments.get(entry, '')
 
            # Could be a scalar when we expect a section
            if isinstance(section[entry], Section):
                section[entry].configspec = configspec[entry]
 
 
    
    def _write_line(self, indent_string, entry, this_entry, comment):
        # NOTE: the calls to self._quote here handles non-StringType values.
        if not self.unreprunrepr:
            val = self._decode_element_decode_element(self._quote_quote(this_entry))
        else:
            val = repr(this_entry)
        return '%s%s%s%s%s' % (indent_string,
                               self._decode_element_decode_element(self._quote_quote(entry, multiline=False)),
                               self._a_to_u_a_to_u(' = '),
                               val,
                               self._decode_element_decode_element(comment))
 
 
    
    def _write_marker(self, indent_string, depth, entry, comment):
        return '%s%s%s%s%s' % (indent_string,
                               self._a_to_u_a_to_u('[' * depth),
                               self._quote_quote(self._decode_element_decode_element(entry), multiline=False),
                               self._a_to_u_a_to_u(']' * depth),
                               self._decode_element_decode_element(comment))
 
 
    
    def _handle_comment(self, comment):
        if not comment:
            return ''
        start = self.indent_typeindent_type
        if not comment.startswith('#'):
            start += self._a_to_u_a_to_u(' # ')
        return (start + comment)
 
 
    # Public methods
 
    
    def write(self, outfile=None, section=None):
        if self.indent_typeindent_type is None:
            # this can be true if initialised from a dictionary
            self.indent_typeindent_type = DEFAULT_INDENT_TYPE
 
        out = []
        cs = self._a_to_u_a_to_u('#')
        csp = self._a_to_u_a_to_u('# ')
        if section is None:
            int_val = self.interpolationinterpolation
            self.interpolationinterpolation = False
            section = self
            for line in self.initial_commentinitial_comment:
                line = self._decode_element_decode_element(line)
                stripped_line = line.strip()
                if stripped_line and not stripped_line.startswith(cs):
                    line = csp + line
                out.append(line)
 
        indent_string = self.indent_typeindent_type * section.depth
        for entry in (section.scalars + section.sections):
            if entry in section.defaults:
                # don't write out default values
                continue
            for comment_line in section.comments[entry]:
                comment_line = self._decode_element_decode_element(comment_line.lstrip())
                if comment_line and not comment_line.startswith(cs):
                    comment_line = csp + comment_line
                out.append(indent_string + comment_line)
            this_entry = section[entry]
            comment = self._handle_comment_handle_comment(section.inline_comments[entry])
 
            if isinstance(this_entry, Section):
                # a section
                out.append(self._write_marker_write_marker(
                    indent_string,
                    this_entry.depth,
                    entry,
                    comment))
                out.extend(self.writewrite(section=this_entry))
            else:
                out.append(self._write_line_write_line(
                    indent_string,
                    entry,
                    this_entry,
                    comment))
 
        if section is self:
            for line in self.final_commentfinal_comment:
                line = self._decode_element_decode_element(line)
                stripped_line = line.strip()
                if stripped_line and not stripped_line.startswith(cs):
                    line = csp + line
                out.append(line)
            self.interpolationinterpolation = int_val
 
        if section is not self:
            return out
 
        if (self.filenamefilename is None) and (outfile is None):
            # output a list of lines
            # might need to encode
            # NOTE: This will *screw* UTF16, each line will start with the BOM
            if self.encodingencoding:
                out = [l.encode(self.encodingencoding) for l in out]
            if (self.BOMBOM and ((self.encodingencoding is None) or
                (BOM_LIST.get(self.encodingencoding.lower()) == 'utf_8'))):
                # Add the UTF8 BOM
                if not out:
                    out.append('')
                out[0] = BOM_UTF8 + out[0]
            return out
 
        # Turn the list to a string, joined with correct newlines
        newline = self.newlinesnewlines or os.linesep
        if (getattr(outfile, 'mode', None) is not None and outfile.mode == 'w'
            and sys.platform == 'win32' and newline == '\r\n'):
            # Windows specific hack to avoid writing '\r\r\n'
            newline = '\n'
        output = self._a_to_u_a_to_u(newline).join(out)
        if not output.endswith(newline):
            output += newline
 
        if isinstance(output, six.binary_type):
            output_bytes = output
        else:
            output_bytes = output.encode(self.encodingencoding or
                                         self.default_encodingdefault_encoding or
                                         'utf-8')  # DEBUG was 'ascii'
 
 
        if self.BOMBOM and ((self.encodingencoding is None) or match_utf8(self.encodingencoding)):
            # Add the UTF8 BOM
            output_bytes = BOM_UTF8 + output_bytes
 
        if outfile is not None:
            outfile.write(output_bytes)
        else:
            with open(self.filenamefilename, 'wb') as h:
                h.write(output_bytes)
 
    
    def validate(self, validator, preserve_errors=False, copy=False,
                 section=None):
        if section is None:
            if self.configspecconfigspecconfigspec is None:
                raise ValueError('No configspec supplied.')
            if preserve_errors:
                # We do this once to remove a top level dependency on the validate module
                # Which makes importing configobj faster
                from validate import VdtMissingValue
                self._vdtMissingValue_vdtMissingValue = VdtMissingValue
 
            section = self
 
            if copy:
                section.initial_comment = section.configspec.initial_comment
                section.final_comment = section.configspec.final_comment
                section.encoding = section.configspec.encoding
                section.BOM = section.configspec.BOM
                section.newlines = section.configspec.newlines
                section.indent_type = section.configspec.indent_type
 
        #
        # section.default_values.clear() #??
        configspec = section.configspec
        self._set_configspec_set_configspec(section, copy)
 
 
        def validate_entry(entry, spec, val, missing, ret_true, ret_false):
            section.default_values.pop(entry, None)
 
            try:
                section.default_values[entry] = validator.get_default_value(configspec[entry])
            except (KeyError, AttributeError, validator.baseErrorClass):
                # No default, bad default or validator has no 'get_default_value'
                # (e.g. SimpleVal)
                pass
 
            try:
                check = validator.check(spec,
                                        val,
                                        missing=missing
                                        )
            except validator.baseErrorClass as e:
                if not preserve_errors or isinstance(e, self._vdtMissingValue_vdtMissingValue):
                    out[entry] = False
                else:
                    # preserve the error
                    out[entry] = e
                    ret_false = False
                ret_true = False
            else:
                ret_false = False
                out[entry] = True
                if self.stringifystringify or missing:
                    # if we are doing type conversion
                    # or the value is a supplied default
                    if not self.stringifystringify:
                        if isinstance(check, (list, tuple)):
                            # preserve lists
                            check = [self._str_str(item) for item in check]
                        elif missing and check is None:
                            # convert the None from a default to a ''
                            check = ''
                        else:
                            check = self._str_str(check)
                    if (check != val) or missing:
                        section[entry] = check
                if not copy and missing and entry not in section.defaults:
                    section.defaults.append(entry)
            return ret_true, ret_false
 
        #
        out = {}
        ret_true = True
        ret_false = True
 
        unvalidated = [k for k in section.scalars if k not in configspec]
        incorrect_sections = [k for k in configspec.sections if k in section.scalars]
        incorrect_scalars = [k for k in configspec.scalars if k in section.sections]
 
        for entry in configspec.scalars:
            if entry in ('__many__', '___many___'):
                # reserved names
                continue
            if (not entry in section.scalars) or (entry in section.defaults):
                # missing entries
                # or entries from defaults
                missing = True
                val = None
                if copy and entry not in section.scalars:
                    # copy comments
                    section.comments[entry] = (
                        configspec.comments.get(entry, []))
                    section.inline_comments[entry] = (
                        configspec.inline_comments.get(entry, ''))
                #
            else:
                missing = False
                val = section[entry]
 
            ret_true, ret_false = validate_entry(entry, configspec[entry], val,
                                                 missing, ret_true, ret_false)
 
        many = None
        if '__many__' in configspec.scalars:
            many = configspec['__many__']
        elif '___many___' in configspec.scalars:
            many = configspec['___many___']
 
        if many is not None:
            for entry in unvalidated:
                val = section[entry]
                ret_true, ret_false = validate_entry(entry, many, val, False,
                                                     ret_true, ret_false)
            unvalidated = []
 
        for entry in incorrect_scalars:
            ret_true = False
            if not preserve_errors:
                out[entry] = False
            else:
                ret_false = False
                msg = 'Value %r was provided as a section' % entry
                out[entry] = validator.baseErrorClass(msg)
        for entry in incorrect_sections:
            ret_true = False
            if not preserve_errors:
                out[entry] = False
            else:
                ret_false = False
                msg = 'Section %r was provided as a single value' % entry
                out[entry] = validator.baseErrorClass(msg)
 
        # Missing sections will have been created as empty ones when the
        # configspec was read.
        for entry in section.sections:
            # FIXME: this means DEFAULT is not copied in copy mode
            if section is self and entry == 'DEFAULT':
                continue
            if section[entry].configspec is None:
                unvalidated.append(entry)
                continue
            if copy:
                section.comments[entry] = configspec.comments.get(entry, [])
                section.inline_comments[entry] = configspec.inline_comments.get(entry, '')
            check = self.validatevalidate(validator, preserve_errors=preserve_errors, copy=copy, section=section[entry])
            out[entry] = check
            if check == False:
                ret_true = False
            elif check == True:
                ret_false = False
            else:
                ret_true = False
 
        section.extra_values = unvalidated
        if preserve_errors and not section._created:
            # If the section wasn't created (i.e. it wasn't missing)
            # then we can't return False, we need to preserve errors
            ret_false = False
        #
        if ret_false and preserve_errors and out:
            # If we are preserving errors, but all
            # the failures are from missing sections / values
            # then we can return False. Otherwise there is a
            # real failure that we need to preserve.
            ret_false = not any(out.values())
        if ret_true:
            return True
        elif ret_false:
            return False
        return out
 
 
    
    def reset(self):
        self.clearclear()
        self._initialise_initialise_initialise()
        # FIXME: Should be done by '_initialise', but ConfigObj constructor (and reload)
        #        requires an empty dictionary
        self.configspecconfigspecconfigspec = None
        # Just to be sure ;-)
        self._original_configspec_original_configspec = None
 
 
    
    def reload(self):
        if not isinstance(self.filenamefilename, six.string_types):
            raise ReloadError()
 
        filename = self.filenamefilename
        current_options = {}
        for entry in OPTION_DEFAULTS:
            if entry == 'configspec':
                continue
            current_options[entry] = getattr(self, entry)
 
        configspec = self._original_configspec_original_configspec
        current_options['configspec'] = configspec
 
        self.clearclear()
        self._initialise_initialise_initialise(current_options)
        self._load_load(filename, configspec)
 
 
 
class SimpleVal():
 
    def __init__(self):
        self.baseErrorClassbaseErrorClass = ConfigObjError
 
    
    def check(self, check, member, missing=False):
        if missing:
            raise self.baseErrorClassbaseErrorClass()
        return member
 
 
 
def flatten_errors(cfg, res, levels=None, results=None):
    if levels is None:
        # first time called
        levels = []
        results = []
    if res == True:
        return sorted(results)
    if res == False or isinstance(res, Exception):
        results.append((levels[:], None, res))
        if levels:
            levels.pop()
        return sorted(results)
    for (key, val) in list(res.items()):
        if val == True:
            continue
        if isinstance(cfg.get(key), dict):
            # Go down one level
            levels.append(key)
            flatten_errors(cfg[key], val, levels, results)
            continue
        results.append((levels[:], key, val))
    #
    # Go up one level
    if levels:
        levels.pop()
    #
    return sorted(results)
 
 
 
def get_extra_values(conf, _prepend=()):
    out = []
 
    out.extend([(_prepend, name) for name in conf.extra_values])
    for name in conf.sections:
        if name not in conf.extra_values:
            out.extend(get_extra_values(conf[name], _prepend + (name,)))
    return out
 
 
"""*A programming language is a medium of expression.* - Paul Graham"""