~ubuntu-branches/ubuntu/trusty/configobj/trusty : revision 10

1

# configobj.py

2

# A config file reader/writer that supports nested sections in config files.

3

4

# E-mail: fuzzyman AT voidspace DOT org DOT uk

5

# nico AT tekNico DOT net

6

7

# ConfigObj 4

8

# http://www.voidspace.org.uk/python/configobj.html

9

10

# Released subject to the BSD License

11

# Please see http://www.voidspace.org.uk/python/license.shtml

12

13

# Scripts maintained at http://www.voidspace.org.uk/python/index.shtml

14

# For information about bugfixes, updates and support, please join the

15

# ConfigObj mailing list:

16

# http://lists.sourceforge.net/lists/listinfo/configobj-develop

17

# Comments, suggestions and bug reports welcome.

18

19

from __future__ import generators

20

21

import os

22

import re

23

import sys

24

25

from codecs import BOM_UTF8, BOM_UTF16, BOM_UTF16_BE, BOM_UTF16_LE

26

27

28

# imported lazily to avoid startup performance hit if it isn't used

29

compiler = None

30

31

# A dictionary mapping BOM to

32

# the encoding to decode with, and what to set the

33

# encoding attribute to.

34

BOMS = {

35

BOM_UTF8: ('utf_8', None),

36

BOM_UTF16_BE: ('utf16_be', 'utf_16'),

37

BOM_UTF16_LE: ('utf16_le', 'utf_16'),

38

BOM_UTF16: ('utf_16', 'utf_16'),

39

}

40

# All legal variants of the BOM codecs.

41

# TODO: the list of aliases is not meant to be exhaustive, is there a

42

# better way ?

43

BOM_LIST = {

44

'utf_16': 'utf_16',

45

'u16': 'utf_16',

46

'utf16': 'utf_16',

47

'utf-16': 'utf_16',

48

'utf16_be': 'utf16_be',

49

'utf_16_be': 'utf16_be',

50

'utf-16be': 'utf16_be',

51

'utf16_le': 'utf16_le',

52

'utf_16_le': 'utf16_le',

53

'utf-16le': 'utf16_le',

54

'utf_8': 'utf_8',

55

'u8': 'utf_8',

56

'utf': 'utf_8',

57

'utf8': 'utf_8',

58

'utf-8': 'utf_8',

59

}

60

61

# Map of encodings to the BOM to write.

62

BOM_SET = {

63

'utf_8': BOM_UTF8,

64

'utf_16': BOM_UTF16,

65

'utf16_be': BOM_UTF16_BE,

66

'utf16_le': BOM_UTF16_LE,

67

None: BOM_UTF8

68

}

69

70

71

def match_utf8(encoding):

72

return BOM_LIST.get(encoding.lower()) == 'utf_8'

73

74

75

# Quote strings used for writing values

76

squot = "'%s'"

77

dquot = '"%s"'

78

noquot = "%s"

79

wspace_plus = ' \r\n\v\t\'"'

80

tsquot = '"""%s"""'

81

tdquot = "'''%s'''"

82

83

# Sentinel for use in getattr calls to replace hasattr

84

MISSING = object()

85

86

__version__ = '4.7.2'

87

88

try:

89

any

90

except NameError:

91

def any(iterable):

92

for entry in iterable:

93

if entry:

94

return True

95

return False

96

97

98

__all__ = (

99

'__version__',

100

'DEFAULT_INDENT_TYPE',

101

'DEFAULT_INTERPOLATION',

102

'ConfigObjError',

103

'NestingError',

104

'ParseError',

105

'DuplicateError',

106

'ConfigspecError',

107

'ConfigObj',

108

'SimpleVal',

109

'InterpolationError',

110

'InterpolationLoopError',

111

'MissingInterpolationOption',

112

'RepeatSectionError',

113

'ReloadError',

114

'UnreprError',

115

'UnknownType',

116

'flatten_errors',

117

'get_extra_values'

118

)

119

120

DEFAULT_INTERPOLATION = 'configparser'

121

DEFAULT_INDENT_TYPE = ' '

122

MAX_INTERPOL_DEPTH = 10

123

124

OPTION_DEFAULTS = {

125

'interpolation': True,

126

'raise_errors': False,

127

'list_values': True,

128

'create_empty': False,

129

'file_error': False,

130

'configspec': None,

131

'stringify': True,

132

# option may be set to one of ('', ' ', '\t')

133

'indent_type': None,

134

'encoding': None,

135

'default_encoding': None,

136

'unrepr': False,

137

'write_empty_values': False,

138

}

139

140

141

142

def getObj(s):

143

global compiler

144

if compiler is None:

145

import compiler

146

s = "a=" + s

147

p = compiler.parse(s)

148

return p.getChildren()[1].getChildren()[0].getChildren()[1]

149

150

151

class UnknownType(Exception):

152

pass

153

154

155

class Builder(object):

156

157

def build(self, o):

158

m = getattr(self, 'build_' + o.__class__.__name__, None)

159

if m is None:

160

raise UnknownType(o.__class__.__name__)

161

return m(o)

162

163

def build_List(self, o):

164

return map(self.build, o.getChildren())

165

166

def build_Const(self, o):

167

return o.value

168

169

def build_Dict(self, o):

170

d = {}

171

i = iter(map(self.build, o.getChildren()))

172

for el in i:

173

d[el] = i.next()

174

return d

175

176

def build_Tuple(self, o):

177

return tuple(self.build_List(o))

178

179

def build_Name(self, o):

180

if o.name == 'None':

181

return None

182

if o.name == 'True':

183

return True

184

if o.name == 'False':

185

return False

186

187

# An undefined Name

188

raise UnknownType('Undefined Name')

189

190

def build_Add(self, o):

191

real, imag = map(self.build_Const, o.getChildren())

192

try:

193

real = float(real)

194

except TypeError:

195

raise UnknownType('Add')

196

if not isinstance(imag, complex) or imag.real != 0.0:

197

raise UnknownType('Add')

198

return real+imag

199

200

def build_Getattr(self, o):

201

parent = self.build(o.expr)

202

return getattr(parent, o.attrname)

203

204

def build_UnarySub(self, o):

205

return -self.build_Const(o.getChildren()[0])

206

207

def build_UnaryAdd(self, o):

208

return self.build_Const(o.getChildren()[0])

209

210

211

_builder = Builder()

212

213

214

def unrepr(s):

215

if not s:

216

return s

217

return _builder.build(getObj(s))

218

219

220

221

class ConfigObjError(SyntaxError):

222

"""

223

This is the base class for all errors that ConfigObj raises.

224

It is a subclass of SyntaxError.

225

"""

226

def __init__(self, message='', line_number=None, line=''):

227

self.line = line

228

self.line_number = line_number

229

SyntaxError.__init__(self, message)

230

231

232

class NestingError(ConfigObjError):

233

"""

234

This error indicates a level of nesting that doesn't match.

235

"""

236

237

238

class ParseError(ConfigObjError):

239

"""

240

This error indicates that a line is badly written.

241

It is neither a valid ``key = value`` line,

242

nor a valid section marker line.

243

"""

244

245

246

class ReloadError(IOError):

247

"""

248

A 'reload' operation failed.

249

This exception is a subclass of ``IOError``.

250

"""

251

def __init__(self):

252

IOError.__init__(self, 'reload failed, filename is not set.')

253

254

255

class DuplicateError(ConfigObjError):

256

"""

257

The keyword or section specified already exists.

258

"""

259

260

261

class ConfigspecError(ConfigObjError):

262

"""

263

An error occured whilst parsing a configspec.

264

"""

265

266

267

class InterpolationError(ConfigObjError):

268

"""Base class for the two interpolation errors."""

269

270

271

class InterpolationLoopError(InterpolationError):

272

"""Maximum interpolation depth exceeded in string interpolation."""

273

274

def __init__(self, option):

275

InterpolationError.__init__(

276

self,

277

'interpolation loop detected in value "%s".' % option)

278

279

280

class RepeatSectionError(ConfigObjError):

281

"""

282

This error indicates additional sections in a section with a

283

``__many__`` (repeated) section.

284

"""

285

286

287

class MissingInterpolationOption(InterpolationError):

288

"""A value specified for interpolation was missing."""

289

def __init__(self, option):

290

msg = 'missing option "%s" in interpolation.' % option

291

InterpolationError.__init__(self, msg)

292

293

294

class UnreprError(ConfigObjError):

295

"""An error parsing in unrepr mode."""

296

297

298

299

class InterpolationEngine(object):

300

"""

301

A helper class to help perform string interpolation.

302

303

This class is an abstract base class; its descendants perform

304

the actual work.

305

"""

306

307

# compiled regexp to use in self.interpolate()

308

_KEYCRE = re.compile(r"%$([^)]*)$s")

309

_cookie = '%'

310

311

def __init__(self, section):

312

# the Section instance that "owns" this engine

313

self.section = section

314

315

316

def interpolate(self, key, value):

317

# short-cut

318

if not self._cookie in value:

319

return value

320

321

def recursive_interpolate(key, value, section, backtrail):

322

"""The function that does the actual work.

323

324

``value``: the string we're trying to interpolate.

325

``section``: the section in which that string was found

326

``backtrail``: a dict to keep track of where we've been,

327

to detect and prevent infinite recursion loops

328

329

This is similar to a depth-first-search algorithm.

330

"""

331

# Have we been here already?

332

if (key, section.name) in backtrail:

333

# Yes - infinite loop detected

334

raise InterpolationLoopError(key)

335

# Place a marker on our backtrail so we won't come back here again

336

backtrail[(key, section.name)] = 1

337

338

# Now start the actual work

339

match = self._KEYCRE.search(value)

340

while match:

341

# The actual parsing of the match is implementation-dependent,

342

# so delegate to our helper function

343

k, v, s = self._parse_match(match)

344

if k is None:

345

# That's the signal that no further interpolation is needed

346

replacement = v

347

else:

348

# Further interpolation may be needed to obtain final value

349

replacement = recursive_interpolate(k, v, s, backtrail)

350

# Replace the matched string with its final value

351

start, end = match.span()

352

value = ''.join((value[:start], replacement, value[end:]))

353

new_search_start = start + len(replacement)

354

# Pick up the next interpolation key, if any, for next time

355

# through the while loop

356

match = self._KEYCRE.search(value, new_search_start)

357

358

# Now safe to come back here again; remove marker from backtrail

359

del backtrail[(key, section.name)]

360

361

return value

362

363

# Back in interpolate(), all we have to do is kick off the recursive

364

# function with appropriate starting values

365

value = recursive_interpolate(key, value, self.section, {})

366

return value

367

368

369

def _fetch(self, key):

370

"""Helper function to fetch values from owning section.

371

372

Returns a 2-tuple: the value, and the section where it was found.

373

"""

374

# switch off interpolation before we try and fetch anything !

375

save_interp = self.section.main.interpolation

376

self.section.main.interpolation = False

377

378

# Start at section that "owns" this InterpolationEngine

379

current_section = self.section

380

while True:

381

# try the current section first

382

val = current_section.get(key)

383

if val is not None and not isinstance(val, Section):

384

break

385

# try "DEFAULT" next

386

val = current_section.get('DEFAULT', {}).get(key)

387

if val is not None and not isinstance(val, Section):

388

break

389

# move up to parent and try again

390

# top-level's parent is itself

391

if current_section.parent is current_section:

392

# reached top level, time to give up

393

break

394

current_section = current_section.parent

395

396

# restore interpolation to previous value before returning

397

self.section.main.interpolation = save_interp

398

if val is None:

399

raise MissingInterpolationOption(key)

400

return val, current_section

401

402

403

def _parse_match(self, match):

404

"""Implementation-dependent helper function.

405

406

Will be passed a match object corresponding to the interpolation

407

key we just found (e.g., "%(foo)s" or "$foo"). Should look up that

408

key in the appropriate config file section (using the ``_fetch()``

409

helper function) and return a 3-tuple: (key, value, section)

410

411

``key`` is the name of the key we're looking for

412

``value`` is the value found for that key

413

``section`` is a reference to the section where it was found

414

415

``key`` and ``section`` should be None if no further

416

interpolation should be performed on the resulting value

417

(e.g., if we interpolated "$$" and returned "$").

418

"""

419

raise NotImplementedError()

420

421

422

423

class ConfigParserInterpolation(InterpolationEngine):

424

"""Behaves like ConfigParser."""

425

_cookie = '%'

426

_KEYCRE = re.compile(r"%$([^)]*)$s")

427

428

def _parse_match(self, match):

429

key = match.group(1)

430

value, section = self._fetch(key)

431

return key, value, section

432

433

434

435

class TemplateInterpolation(InterpolationEngine):

436

"""Behaves like string.Template."""

437

_cookie = '$'

438

_delimiter = '$'

439

_KEYCRE = re.compile(r"""

440

\$(?:

441

(?P<escaped>\$) | # Two $ signs

442

(?P<named>[_a-z][_a-z0-9]*) | # $name format

443

{(?P<braced>[^}]*)} # ${name} format

444

)

445

""", re.IGNORECASE | re.VERBOSE)

446

447

def _parse_match(self, match):

448

# Valid name (in or out of braces): fetch value from section

449

key = match.group('named') or match.group('braced')

450

if key is not None:

451

value, section = self._fetch(key)

452

return key, value, section

453

# Escaped delimiter (e.g., $$): return single delimiter

454

if match.group('escaped') is not None:

455

# Return None for key and section to indicate it's time to stop

456

return None, self._delimiter, None

457

# Anything else: ignore completely, just return it unchanged

458

return None, match.group(), None

459

460

461

interpolation_engines = {

462

'configparser': ConfigParserInterpolation,

463

'template': TemplateInterpolation,

464

}

465

466

467

def __newobj__(cls, *args):

468

# Hack for pickle

469

return cls.__new__(cls, *args)

470

471

class Section(dict):

472

"""

473

A dictionary-like object that represents a section in a config file.

474

475

It does string interpolation if the 'interpolation' attribute

476

of the 'main' object is set to True.

477

478

Interpolation is tried first from this object, then from the 'DEFAULT'

479

section of this object, next from the parent and its 'DEFAULT' section,

480

and so on until the main object is reached.

481

482

A Section will behave like an ordered dictionary - following the

483

order of the ``scalars`` and ``sections`` attributes.

484

You can use this to change the order of members.

485

486

Iteration follows the order: scalars, then sections.

487

"""

488

489

490

def __setstate__(self, state):

491

dict.update(self, state[0])

492

self.__dict__.update(state[1])

493

494

def __reduce__(self):

495

state = (dict(self), self.__dict__)

496

return (__newobj__, (self.__class__,), state)

497

498

499

def __init__(self, parent, depth, main, indict=None, name=None):

500

"""

501

* parent is the section above

502

* depth is the depth level of this section

503

* main is the main ConfigObj

504

* indict is a dictionary to initialise the section with

505

"""

506

if indict is None:

507

indict = {}

508

dict.__init__(self)

509

# used for nesting level *and* interpolation

510

self.parent = parent

511

# used for the interpolation attribute

512

self.main = main

513

# level of nesting depth of this Section

514

self.depth = depth

515

# purely for information

516

self.name = name

517

#

518

self._initialise()

519

# we do this explicitly so that __setitem__ is used properly

520

# (rather than just passing to ``dict.__init__``)

521

for entry, value in indict.iteritems():

522

self[entry] = value

523

524

525

def _initialise(self):

526

# the sequence of scalar values in this Section

527

self.scalars = []

528

# the sequence of sections in this Section

529

self.sections = []

530

# for comments :-)

531

self.comments = {}

532

self.inline_comments = {}

533

# the configspec

534

self.configspec = None

535

# for defaults

536

self.defaults = []

537

self.default_values = {}

538

self.extra_values = []

539

self._created = False

540

541

542

def _interpolate(self, key, value):

543

try:

544

# do we already have an interpolation engine?

545

engine = self._interpolation_engine

546

except AttributeError:

547

# not yet: first time running _interpolate(), so pick the engine

548

name = self.main.interpolation

549

if name == True: # note that "if name:" would be incorrect here

550

# backwards-compatibility: interpolation=True means use default

551

name = DEFAULT_INTERPOLATION

552

name = name.lower() # so that "Template", "template", etc. all work

553

class_ = interpolation_engines.get(name, None)

554

if class_ is None:

555

# invalid value for self.main.interpolation

556

self.main.interpolation = False

557

return value

558

else:

559

# save reference to engine so we don't have to do this again

560

engine = self._interpolation_engine = class_(self)

561

# let the engine do the actual work

562

return engine.interpolate(key, value)

563

564

565

def __getitem__(self, key):

566

"""Fetch the item and do string interpolation."""

567

val = dict.__getitem__(self, key)

568

if self.main.interpolation:

569

if isinstance(val, basestring):

570

return self._interpolate(key, val)

571

if isinstance(val, list):

572

def _check(entry):

573

if isinstance(entry, basestring):

574

return self._interpolate(key, entry)

575

return entry

576

new = [_check(entry) for entry in val]

577

if new != val:

578

return new

579

return val

580

581

582

def __setitem__(self, key, value, unrepr=False):

583

"""

584

Correctly set a value.

585

586

Making dictionary values Section instances.

587

(We have to special case 'Section' instances - which are also dicts)

588

589

Keys must be strings.

590

Values need only be strings (or lists of strings) if

591

``main.stringify`` is set.

592

593

``unrepr`` must be set when setting a value to a dictionary, without

594

creating a new sub-section.

595

"""

596

if not isinstance(key, basestring):

597

raise ValueError('The key "%s" is not a string.' % key)

598

599

# add the comment

600

if key not in self.comments:

601

self.comments[key] = []

602

self.inline_comments[key] = ''

603

# remove the entry from defaults

604

if key in self.defaults:

605

self.defaults.remove(key)

606

#

607

if isinstance(value, Section):

608

if key not in self:

609

self.sections.append(key)

610

dict.__setitem__(self, key, value)

611

elif isinstance(value, dict) and not unrepr:

612

# First create the new depth level,

613

# then create the section

614

if key not in self:

615

self.sections.append(key)

616

new_depth = self.depth + 1

617

dict.__setitem__(

618

self,

619

key,

620

Section(

621

self,

622

new_depth,

623

self.main,

624

indict=value,

625

name=key))

626

else:

627

if key not in self:

628

self.scalars.append(key)

629

if not self.main.stringify:

630

if isinstance(value, basestring):

631

pass

632

elif isinstance(value, (list, tuple)):

633

for entry in value:

634

if not isinstance(entry, basestring):

635

raise TypeError('Value is not a string "%s".' % entry)

636

else:

637

raise TypeError('Value is not a string "%s".' % value)

638

dict.__setitem__(self, key, value)

639

640

641

def __delitem__(self, key):

642

"""Remove items from the sequence when deleting."""

643

dict. __delitem__(self, key)

644

if key in self.scalars:

645

self.scalars.remove(key)

646

else:

647

self.sections.remove(key)

648

del self.comments[key]

649

del self.inline_comments[key]

650

651

652

def get(self, key, default=None):

653

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

654

try:

655

return self[key]

656

except KeyError:

657

return default

658

659

660

def update(self, indict):

661

"""

662

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

663

"""

664

for entry in indict:

665

self[entry] = indict[entry]

666

667

668

def pop(self, key, default=MISSING):

669

"""

670

'D.pop(k[,d]) -> v, remove specified key and return the corresponding value.

671

If key is not found, d is returned if given, otherwise KeyError is raised'

672

"""

673

try:

674

val = self[key]

675

except KeyError:

676

if default is MISSING:

677

raise

678

val = default

679

else:

680

del self[key]

681

return val

682

683

684

def popitem(self):

685

"""Pops the first (key,val)"""

686

sequence = (self.scalars + self.sections)

687

if not sequence:

688

raise KeyError(": 'popitem(): dictionary is empty'")

689

key = sequence[0]

690

val = self[key]

691

del self[key]

692

return key, val

693

694

695

def clear(self):

696

"""

697

A version of clear that also affects scalars/sections

698

Also clears comments and configspec.

699

700

Leaves other attributes alone :

701

depth/main/parent are not affected

702

"""

703

dict.clear(self)

704

self.scalars = []

705

self.sections = []

706

self.comments = {}

707

self.inline_comments = {}

708

self.configspec = None

709

self.defaults = []

710

self.extra_values = []

711

712

713

def setdefault(self, key, default=None):

714

"""A version of setdefault that sets sequence if appropriate."""

715

try:

716

return self[key]

717

except KeyError:

718

self[key] = default

719

return self[key]

720

721

722

def items(self):

723

"""D.items() -> list of D's (key, value) pairs, as 2-tuples"""

724

return zip((self.scalars + self.sections), self.values())

725

726

727

def keys(self):

728

"""D.keys() -> list of D's keys"""

729

return (self.scalars + self.sections)

730

731

732

def values(self):

733

"""D.values() -> list of D's values"""

734

return [self[key] for key in (self.scalars + self.sections)]

735

736

737

def iteritems(self):

738

"""D.iteritems() -> an iterator over the (key, value) items of D"""

739

return iter(self.items())

740

741

742

def iterkeys(self):

743

"""D.iterkeys() -> an iterator over the keys of D"""

744

return iter((self.scalars + self.sections))

745

746

__iter__ = iterkeys

747

748

749

def itervalues(self):

750

"""D.itervalues() -> an iterator over the values of D"""

751

return iter(self.values())

752

753

754

def __repr__(self):

755

"""x.__repr__() <==> repr(x)"""

756

def _getval(key):

757

try:

758

return self[key]

759

except MissingInterpolationOption:

760

return dict.__getitem__(self, key)

761

return '{%s}' % ', '.join([('%s: %s' % (repr(key), repr(_getval(key))))

762

for key in (self.scalars + self.sections)])

763

764

__str__ = __repr__

765

__str__.__doc__ = "x.__str__() <==> str(x)"

766

767

768

# Extra methods - not in a normal dictionary

769

770

def dict(self):

771

"""

772

Return a deepcopy of self as a dictionary.

773

774

All members that are ``Section`` instances are recursively turned to

775

ordinary dictionaries - by calling their ``dict`` method.

776

777

>>> n = a.dict()

778

>>> n == a

779

1

780

>>> n is a

781

0

782

"""

783

newdict = {}

784

for entry in self:

785

this_entry = self[entry]

786

if isinstance(this_entry, Section):

787

this_entry = this_entry.dict()

788

elif isinstance(this_entry, list):

789

# create a copy rather than a reference

790

this_entry = list(this_entry)

791

elif isinstance(this_entry, tuple):

792

# create a copy rather than a reference

793

this_entry = tuple(this_entry)

794

newdict[entry] = this_entry

795

return newdict

796

797

798

def merge(self, indict):

799

"""

800

A recursive update - useful for merging config files.

801

802

>>> a = '''[section1]

803

... option1 = True

804

... [[subsection]]

805

... more_options = False

806

... # end of file'''.splitlines()

807

>>> b = '''# File is user.ini

808

... [section1]

809

... option1 = False

810

... # end of file'''.splitlines()

811

>>> c1 = ConfigObj(b)

812

>>> c2 = ConfigObj(a)

813

>>> c2.merge(c1)

814

>>> c2

815

ConfigObj({'section1': {'option1': 'False', 'subsection': {'more_options': 'False'}}})

816

"""

817

for key, val in indict.items():

818

if (key in self and isinstance(self[key], dict) and

819

isinstance(val, dict)):

820

self[key].merge(val)

821

else:

822

self[key] = val

823

824

825

def rename(self, oldkey, newkey):

826

"""

827

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

828

829

Implemented so that transformations can be made on keys,

830

as well as on values. (used by encode and decode)

831

832

Also renames comments.

833

"""

834

if oldkey in self.scalars:

835

the_list = self.scalars

836

elif oldkey in self.sections:

837

the_list = self.sections

838

else:

839

raise KeyError('Key "%s" not found.' % oldkey)

840

pos = the_list.index(oldkey)

841

#

842

val = self[oldkey]

843

dict.__delitem__(self, oldkey)

844

dict.__setitem__(self, newkey, val)

845

the_list.remove(oldkey)

846

the_list.insert(pos, newkey)

847

comm = self.comments[oldkey]

848

inline_comment = self.inline_comments[oldkey]

849

del self.comments[oldkey]

850

del self.inline_comments[oldkey]

851

self.comments[newkey] = comm

852

self.inline_comments[newkey] = inline_comment

853

854

855

def walk(self, function, raise_errors=True,

856

call_on_sections=False, **keywargs):

857

"""

858

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

859

860

Return a dictionary of the return values

861

862

If the function raises an exception, raise the errror

863

unless ``raise_errors=False``, in which case set the return value to

864

``False``.

865

866

Any unrecognised keyword arguments you pass to walk, will be pased on

867

to the function you pass in.

868

869

Note: if ``call_on_sections`` is ``True`` then - on encountering a

870

subsection, *first* the function is called for the *whole* subsection,

871

and then recurses into it's members. This means your function must be

872

able to handle strings, dictionaries and lists. This allows you

873

to change the key of subsections as well as for ordinary members. The

874

return value when called on the whole subsection has to be discarded.

875

876

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

877

878

.. admonition:: caution

879

880

You can use ``walk`` to transform the names of members of a section

881

but you mustn't add or delete members.

882

883

>>> config = '''[XXXXsection]

884

... XXXXkey = XXXXvalue'''.splitlines()

885

>>> cfg = ConfigObj(config)

886

>>> cfg

887

ConfigObj({'XXXXsection': {'XXXXkey': 'XXXXvalue'}})

888

>>> def transform(section, key):

889

... val = section[key]

890

... newkey = key.replace('XXXX', 'CLIENT1')

891

... section.rename(key, newkey)

892

... if isinstance(val, (tuple, list, dict)):

893

... pass

894

... else:

895

... val = val.replace('XXXX', 'CLIENT1')

896

... section[newkey] = val

897

>>> cfg.walk(transform, call_on_sections=True)

898

{'CLIENT1section': {'CLIENT1key': None}}

899

>>> cfg

900

ConfigObj({'CLIENT1section': {'CLIENT1key': 'CLIENT1value'}})

901

"""

902

out = {}

903

# scalars first

904

for i in range(len(self.scalars)):

905

entry = self.scalars[i]

906

try:

907

val = function(self, entry, **keywargs)

908

# bound again in case name has changed

909

entry = self.scalars[i]

910

out[entry] = val

911

except Exception:

912

if raise_errors:

913

raise

914

else:

915

entry = self.scalars[i]

916

out[entry] = False

917

# then sections

918

for i in range(len(self.sections)):

919

entry = self.sections[i]

920

if call_on_sections:

921

try:

922

function(self, entry, **keywargs)

923

except Exception:

924

if raise_errors:

925

raise

926

else:

927

entry = self.sections[i]

928

out[entry] = False

929

# bound again in case name has changed

930

entry = self.sections[i]

931

# previous result is discarded

932

out[entry] = self[entry].walk(

933

function,

934

raise_errors=raise_errors,

935

call_on_sections=call_on_sections,

936

**keywargs)

937

return out

938

939

940

def as_bool(self, key):

941

"""

942

Accepts a key as input. The corresponding value must be a string or

943

the objects (``True`` or 1) or (``False`` or 0). We allow 0 and 1 to

944

retain compatibility with Python 2.2.

945

946

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

947

``True``.

948

949

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

950

``False``.

951

952

``as_bool`` is not case sensitive.

953

954

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

955

956

>>> a = ConfigObj()

957

>>> a['a'] = 'fish'

958

>>> a.as_bool('a')

959

Traceback (most recent call last):

960

ValueError: Value "fish" is neither True nor False

961

>>> a['b'] = 'True'

962

>>> a.as_bool('b')

963

1

964

>>> a['b'] = 'off'

965

>>> a.as_bool('b')

966

0

967

"""

968

val = self[key]

969

if val == True:

970

return True

971

elif val == False:

972

return False

973

else:

974

try:

975

if not isinstance(val, basestring):

976

# TODO: Why do we raise a KeyError here?

977

raise KeyError()

978

else:

979

return self.main._bools[val.lower()]

980

except KeyError:

981

raise ValueError('Value "%s" is neither True nor False' % val)

982

983

984

def as_int(self, key):

985

"""

986

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

987

988

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

989

be raised.

990

991

>>> a = ConfigObj()

992

>>> a['a'] = 'fish'

993

>>> a.as_int('a')

994

Traceback (most recent call last):

995

ValueError: invalid literal for int() with base 10: 'fish'

996

>>> a['b'] = '1'

997

>>> a.as_int('b')

998

1

999

>>> a['b'] = '3.2'

1000

>>> a.as_int('b')

1001

Traceback (most recent call last):

1002

ValueError: invalid literal for int() with base 10: '3.2'

1003

"""

1004

return int(self[key])

1005

1006

1007

def as_float(self, key):

1008

"""

1009

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

1010

1011

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

1012

be raised.

1013

"""

1014

return float(self[key])

1015

1016

1017

def as_list(self, key):

1018

"""

1019

A convenience method which fetches the specified value, guaranteeing

1020

that it is a list.

1021

1022

>>> a = ConfigObj()

1023

>>> a['a'] = 1

1024

>>> a.as_list('a')

1025

[1]

1026

>>> a['a'] = (1,)

1027

>>> a.as_list('a')

1028

[1]

1029

>>> a['a'] = [1]

1030

>>> a.as_list('a')

1031

[1]

1032

"""

1033

result = self[key]

1034

if isinstance(result, (tuple, list)):

1035

return list(result)

1036

return [result]

1037

1038

1039

def restore_default(self, key):

1040

"""

1041

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

1042

1043

This method will only work for a ConfigObj that was created

1044

with a configspec and has been validated.

1045

1046

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

1047

"""

1048

default = self.default_values[key]

1049

dict.__setitem__(self, key, default)

1050

if key not in self.defaults:

1051

self.defaults.append(key)

1052

return default

1053

1054

1055

def restore_defaults(self):

1056

"""

1057

Recursively restore default values to all members

1058

that have them.

1059

1060

This method will only work for a ConfigObj that was created

1061

with a configspec and has been validated.

1062

1063

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

1064

"""

1065

for key in self.default_values:

1066

self.restore_default(key)

1067

1068

for section in self.sections:

1069

self[section].restore_defaults()

1070

1071

1072

class ConfigObj(Section):

1073

"""An object to read, create, and write config files."""

1074

1075

_keyword = re.compile(r'''^ # line start

1076

(\s*) # indentation

1077

( # keyword

1078

(?:".*?")| # double quotes

1079

(?:'.*?')| # single quotes

1080

(?:[^'"=].*?) # no quotes

1081

)

1082

\s*=\s* # divider

1083

(.*) # value (including list values and comments)

1084

$ # line end

1085

''',

1086

re.VERBOSE)

1087

1088

_sectionmarker = re.compile(r'''^

1089

(\s*) # 1: indentation

1090

((?:\[\s*)+) # 2: section marker open

1091

( # 3: section name open

1092

(?:"\s*\S.*?\s*")| # at least one non-space with double quotes

1093

(?:'\s*\S.*?\s*')| # at least one non-space with single quotes

1094

(?:[^'"\s].*?) # at least one non-space unquoted

1095

) # section name close

1096

((?:\s*\])+) # 4: section marker close

1097

\s*(\#.*)? # 5: optional comment

1098

$''',

1099

re.VERBOSE)

1100

1101

# this regexp pulls list values out as a single string

1102

# or single values and comments

1103

# FIXME: this regex adds a '' to the end of comma terminated lists

1104

# workaround in ``_handle_value``

1105

_valueexp = re.compile(r'''^

1106

(?:

1107

(?:

1108

(

1109

(?:

1110

(?:

1111

(?:".*?")| # double quotes

1112

(?:'.*?')| # single quotes

1113

(?:[^'",\#][^,\#]*?) # unquoted

1114

)

1115

\s*,\s* # comma

1116

)* # match all list items ending in a comma (if any)

1117

)

1118

(

1119

(?:".*?")| # double quotes

1120

(?:'.*?')| # single quotes

1121

(?:[^'",\#\s][^,]*?)| # unquoted

1122

(?:(?<!,)) # Empty value

1123

)? # last item in a list - or string value

1124

)|

1125

(,) # alternatively a single comma - empty list

1126

)

1127

\s*(\#.*)? # optional comment

1128

$''',

1129

re.VERBOSE)

1130

1131

# use findall to get the members of a list value

1132

_listvalueexp = re.compile(r'''

1133

(

1134

(?:".*?")| # double quotes

1135

(?:'.*?')| # single quotes

1136

(?:[^'",\#]?.*?) # unquoted

1137

)

1138

\s*,\s* # comma

1139

''',

1140

re.VERBOSE)

1141

1142

# this regexp is used for the value

1143

# when lists are switched off

1144

_nolistvalue = re.compile(r'''^

1145

(

1146

(?:".*?")| # double quotes

1147

(?:'.*?')| # single quotes

1148

(?:[^'"\#].*?)| # unquoted

1149

(?:) # Empty value

1150

)

1151

\s*(\#.*)? # optional comment

1152

$''',

1153

re.VERBOSE)

1154

1155

# regexes for finding triple quoted values on one line

1156

_single_line_single = re.compile(r"^'''(.*?)'''\s*(#.*)?$")

1157

_single_line_double = re.compile(r'^"""(.*?)"""\s*(#.*)?$')

1158

_multi_line_single = re.compile(r"^(.*?)'''\s*(#.*)?$")

1159

_multi_line_double = re.compile(r'^(.*?)"""\s*(#.*)?$')

1160

1161

_triple_quote = {

1162

"'''": (_single_line_single, _multi_line_single),

1163

'"""': (_single_line_double, _multi_line_double),

1164

}

1165

1166

# Used by the ``istrue`` Section method

1167

_bools = {

1168

'yes': True, 'no': False,

1169

'on': True, 'off': False,

1170

'1': True, '0': False,

1171

'true': True, 'false': False,

1172

}

1173

1174

1175

def __init__(self, infile=None, options=None, configspec=None, encoding=None,

1176

interpolation=True, raise_errors=False, list_values=True,

1177

create_empty=False, file_error=False, stringify=True,

1178

indent_type=None, default_encoding=None, unrepr=False,

1179

write_empty_values=False, _inspec=False):

1180

"""

1181

Parse a config file or create a config file object.

1182

1183

``ConfigObj(infile=None, configspec=None, encoding=None,

1184

interpolation=True, raise_errors=False, list_values=True,

1185

create_empty=False, file_error=False, stringify=True,

1186

indent_type=None, default_encoding=None, unrepr=False,

1187

write_empty_values=False, _inspec=False)``

1188

"""

1189

self._inspec = _inspec

1190

# init the superclass

1191

Section.__init__(self, self, 0, self)

1192

1193

infile = infile or []

1194

1195

_options = {'configspec': configspec,

1196

'encoding': encoding, 'interpolation': interpolation,

1197

'raise_errors': raise_errors, 'list_values': list_values,

1198

'create_empty': create_empty, 'file_error': file_error,

1199

'stringify': stringify, 'indent_type': indent_type,

1200

'default_encoding': default_encoding, 'unrepr': unrepr,

1201

'write_empty_values': write_empty_values}

1202

1203

if options is None:

1204

options = _options

1205

else:

1206

import warnings

1207

warnings.warn('Passing in an options dictionary to ConfigObj() is '

1208

'deprecated. Use **options instead.',

1209

DeprecationWarning, stacklevel=2)

1210

1211

# TODO: check the values too.

1212

for entry in options:

1213

if entry not in OPTION_DEFAULTS:

1214

raise TypeError('Unrecognised option "%s".' % entry)

1215

for entry, value in OPTION_DEFAULTS.items():

1216

if entry not in options:

1217

options[entry] = value

1218

keyword_value = _options[entry]

1219

if value != keyword_value:

1220

options[entry] = keyword_value

1221

1222

# XXXX this ignores an explicit list_values = True in combination

1223

# with _inspec. The user should *never* do that anyway, but still...

1224

if _inspec:

1225

options['list_values'] = False

1226

1227

self._initialise(options)

1228

configspec = options['configspec']

1229

self._original_configspec = configspec

1230

self._load(infile, configspec)

1231

1232

1233

def _load(self, infile, configspec):

1234

if isinstance(infile, basestring):

1235

self.filename = infile

1236

if os.path.isfile(infile):

1237

h = open(infile, 'rb')

1238

infile = h.read() or []

1239

h.close()

1240

elif self.file_error:

1241

# raise an error if the file doesn't exist

1242

raise IOError('Config file not found: "%s".' % self.filename)

1243

else:

1244

# file doesn't already exist

1245

if self.create_empty:

1246

# this is a good test that the filename specified

1247

# isn't impossible - like on a non-existent device

1248

h = open(infile, 'w')

1249

h.write('')

1250

h.close()

1251

infile = []

1252

1253

elif isinstance(infile, (list, tuple)):

1254

infile = list(infile)

1255

1256

elif isinstance(infile, dict):

1257

# initialise self

1258

# the Section class handles creating subsections

1259

if isinstance(infile, ConfigObj):

1260

# get a copy of our ConfigObj

1261

def set_section(in_section, this_section):

1262

for entry in in_section.scalars:

1263

this_section[entry] = in_section[entry]

1264

for section in in_section.sections:

1265

this_section[section] = {}

1266

set_section(in_section[section], this_section[section])

1267

set_section(infile, self)

1268

1269

else:

1270

for entry in infile:

1271

self[entry] = infile[entry]

1272

del self._errors

1273

1274

if configspec is not None:

1275

self._handle_configspec(configspec)

1276

else:

1277

self.configspec = None

1278

return

1279

1280

elif getattr(infile, 'read', MISSING) is not MISSING:

1281

# This supports file like objects

1282

infile = infile.read() or []

1283

# needs splitting into lines - but needs doing *after* decoding

1284

# in case it's not an 8 bit encoding

1285

else:

1286

raise TypeError('infile must be a filename, file like object, or list of lines.')

1287

1288

if infile:

1289

# don't do it for the empty ConfigObj

1290

infile = self._handle_bom(infile)

1291

# infile is now *always* a list

1292

#

1293

# Set the newlines attribute (first line ending it finds)

1294

# and strip trailing '\n' or '\r' from lines

1295

for line in infile:

1296

if (not line) or (line[-1] not in ('\r', '\n', '\r\n')):

1297

continue

1298

for end in ('\r\n', '\n', '\r'):

1299

if line.endswith(end):

1300

self.newlines = end

1301

break

1302

break

1303

1304

infile = [line.rstrip('\r\n') for line in infile]

1305

1306

self._parse(infile)

1307

# if we had any errors, now is the time to raise them

1308

if self._errors:

1309

info = "at line %s." % self._errors[0].line_number

1310

if len(self._errors) > 1:

1311

msg = "Parsing failed with several errors.\nFirst error %s" % info

1312

error = ConfigObjError(msg)

1313

else:

1314

error = self._errors[0]

1315

# set the errors attribute; it's a list of tuples:

1316

# (error_type, message, line_number)

1317

error.errors = self._errors

1318

# set the config attribute

1319

error.config = self

1320

raise error

1321

# delete private attributes

1322

del self._errors

1323

1324

if configspec is None:

1325

self.configspec = None

1326

else:

1327

self._handle_configspec(configspec)

1328

1329

1330

def _initialise(self, options=None):

1331

if options is None:

1332

options = OPTION_DEFAULTS

1333

1334

# initialise a few variables

1335

self.filename = None

1336

self._errors = []

1337

self.raise_errors = options['raise_errors']

1338

self.interpolation = options['interpolation']

1339

self.list_values = options['list_values']

1340

self.create_empty = options['create_empty']

1341

self.file_error = options['file_error']

1342

self.stringify = options['stringify']

1343

self.indent_type = options['indent_type']

1344

self.encoding = options['encoding']

1345

self.default_encoding = options['default_encoding']

1346

self.BOM = False

1347

self.newlines = None

1348

self.write_empty_values = options['write_empty_values']

1349

self.unrepr = options['unrepr']

1350

1351

self.initial_comment = []

1352

self.final_comment = []

1353

self.configspec = None

1354

1355

if self._inspec:

1356

self.list_values = False

1357

1358

# Clear section attributes as well

1359

Section._initialise(self)

1360

1361

1362

def __repr__(self):

1363

def _getval(key):

1364

try:

1365

return self[key]

1366

except MissingInterpolationOption:

1367

return dict.__getitem__(self, key)

1368

return ('ConfigObj({%s})' %

1369

', '.join([('%s: %s' % (repr(key), repr(_getval(key))))

1370

for key in (self.scalars + self.sections)]))

1371

1372

1373

def _handle_bom(self, infile):

1374

"""

1375

Handle any BOM, and decode if necessary.

1376

1377

If an encoding is specified, that *must* be used - but the BOM should

1378

still be removed (and the BOM attribute set).

1379

1380

(If the encoding is wrongly specified, then a BOM for an alternative

1381

encoding won't be discovered or removed.)

1382

1383

If an encoding is not specified, UTF8 or UTF16 BOM will be detected and

1384

removed. The BOM attribute will be set. UTF16 will be decoded to

1385

unicode.

1386

1387

NOTE: This method must not be called with an empty ``infile``.

1388

1389

Specifying the *wrong* encoding is likely to cause a

1390

``UnicodeDecodeError``.

1391

1392

``infile`` must always be returned as a list of lines, but may be

1393

passed in as a single string.

1394

"""

1395

if ((self.encoding is not None) and

1396

(self.encoding.lower() not in BOM_LIST)):

1397

# No need to check for a BOM

1398

# the encoding specified doesn't have one

1399

# just decode

1400

return self._decode(infile, self.encoding)

1401

1402

if isinstance(infile, (list, tuple)):

1403

line = infile[0]

1404

else:

1405

line = infile

1406

if self.encoding is not None:

1407

# encoding explicitly supplied

1408

# And it could have an associated BOM

1409

# TODO: if encoding is just UTF16 - we ought to check for both

1410

# TODO: big endian and little endian versions.

1411

enc = BOM_LIST[self.encoding.lower()]

1412

if enc == 'utf_16':

1413

# For UTF16 we try big endian and little endian

1414

for BOM, (encoding, final_encoding) in BOMS.items():

1415

if not final_encoding:

1416

# skip UTF8

1417

continue

1418

if infile.startswith(BOM):

1419

### BOM discovered

1420

##self.BOM = True

1421

# Don't need to remove BOM

1422

return self._decode(infile, encoding)

1423

1424

# If we get this far, will *probably* raise a DecodeError

1425

# As it doesn't appear to start with a BOM

1426

return self._decode(infile, self.encoding)

1427

1428

# Must be UTF8

1429

BOM = BOM_SET[enc]

1430

if not line.startswith(BOM):

1431

return self._decode(infile, self.encoding)

1432

1433

newline = line[len(BOM):]

1434

1435

# BOM removed

1436

if isinstance(infile, (list, tuple)):

1437

infile[0] = newline

1438

else:

1439

infile = newline

1440

self.BOM = True

1441

return self._decode(infile, self.encoding)

1442

1443

# No encoding specified - so we need to check for UTF8/UTF16

1444

for BOM, (encoding, final_encoding) in BOMS.items():

1445

if not line.startswith(BOM):

1446

continue

1447

else:

1448

# BOM discovered

1449

self.encoding = final_encoding

1450

if not final_encoding:

1451

self.BOM = True

1452

# UTF8

1453

# remove BOM

1454

newline = line[len(BOM):]

1455

if isinstance(infile, (list, tuple)):

1456

infile[0] = newline

1457

else:

1458

infile = newline

1459

# UTF8 - don't decode

1460

if isinstance(infile, basestring):

1461

return infile.splitlines(True)

1462

else:

1463

return infile

1464

# UTF16 - have to decode

1465

return self._decode(infile, encoding)

1466

1467

# No BOM discovered and no encoding specified, just return

1468

if isinstance(infile, basestring):

1469

# infile read from a file will be a single string

1470

return infile.splitlines(True)

1471

return infile

1472

1473

1474

def _a_to_u(self, aString):

1475

"""Decode ASCII strings to unicode if a self.encoding is specified."""

1476

if self.encoding:

1477

return aString.decode('ascii')

1478

else:

1479

return aString

1480

1481

1482

def _decode(self, infile, encoding):

1483

"""

1484

Decode infile to unicode. Using the specified encoding.

1485

1486

if is a string, it also needs converting to a list.

1487

"""

1488

if isinstance(infile, basestring):

1489

# can't be unicode

1490

# NOTE: Could raise a ``UnicodeDecodeError``

1491

return infile.decode(encoding).splitlines(True)

1492

for i, line in enumerate(infile):

1493

if not isinstance(line, unicode):

1494

# NOTE: The isinstance test here handles mixed lists of unicode/string

1495

# NOTE: But the decode will break on any non-string values

1496

# NOTE: Or could raise a ``UnicodeDecodeError``

1497

infile[i] = line.decode(encoding)

1498

return infile

1499

1500

1501

def _decode_element(self, line):

1502

"""Decode element to unicode if necessary."""

1503

if not self.encoding:

1504

return line

1505

if isinstance(line, str) and self.default_encoding:

1506

return line.decode(self.default_encoding)

1507

return line

1508

1509

1510

def _str(self, value):

1511

"""

1512

Used by ``stringify`` within validate, to turn non-string values

1513

into strings.

1514

"""

1515

if not isinstance(value, basestring):

1516

return str(value)

1517

else:

1518

return value

1519

1520

1521

def _parse(self, infile):

1522

"""Actually parse the config file."""

1523

temp_list_values = self.list_values

1524

if self.unrepr:

1525

self.list_values = False

1526

1527

comment_list = []

1528

done_start = False

1529

this_section = self

1530

maxline = len(infile) - 1

1531

cur_index = -1

1532

reset_comment = False

1533

1534

while cur_index < maxline:

1535

if reset_comment:

1536

comment_list = []

1537

cur_index += 1

1538

line = infile[cur_index]

1539

sline = line.strip()

1540

# do we have anything on the line ?

1541

if not sline or sline.startswith('#'):

1542

reset_comment = False

1543

comment_list.append(line)

1544

continue

1545

1546

if not done_start:

1547

# preserve initial comment

1548

self.initial_comment = comment_list

1549

comment_list = []

1550

done_start = True

1551

1552

reset_comment = True

1553

# first we check if it's a section marker

1554

mat = self._sectionmarker.match(line)

1555

if mat is not None:

1556

# is a section line

1557

(indent, sect_open, sect_name, sect_close, comment) = mat.groups()

1558

if indent and (self.indent_type is None):

1559

self.indent_type = indent

1560

cur_depth = sect_open.count('[')

1561

if cur_depth != sect_close.count(']'):

1562

self._handle_error("Cannot compute the section depth at line %s.",

1563

NestingError, infile, cur_index)

1564

continue

1565

1566

if cur_depth < this_section.depth:

1567

# the new section is dropping back to a previous level

1568

try:

1569

parent = self._match_depth(this_section,

1570

cur_depth).parent

1571

except SyntaxError:

1572

self._handle_error("Cannot compute nesting level at line %s.",

1573

NestingError, infile, cur_index)

1574

continue

1575

elif cur_depth == this_section.depth:

1576

# the new section is a sibling of the current section

1577

parent = this_section.parent

1578

elif cur_depth == this_section.depth + 1:

1579

# the new section is a child the current section

1580

parent = this_section

1581

else:

1582

self._handle_error("Section too nested at line %s.",

1583

NestingError, infile, cur_index)

1584

1585

sect_name = self._unquote(sect_name)

1586

if sect_name in parent:

1587

self._handle_error('Duplicate section name at line %s.',

1588

DuplicateError, infile, cur_index)

1589

continue

1590

1591

# create the new section

1592

this_section = Section(

1593

parent,

1594

cur_depth,

1595

self,

1596

name=sect_name)

1597

parent[sect_name] = this_section

1598

parent.inline_comments[sect_name] = comment

1599

parent.comments[sect_name] = comment_list

1600

continue

1601

#

1602

# it's not a section marker,

1603

# so it should be a valid ``key = value`` line

1604

mat = self._keyword.match(line)

1605

if mat is None:

1606

# it neither matched as a keyword

1607

# or a section marker

1608

self._handle_error(

1609

'Invalid line at line "%s".',

1610

ParseError, infile, cur_index)

1611

else:

1612

# is a keyword value

1613

# value will include any inline comment

1614

(indent, key, value) = mat.groups()

1615

if indent and (self.indent_type is None):

1616

self.indent_type = indent

1617

# check for a multiline value

1618

if value[:3] in ['"""', "'''"]:

1619

try:

1620

value, comment, cur_index = self._multiline(

1621

value, infile, cur_index, maxline)

1622

except SyntaxError:

1623

self._handle_error(

1624

'Parse error in value at line %s.',

1625

ParseError, infile, cur_index)

1626

continue

1627

else:

1628

if self.unrepr:

1629

comment = ''

1630

try:

1631

value = unrepr(value)

1632

except Exception, e:

1633

if type(e) == UnknownType:

1634

msg = 'Unknown name or type in value at line %s.'

1635

else:

1636

msg = 'Parse error in value at line %s.'

1637

self._handle_error(msg, UnreprError, infile,

1638

cur_index)

1639

continue

1640

else:

1641

if self.unrepr:

1642

comment = ''

1643

try:

1644

value = unrepr(value)

1645

except Exception, e:

1646

if isinstance(e, UnknownType):

1647

msg = 'Unknown name or type in value at line %s.'

1648

else:

1649

msg = 'Parse error in value at line %s.'

1650

self._handle_error(msg, UnreprError, infile,

1651

cur_index)

1652

continue

1653

else:

1654

# extract comment and lists

1655

try:

1656

(value, comment) = self._handle_value(value)

1657

except SyntaxError:

1658

self._handle_error(

1659

'Parse error in value at line %s.',

1660

ParseError, infile, cur_index)

1661

continue

1662

#

1663

key = self._unquote(key)

1664

if key in this_section:

1665

self._handle_error(

1666

'Duplicate keyword name at line %s.',

1667

DuplicateError, infile, cur_index)

1668

continue

1669

# add the key.

1670

# we set unrepr because if we have got this far we will never

1671

# be creating a new section

1672

this_section.__setitem__(key, value, unrepr=True)

1673

this_section.inline_comments[key] = comment

1674

this_section.comments[key] = comment_list

1675

continue

1676

#

1677

if self.indent_type is None:

1678

# no indentation used, set the type accordingly

1679

self.indent_type = ''

1680

1681

# preserve the final comment

1682

if not self and not self.initial_comment:

1683

self.initial_comment = comment_list

1684

elif not reset_comment:

1685

self.final_comment = comment_list

1686

self.list_values = temp_list_values

1687

1688

1689

def _match_depth(self, sect, depth):

1690

"""

1691

Given a section and a depth level, walk back through the sections

1692

parents to see if the depth level matches a previous section.

1693

1694

Return a reference to the right section,

1695

or raise a SyntaxError.

1696

"""

1697

while depth < sect.depth:

1698

if sect is sect.parent:

1699

# we've reached the top level already

1700

raise SyntaxError()

1701

sect = sect.parent

1702

if sect.depth == depth:

1703

return sect

1704

# shouldn't get here

1705

raise SyntaxError()

1706

1707

1708

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

1709

"""

1710

Handle an error according to the error settings.

1711

1712

Either raise the error or store it.

1713

The error will have occured at ``cur_index``

1714

"""

1715

line = infile[cur_index]

1716

cur_index += 1

1717

message = text % cur_index

1718

error = ErrorClass(message, cur_index, line)

1719

if self.raise_errors:

1720

# raise the error - parsing stops here

1721

raise error

1722

# store the error

1723

# reraise when parsing has finished

1724

self._errors.append(error)

1725

1726

1727

def _unquote(self, value):

1728

"""Return an unquoted version of a value"""

1729

if not value:

1730

# should only happen during parsing of lists

1731

raise SyntaxError

1732

if (value[0] == value[-1]) and (value[0] in ('"', "'")):

1733

value = value[1:-1]

1734

return value

1735

1736

1737

def _quote(self, value, multiline=True):

1738

"""

1739

Return a safely quoted version of a value.

1740

1741

Raise a ConfigObjError if the value cannot be safely quoted.

1742

If multiline is ``True`` (default) then use triple quotes

1743

if necessary.

1744

1745

* Don't quote values that don't need it.

1746

* Recursively quote members of a list and return a comma joined list.

1747

* Multiline is ``False`` for lists.

1748

* Obey list syntax for empty and single member lists.

1749

1750

If ``list_values=False`` then the value is only quoted if it contains

1751

a ``\\n`` (is multiline) or '#'.

1752

1753

If ``write_empty_values`` is set, and the value is an empty string, it

1754

won't be quoted.

1755

"""

1756

if multiline and self.write_empty_values and value == '':

1757

# Only if multiline is set, so that it is used for values not

1758

# keys, and not values that are part of a list

1759

return ''

1760

1761

if multiline and isinstance(value, (list, tuple)):

1762

if not value:

1763

return ','

1764

elif len(value) == 1:

1765

return self._quote(value[0], multiline=False) + ','

1766

return ', '.join([self._quote(val, multiline=False)

1767

for val in value])

1768

if not isinstance(value, basestring):

1769

if self.stringify:

1770

value = str(value)

1771

else:

1772

raise TypeError('Value "%s" is not a string.' % value)

1773

1774

if not value:

1775

return '""'

1776

1777

no_lists_no_quotes = not self.list_values and '\n' not in value and '#' not in value

1778

need_triple = multiline and ((("'" in value) and ('"' in value)) or ('\n' in value ))

1779

hash_triple_quote = multiline and not need_triple and ("'" in value) and ('"' in value) and ('#' in value)

1780

check_for_single = (no_lists_no_quotes or not need_triple) and not hash_triple_quote

1781

1782

if check_for_single:

1783

if not self.list_values:

1784

# we don't quote if ``list_values=False``

1785

quot = noquot

1786

# for normal values either single or double quotes will do

1787

elif '\n' in value:

1788

# will only happen if multiline is off - e.g. '\n' in key

1789

raise ConfigObjError('Value "%s" cannot be safely quoted.' % value)

1790

elif ((value[0] not in wspace_plus) and

1791

(value[-1] not in wspace_plus) and

1792

(',' not in value)):

1793

quot = noquot

1794

else:

1795

quot = self._get_single_quote(value)

1796

else:

1797

# if value has '\n' or "'" *and* '"', it will need triple quotes

1798

quot = self._get_triple_quote(value)

1799

1800

if quot == noquot and '#' in value and self.list_values:

1801

quot = self._get_single_quote(value)

1802

1803

return quot % value

1804

1805

1806

def _get_single_quote(self, value):

1807

if ("'" in value) and ('"' in value):

1808

raise ConfigObjError('Value "%s" cannot be safely quoted.' % value)

1809

elif '"' in value:

1810

quot = squot

1811

else:

1812

quot = dquot

1813

return quot

1814

1815

1816

def _get_triple_quote(self, value):

1817

if (value.find('"""') != -1) and (value.find("'''") != -1):

1818

raise ConfigObjError('Value "%s" cannot be safely quoted.' % value)

1819

if value.find('"""') == -1:

1820

quot = tdquot

1821

else:

1822

quot = tsquot

1823

return quot

1824

1825

1826

def _handle_value(self, value):

1827

"""

1828

Given a value string, unquote, remove comment,

1829

handle lists. (including empty and single member lists)

1830

"""

1831

if self._inspec:

1832

# Parsing a configspec so don't handle comments

1833

return (value, '')

1834

# do we look for lists in values ?

1835

if not self.list_values:

1836

mat = self._nolistvalue.match(value)

1837

if mat is None:

1838

raise SyntaxError()

1839

# NOTE: we don't unquote here

1840

return mat.groups()

1841

#

1842

mat = self._valueexp.match(value)

1843

if mat is None:

1844

# the value is badly constructed, probably badly quoted,

1845

# or an invalid list

1846

raise SyntaxError()

1847

(list_values, single, empty_list, comment) = mat.groups()

1848

if (list_values == '') and (single is None):

1849

# change this if you want to accept empty values

1850

raise SyntaxError()

1851

# NOTE: note there is no error handling from here if the regex

1852

# is wrong: then incorrect values will slip through

1853

if empty_list is not None:

1854

# the single comma - meaning an empty list

1855

return ([], comment)

1856

if single is not None:

1857

# handle empty values

1858

if list_values and not single:

1859

# FIXME: the '' is a workaround because our regex now matches

1860

# '' at the end of a list if it has a trailing comma

1861

single = None

1862

else:

1863

single = single or '""'

1864

single = self._unquote(single)

1865

if list_values == '':

1866

# not a list value

1867

return (single, comment)

1868

the_list = self._listvalueexp.findall(list_values)

1869

the_list = [self._unquote(val) for val in the_list]

1870

if single is not None:

1871

the_list += [single]

1872

return (the_list, comment)

1873

1874

1875

def _multiline(self, value, infile, cur_index, maxline):

1876

"""Extract the value, where we are in a multiline situation."""

1877

quot = value[:3]

1878

newvalue = value[3:]

1879

single_line = self._triple_quote[quot][0]

1880

multi_line = self._triple_quote[quot][1]

1881

mat = single_line.match(value)

1882

if mat is not None:

1883

retval = list(mat.groups())

1884

retval.append(cur_index)

1885

return retval

1886

elif newvalue.find(quot) != -1:

1887

# somehow the triple quote is missing

1888

raise SyntaxError()

1889

#

1890

while cur_index < maxline:

1891

cur_index += 1

1892

newvalue += '\n'

1893

line = infile[cur_index]

1894

if line.find(quot) == -1:

1895

newvalue += line

1896

else:

1897

# end of multiline, process it

1898

break

1899

else:

1900

# we've got to the end of the config, oops...

1901

raise SyntaxError()

1902

mat = multi_line.match(line)

1903

if mat is None:

1904

# a badly formed line

1905

raise SyntaxError()

1906

(value, comment) = mat.groups()

1907

return (newvalue + value, comment, cur_index)

1908

1909

1910

def _handle_configspec(self, configspec):

1911

"""Parse the configspec."""

1912

# FIXME: Should we check that the configspec was created with the

1913

# correct settings ? (i.e. ``list_values=False``)

1914

if not isinstance(configspec, ConfigObj):

1915

try:

1916

configspec = ConfigObj(configspec,

1917

raise_errors=True,

1918

file_error=True,

1919

_inspec=True)

1920

except ConfigObjError, e:

1921

# FIXME: Should these errors have a reference

1922

# to the already parsed ConfigObj ?

1923

raise ConfigspecError('Parsing configspec failed: %s' % e)

1924

except IOError, e:

1925

raise IOError('Reading configspec failed: %s' % e)

1926

1927

self.configspec = configspec

1928

1929

1930

1931

def _set_configspec(self, section, copy):

1932

"""

1933

Called by validate. Handles setting the configspec on subsections

1934

including sections to be validated by __many__

1935

"""

1936

configspec = section.configspec

1937

many = configspec.get('__many__')

1938

if isinstance(many, dict):

1939

for entry in section.sections:

1940

if entry not in configspec:

1941

section[entry].configspec = many

1942

1943

for entry in configspec.sections:

1944

if entry == '__many__':

1945

continue

1946

if entry not in section:

1947

section[entry] = {}

1948

section[entry]._created = True

1949

if copy:

1950

# copy comments

1951

section.comments[entry] = configspec.comments.get(entry, [])

1952

section.inline_comments[entry] = configspec.inline_comments.get(entry, '')

1953

1954

# Could be a scalar when we expect a section

1955

if isinstance(section[entry], Section):

1956

section[entry].configspec = configspec[entry]

1957

1958

1959

def _write_line(self, indent_string, entry, this_entry, comment):

1960

"""Write an individual line, for the write method"""

1961

# NOTE: the calls to self._quote here handles non-StringType values.

1962

if not self.unrepr:

1963

val = self._decode_element(self._quote(this_entry))

1964

else:

1965

val = repr(this_entry)

1966

return '%s%s%s%s%s' % (indent_string,

1967

self._decode_element(self._quote(entry, multiline=False)),

1968

self._a_to_u(' = '),

1969

val,

1970

self._decode_element(comment))

1971

1972

1973

def _write_marker(self, indent_string, depth, entry, comment):

1974

"""Write a section marker line"""

1975

return '%s%s%s%s%s' % (indent_string,

1976

self._a_to_u('[' * depth),

1977

self._quote(self._decode_element(entry), multiline=False),

1978

self._a_to_u(']' * depth),

1979

self._decode_element(comment))

1980

1981

1982

def _handle_comment(self, comment):

1983

"""Deal with a comment."""

1984

if not comment:

1985

return ''

1986

start = self.indent_type

1987

if not comment.startswith('#'):

1988

start += self._a_to_u(' # ')

1989

return (start + comment)

1990

1991

1992

# Public methods

1993

1994

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

1995

"""

1996

Write the current ConfigObj as a file

1997

1998

tekNico: FIXME: use StringIO instead of real files

1999

2000

>>> filename = a.filename

2001

>>> a.filename = 'test.ini'

2002

>>> a.write()

2003

>>> a.filename = filename

2004

>>> a == ConfigObj('test.ini', raise_errors=True)

2005

1

2006

>>> import os

2007

>>> os.remove('test.ini')

2008

"""

2009

if self.indent_type is None:

2010

# this can be true if initialised from a dictionary

2011

self.indent_type = DEFAULT_INDENT_TYPE

2012

2013

out = []

2014

cs = self._a_to_u('#')

2015

csp = self._a_to_u('# ')

2016

if section is None:

2017

int_val = self.interpolation

2018

self.interpolation = False

2019

section = self

2020

for line in self.initial_comment:

2021

line = self._decode_element(line)

2022

stripped_line = line.strip()

2023

if stripped_line and not stripped_line.startswith(cs):

2024

line = csp + line

2025

out.append(line)

2026

2027

indent_string = self.indent_type * section.depth

2028

for entry in (section.scalars + section.sections):

2029

if entry in section.defaults:

2030

# don't write out default values

2031

continue

2032

for comment_line in section.comments[entry]:

2033

comment_line = self._decode_element(comment_line.lstrip())

2034

if comment_line and not comment_line.startswith(cs):

2035

comment_line = csp + comment_line

2036

out.append(indent_string + comment_line)

2037

this_entry = section[entry]

2038

comment = self._handle_comment(section.inline_comments[entry])

2039

2040

if isinstance(this_entry, dict):

2041

# a section

2042

out.append(self._write_marker(

2043

indent_string,

2044

this_entry.depth,

2045

entry,

2046

comment))

2047

out.extend(self.write(section=this_entry))

2048

else:

2049

out.append(self._write_line(

2050

indent_string,

2051

entry,

2052

this_entry,

2053

comment))

2054

2055

if section is self:

2056

for line in self.final_comment:

2057

line = self._decode_element(line)

2058

stripped_line = line.strip()

2059

if stripped_line and not stripped_line.startswith(cs):

2060

line = csp + line

2061

out.append(line)

2062

self.interpolation = int_val

2063

2064

if section is not self:

2065

return out

2066

2067

if (self.filename is None) and (outfile is None):

2068

# output a list of lines

2069

# might need to encode

2070

# NOTE: This will *screw* UTF16, each line will start with the BOM

2071

if self.encoding:

2072

out = [l.encode(self.encoding) for l in out]

2073

if (self.BOM and ((self.encoding is None) or

2074

(BOM_LIST.get(self.encoding.lower()) == 'utf_8'))):

2075

# Add the UTF8 BOM

2076

if not out:

2077

out.append('')

2078

out[0] = BOM_UTF8 + out[0]

2079

return out

2080

2081

# Turn the list to a string, joined with correct newlines

2082

newline = self.newlines or os.linesep

2083

if (getattr(outfile, 'mode', None) is not None and outfile.mode == 'w'

2084

and sys.platform == 'win32' and newline == '\r\n'):

2085

# Windows specific hack to avoid writing '\r\r\n'

2086

newline = '\n'

2087

output = self._a_to_u(newline).join(out)

2088

if self.encoding:

2089

output = output.encode(self.encoding)

2090

if self.BOM and ((self.encoding is None) or match_utf8(self.encoding)):

2091

# Add the UTF8 BOM

2092

output = BOM_UTF8 + output

2093

2094

if not output.endswith(newline):

2095

output += newline

2096

if outfile is not None:

2097

outfile.write(output)

2098

else:

2099

h = open(self.filename, 'wb')

2100

h.write(output)

2101

h.close()

2102

2103

2104

def validate(self, validator, preserve_errors=False, copy=False,

2105

section=None):

2106

"""

2107

Test the ConfigObj against a configspec.

2108

2109

It uses the ``validator`` object from *validate.py*.

2110

2111

To run ``validate`` on the current ConfigObj, call: ::

2112

2113

test = config.validate(validator)

2114

2115

(Normally having previously passed in the configspec when the ConfigObj

2116

was created - you can dynamically assign a dictionary of checks to the

2117

``configspec`` attribute of a section though).

2118

2119

It returns ``True`` if everything passes, or a dictionary of

2120

pass/fails (True/False). If every member of a subsection passes, it

2121

will just have the value ``True``. (It also returns ``False`` if all

2122

members fail).

2123

2124

In addition, it converts the values from strings to their native

2125

types if their checks pass (and ``stringify`` is set).

2126

2127

If ``preserve_errors`` is ``True`` (``False`` is default) then instead

2128

of a marking a fail with a ``False``, it will preserve the actual

2129

exception object. This can contain info about the reason for failure.

2130

For example the ``VdtValueTooSmallError`` indicates that the value

2131

supplied was too small. If a value (or section) is missing it will

2132

still be marked as ``False``.

2133

2134

You must have the validate module to use ``preserve_errors=True``.

2135

2136

You can then use the ``flatten_errors`` function to turn your nested

2137

results dictionary into a flattened list of failures - useful for

2138

displaying meaningful error messages.

2139

"""

2140

if section is None:

2141

if self.configspec is None:

2142

raise ValueError('No configspec supplied.')

2143

if preserve_errors:

2144

# We do this once to remove a top level dependency on the validate module

2145

# Which makes importing configobj faster

2146

from validate import VdtMissingValue

2147

self._vdtMissingValue = VdtMissingValue

2148

2149

section = self

2150

2151

if copy:

2152

section.initial_comment = section.configspec.initial_comment

2153

section.final_comment = section.configspec.final_comment

2154

section.encoding = section.configspec.encoding

2155

section.BOM = section.configspec.BOM

2156

section.newlines = section.configspec.newlines

2157

section.indent_type = section.configspec.indent_type

2158

2159

#

2160

# section.default_values.clear() #??

2161

configspec = section.configspec

2162

self._set_configspec(section, copy)

2163

2164

2165

def validate_entry(entry, spec, val, missing, ret_true, ret_false):

2166

section.default_values.pop(entry, None)

2167

2168

try:

2169

section.default_values[entry] = validator.get_default_value(configspec[entry])

2170

except (KeyError, AttributeError, validator.baseErrorClass):

2171

# No default, bad default or validator has no 'get_default_value'

2172

# (e.g. SimpleVal)

2173

pass

2174

2175

try:

2176

check = validator.check(spec,

2177

val,

2178

missing=missing

2179

)

2180

except validator.baseErrorClass, e:

2181

if not preserve_errors or isinstance(e, self._vdtMissingValue):

2182

out[entry] = False

2183

else:

2184

# preserve the error

2185

out[entry] = e

2186

ret_false = False

2187

ret_true = False

2188

else:

2189

ret_false = False

2190

out[entry] = True

2191

if self.stringify or missing:

2192

# if we are doing type conversion

2193

# or the value is a supplied default

2194

if not self.stringify:

2195

if isinstance(check, (list, tuple)):

2196

# preserve lists

2197

check = [self._str(item) for item in check]

2198

elif missing and check is None:

2199

# convert the None from a default to a ''

2200

check = ''

2201

else:

2202

check = self._str(check)

2203

if (check != val) or missing:

2204

section[entry] = check

2205

if not copy and missing and entry not in section.defaults:

2206

section.defaults.append(entry)

2207

return ret_true, ret_false

2208

2209

#

2210

out = {}

2211

ret_true = True

2212

ret_false = True

2213

2214

unvalidated = [k for k in section.scalars if k not in configspec]

2215

incorrect_sections = [k for k in configspec.sections if k in section.scalars]

2216

incorrect_scalars = [k for k in configspec.scalars if k in section.sections]

2217

2218

for entry in configspec.scalars:

2219

if entry in ('__many__', '___many___'):

2220

# reserved names

2221

continue

2222

if (not entry in section.scalars) or (entry in section.defaults):

2223

# missing entries

2224

# or entries from defaults

2225

missing = True

2226

val = None

2227

if copy and entry not in section.scalars:

2228

# copy comments

2229

section.comments[entry] = (

2230

configspec.comments.get(entry, []))

2231

section.inline_comments[entry] = (

2232

configspec.inline_comments.get(entry, ''))

2233

#

2234

else:

2235

missing = False

2236

val = section[entry]

2237

2238

ret_true, ret_false = validate_entry(entry, configspec[entry], val,

2239

missing, ret_true, ret_false)

2240

2241

many = None

2242

if '__many__' in configspec.scalars:

2243

many = configspec['__many__']

2244

elif '___many___' in configspec.scalars:

2245

many = configspec['___many___']

2246

2247

if many is not None:

2248

for entry in unvalidated:

2249

val = section[entry]

2250

ret_true, ret_false = validate_entry(entry, many, val, False,

2251

ret_true, ret_false)

2252

unvalidated = []

2253

2254

for entry in incorrect_scalars:

2255

ret_true = False

2256

if not preserve_errors:

2257

out[entry] = False

2258

else:

2259

ret_false = False

2260

msg = 'Value %r was provided as a section' % entry

2261

out[entry] = validator.baseErrorClass(msg)

2262

for entry in incorrect_sections:

2263

ret_true = False

2264

if not preserve_errors:

2265

out[entry] = False

2266

else:

2267

ret_false = False

2268

msg = 'Section %r was provided as a single value' % entry

2269

out[entry] = validator.baseErrorClass(msg)

2270

2271

# Missing sections will have been created as empty ones when the

2272

# configspec was read.

2273

for entry in section.sections:

2274

# FIXME: this means DEFAULT is not copied in copy mode

2275

if section is self and entry == 'DEFAULT':

2276

continue

2277

if section[entry].configspec is None:

2278

unvalidated.append(entry)

2279

continue

2280

if copy:

2281

section.comments[entry] = configspec.comments.get(entry, [])

2282

section.inline_comments[entry] = configspec.inline_comments.get(entry, '')

2283

check = self.validate(validator, preserve_errors=preserve_errors, copy=copy, section=section[entry])

2284

out[entry] = check

2285

if check == False:

2286

ret_true = False

2287

elif check == True:

2288

ret_false = False

2289

else:

2290

ret_true = False

2291

2292

section.extra_values = unvalidated

2293

if preserve_errors and not section._created:

2294

# If the section wasn't created (i.e. it wasn't missing)

2295

# then we can't return False, we need to preserve errors

2296

ret_false = False

2297

#

2298

if ret_false and preserve_errors and out:

2299

# If we are preserving errors, but all

2300

# the failures are from missing sections / values

2301

# then we can return False. Otherwise there is a

2302

# real failure that we need to preserve.

2303

ret_false = not any(out.values())

2304

if ret_true:

2305

return True

2306

elif ret_false:

2307

return False

2308

return out

2309

2310

2311

def reset(self):

2312

"""Clear ConfigObj instance and restore to 'freshly created' state."""

2313

self.clear()

2314

self._initialise()

2315

# FIXME: Should be done by '_initialise', but ConfigObj constructor (and reload)

2316

# requires an empty dictionary

2317

self.configspec = None

2318

# Just to be sure ;-)

2319

self._original_configspec = None

2320

2321

2322

def reload(self):

2323

"""

2324

Reload a ConfigObj from file.

2325

2326

This method raises a ``ReloadError`` if the ConfigObj doesn't have

2327

a filename attribute pointing to a file.

2328

"""

2329

if not isinstance(self.filename, basestring):

2330

raise ReloadError()

2331

2332

filename = self.filename

2333

current_options = {}

2334

for entry in OPTION_DEFAULTS:

2335

if entry == 'configspec':

2336

continue

2337

current_options[entry] = getattr(self, entry)

2338

2339

configspec = self._original_configspec

2340

current_options['configspec'] = configspec

2341

2342

self.clear()

2343

self._initialise(current_options)

2344

self._load(filename, configspec)

2345

2346

2347

2348

class SimpleVal(object):

2349

"""

2350

A simple validator.

2351

Can be used to check that all members expected are present.

2352

2353

To use it, provide a configspec with all your members in (the value given

2354

will be ignored). Pass an instance of ``SimpleVal`` to the ``validate``

2355

method of your ``ConfigObj``. ``validate`` will return ``True`` if all

2356

members are present, or a dictionary with True/False meaning

2357

present/missing. (Whole missing sections will be replaced with ``False``)

2358

"""

2359

2360

def __init__(self):

2361

self.baseErrorClass = ConfigObjError

2362

2363

def check(self, check, member, missing=False):

2364

"""A dummy check method, always returns the value unchanged."""

2365

if missing:

2366

raise self.baseErrorClass()

2367

return member

2368

2369

2370

def flatten_errors(cfg, res, levels=None, results=None):

2371

"""

2372

An example function that will turn a nested dictionary of results

2373

(as returned by ``ConfigObj.validate``) into a flat list.

2374

2375

``cfg`` is the ConfigObj instance being checked, ``res`` is the results

2376

dictionary returned by ``validate``.

2377

2378

(This is a recursive function, so you shouldn't use the ``levels`` or

2379

``results`` arguments - they are used by the function.)

2380

2381

Returns a list of keys that failed. Each member of the list is a tuple::

2382

2383

([list of sections...], key, result)

2384

2385

If ``validate`` was called with ``preserve_errors=False`` (the default)

2386

then ``result`` will always be ``False``.

2387

2388

*list of sections* is a flattened list of sections that the key was found

2389

in.

2390

2391

If the section was missing (or a section was expected and a scalar provided

2392

- or vice-versa) then key will be ``None``.

2393

2394

If the value (or section) was missing then ``result`` will be ``False``.

2395

2396

If ``validate`` was called with ``preserve_errors=True`` and a value

2397

was present, but failed the check, then ``result`` will be the exception

2398

object returned. You can use this as a string that describes the failure.

2399

2400

For example *The value "3" is of the wrong type*.

2401

"""

2402

if levels is None:

2403

# first time called

2404

levels = []

2405

results = []

2406

if res == True:

2407

return results

2408

if res == False or isinstance(res, Exception):

2409

results.append((levels[:], None, res))

2410

if levels:

2411

levels.pop()

2412

return results

2413

for (key, val) in res.items():

2414

if val == True:

2415

continue

2416

if isinstance(cfg.get(key), dict):

2417

# Go down one level

2418

levels.append(key)

2419

flatten_errors(cfg[key], val, levels, results)

2420

continue

2421

results.append((levels[:], key, val))

2422

#

2423

# Go up one level

2424

if levels:

2425

levels.pop()

2426

#

2427

return results

2428

2429

2430

def get_extra_values(conf, _prepend=()):

2431

"""

2432

Find all the values and sections not in the configspec from a validated

2433

ConfigObj.

2434

2435

``get_extra_values`` returns a list of tuples where each tuple represents

2436

either an extra section, or an extra value.

2437

2438

The tuples contain two values, a tuple representing the section the value

2439

is in and the name of the extra values. For extra values in the top level

2440

section the first member will be an empty tuple. For values in the 'foo'

2441

section the first member will be ``('foo',)``. For members in the 'bar'

2442

subsection of the 'foo' section the first member will be ``('foo', 'bar')``.

2443

2444

NOTE: If you call ``get_extra_values`` on a ConfigObj instance that hasn't

2445

been validated it will return an empty list.

2446

"""

2447

out = []

2448

2449

out.extend([(_prepend, name) for name in conf.extra_values])

2450

for name in conf.sections:

2451

if name not in conf.extra_values:

2452

out.extend(get_extra_values(conf[name], _prepend + (name,)))

2453

return out

2454

2455

2456

"""*A programming language is a medium of expression.* - Paul Graham"""