configobj.py 84 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372137313741375137613771378137913801381138213831384138513861387138813891390139113921393139413951396139713981399140014011402140314041405140614071408140914101411141214131414141514161417141814191420142114221423142414251426142714281429143014311432143314341435143614371438143914401441144214431444144514461447144814491450145114521453145414551456145714581459146014611462146314641465146614671468146914701471147214731474147514761477147814791480148114821483148414851486148714881489149014911492149314941495149614971498149915001501150215031504150515061507150815091510151115121513151415151516151715181519152015211522152315241525152615271528152915301531153215331534153515361537153815391540154115421543154415451546154715481549155015511552155315541555155615571558155915601561156215631564156515661567156815691570157115721573157415751576157715781579158015811582158315841585158615871588158915901591159215931594159515961597159815991600160116021603160416051606160716081609161016111612161316141615161616171618161916201621162216231624162516261627162816291630163116321633163416351636163716381639164016411642164316441645164616471648164916501651165216531654165516561657165816591660166116621663166416651666166716681669167016711672167316741675167616771678167916801681168216831684168516861687168816891690169116921693169416951696169716981699170017011702170317041705170617071708170917101711171217131714171517161717171817191720172117221723172417251726172717281729173017311732173317341735173617371738173917401741174217431744174517461747174817491750175117521753175417551756175717581759176017611762176317641765176617671768176917701771177217731774177517761777177817791780178117821783178417851786178717881789179017911792179317941795179617971798179918001801180218031804180518061807180818091810181118121813181418151816181718181819182018211822182318241825182618271828182918301831183218331834183518361837183818391840184118421843184418451846184718481849185018511852185318541855185618571858185918601861186218631864186518661867186818691870187118721873187418751876187718781879188018811882188318841885188618871888188918901891189218931894189518961897189818991900190119021903190419051906190719081909191019111912191319141915191619171918191919201921192219231924192519261927192819291930193119321933193419351936193719381939194019411942194319441945194619471948194919501951195219531954195519561957195819591960196119621963196419651966196719681969197019711972197319741975197619771978197919801981198219831984198519861987198819891990199119921993199419951996199719981999200020012002200320042005200620072008200920102011201220132014201520162017201820192020202120222023202420252026202720282029203020312032203320342035203620372038203920402041204220432044204520462047204820492050205120522053205420552056205720582059206020612062206320642065206620672068206920702071207220732074207520762077207820792080208120822083208420852086208720882089209020912092209320942095209620972098209921002101210221032104210521062107210821092110211121122113211421152116211721182119212021212122212321242125212621272128212921302131213221332134213521362137213821392140214121422143214421452146214721482149215021512152215321542155215621572158215921602161216221632164216521662167216821692170217121722173217421752176217721782179218021812182218321842185218621872188218921902191219221932194219521962197219821992200220122022203220422052206220722082209221022112212221322142215221622172218221922202221222222232224222522262227222822292230223122322233223422352236223722382239224022412242224322442245224622472248224922502251225222532254225522562257225822592260226122622263226422652266226722682269227022712272227322742275227622772278227922802281228222832284228522862287228822892290229122922293229422952296229722982299230023012302230323042305230623072308230923102311231223132314231523162317231823192320232123222323232423252326232723282329233023312332233323342335233623372338233923402341234223432344234523462347234823492350235123522353235423552356235723582359236023612362236323642365236623672368236923702371237223732374237523762377237823792380238123822383238423852386238723882389239023912392239323942395239623972398239924002401240224032404240524062407240824092410241124122413241424152416241724182419242024212422242324242425242624272428242924302431243224332434243524362437243824392440244124422443244424452446244724482449245024512452245324542455
  1. # configobj.py
  2. # A config file reader/writer that supports nested sections in config files.
  3. # Copyright (C) 2005-2009 Michael Foord, Nicola Larosa
  4. # E-mail: fuzzyman AT voidspace DOT org DOT uk
  5. # nico AT tekNico DOT net
  6. # ConfigObj 4
  7. # http://www.voidspace.org.uk/python/configobj.html
  8. # Released subject to the BSD License
  9. # Please see http://www.voidspace.org.uk/python/license.shtml
  10. # Scripts maintained at http://www.voidspace.org.uk/python/index.shtml
  11. # For information about bugfixes, updates and support, please join the
  12. # ConfigObj mailing list:
  13. # http://lists.sourceforge.net/lists/listinfo/configobj-develop
  14. # Comments, suggestions and bug reports welcome.
  15. from __future__ import generators
  16. import sys
  17. import os
  18. import re
  19. compiler = None
  20. try:
  21. import compiler
  22. except ImportError:
  23. # for IronPython
  24. pass
  25. try:
  26. from codecs import BOM_UTF8, BOM_UTF16, BOM_UTF16_BE, BOM_UTF16_LE
  27. except ImportError:
  28. # Python 2.2 does not have these
  29. # UTF-8
  30. BOM_UTF8 = '\xef\xbb\xbf'
  31. # UTF-16, little endian
  32. BOM_UTF16_LE = '\xff\xfe'
  33. # UTF-16, big endian
  34. BOM_UTF16_BE = '\xfe\xff'
  35. if sys.byteorder == 'little':
  36. # UTF-16, native endianness
  37. BOM_UTF16 = BOM_UTF16_LE
  38. else:
  39. # UTF-16, native endianness
  40. BOM_UTF16 = BOM_UTF16_BE
  41. # A dictionary mapping BOM to
  42. # the encoding to decode with, and what to set the
  43. # encoding attribute to.
  44. BOMS = {
  45. BOM_UTF8: ('utf_8', None),
  46. BOM_UTF16_BE: ('utf16_be', 'utf_16'),
  47. BOM_UTF16_LE: ('utf16_le', 'utf_16'),
  48. BOM_UTF16: ('utf_16', 'utf_16'),
  49. }
  50. # All legal variants of the BOM codecs.
  51. # TODO: the list of aliases is not meant to be exhaustive, is there a
  52. # better way ?
  53. BOM_LIST = {
  54. 'utf_16': 'utf_16',
  55. 'u16': 'utf_16',
  56. 'utf16': 'utf_16',
  57. 'utf-16': 'utf_16',
  58. 'utf16_be': 'utf16_be',
  59. 'utf_16_be': 'utf16_be',
  60. 'utf-16be': 'utf16_be',
  61. 'utf16_le': 'utf16_le',
  62. 'utf_16_le': 'utf16_le',
  63. 'utf-16le': 'utf16_le',
  64. 'utf_8': 'utf_8',
  65. 'u8': 'utf_8',
  66. 'utf': 'utf_8',
  67. 'utf8': 'utf_8',
  68. 'utf-8': 'utf_8',
  69. }
  70. # Map of encodings to the BOM to write.
  71. BOM_SET = {
  72. 'utf_8': BOM_UTF8,
  73. 'utf_16': BOM_UTF16,
  74. 'utf16_be': BOM_UTF16_BE,
  75. 'utf16_le': BOM_UTF16_LE,
  76. None: BOM_UTF8
  77. }
  78. def match_utf8(encoding):
  79. return BOM_LIST.get(encoding.lower()) == 'utf_8'
  80. # Quote strings used for writing values
  81. squot = "'%s'"
  82. dquot = '"%s"'
  83. noquot = "%s"
  84. wspace_plus = ' \r\n\v\t\'"'
  85. tsquot = '"""%s"""'
  86. tdquot = "'''%s'''"
  87. try:
  88. enumerate
  89. except NameError:
  90. def enumerate(obj):
  91. """enumerate for Python 2.2."""
  92. i = -1
  93. for item in obj:
  94. i += 1
  95. yield i, item
  96. # Sentinel for use in getattr calls to replace hasattr
  97. MISSING = object()
  98. __version__ = '4.6.0'
  99. __revision__ = '$Id: configobj.py 156 2006-01-31 14:57:08Z fuzzyman $'
  100. __docformat__ = "restructuredtext en"
  101. __all__ = (
  102. '__version__',
  103. 'DEFAULT_INDENT_TYPE',
  104. 'DEFAULT_INTERPOLATION',
  105. 'ConfigObjError',
  106. 'NestingError',
  107. 'ParseError',
  108. 'DuplicateError',
  109. 'ConfigspecError',
  110. 'ConfigObj',
  111. 'SimpleVal',
  112. 'InterpolationError',
  113. 'InterpolationLoopError',
  114. 'MissingInterpolationOption',
  115. 'RepeatSectionError',
  116. 'ReloadError',
  117. 'UnreprError',
  118. 'UnknownType',
  119. '__docformat__',
  120. 'flatten_errors',
  121. )
  122. DEFAULT_INTERPOLATION = 'configparser'
  123. DEFAULT_INDENT_TYPE = ' '
  124. MAX_INTERPOL_DEPTH = 10
  125. OPTION_DEFAULTS = {
  126. 'interpolation': True,
  127. 'raise_errors': False,
  128. 'list_values': True,
  129. 'create_empty': False,
  130. 'file_error': False,
  131. 'configspec': None,
  132. 'stringify': True,
  133. # option may be set to one of ('', ' ', '\t')
  134. 'indent_type': None,
  135. 'encoding': None,
  136. 'default_encoding': None,
  137. 'unrepr': False,
  138. 'write_empty_values': False,
  139. }
  140. def getObj(s):
  141. s = "a=" + s
  142. if compiler is None:
  143. raise ImportError('compiler module not available')
  144. p = compiler.parse(s)
  145. return p.getChildren()[1].getChildren()[0].getChildren()[1]
  146. class UnknownType(Exception):
  147. pass
  148. class Builder(object):
  149. def build(self, o):
  150. m = getattr(self, 'build_' + o.__class__.__name__, None)
  151. if m is None:
  152. raise UnknownType(o.__class__.__name__)
  153. return m(o)
  154. def build_List(self, o):
  155. return map(self.build, o.getChildren())
  156. def build_Const(self, o):
  157. return o.value
  158. def build_Dict(self, o):
  159. d = {}
  160. i = iter(map(self.build, o.getChildren()))
  161. for el in i:
  162. d[el] = i.next()
  163. return d
  164. def build_Tuple(self, o):
  165. return tuple(self.build_List(o))
  166. def build_Name(self, o):
  167. if o.name == 'None':
  168. return None
  169. if o.name == 'True':
  170. return True
  171. if o.name == 'False':
  172. return False
  173. # An undefined Name
  174. raise UnknownType('Undefined Name')
  175. def build_Add(self, o):
  176. real, imag = map(self.build_Const, o.getChildren())
  177. try:
  178. real = float(real)
  179. except TypeError:
  180. raise UnknownType('Add')
  181. if not isinstance(imag, complex) or imag.real != 0.0:
  182. raise UnknownType('Add')
  183. return real+imag
  184. def build_Getattr(self, o):
  185. parent = self.build(o.expr)
  186. return getattr(parent, o.attrname)
  187. def build_UnarySub(self, o):
  188. return -self.build_Const(o.getChildren()[0])
  189. def build_UnaryAdd(self, o):
  190. return self.build_Const(o.getChildren()[0])
  191. _builder = Builder()
  192. def unrepr(s):
  193. if not s:
  194. return s
  195. return _builder.build(getObj(s))
  196. class ConfigObjError(SyntaxError):
  197. """
  198. This is the base class for all errors that ConfigObj raises.
  199. It is a subclass of SyntaxError.
  200. """
  201. def __init__(self, message='', line_number=None, line=''):
  202. self.line = line
  203. self.line_number = line_number
  204. SyntaxError.__init__(self, message)
  205. class NestingError(ConfigObjError):
  206. """
  207. This error indicates a level of nesting that doesn't match.
  208. """
  209. class ParseError(ConfigObjError):
  210. """
  211. This error indicates that a line is badly written.
  212. It is neither a valid ``key = value`` line,
  213. nor a valid section marker line.
  214. """
  215. class ReloadError(IOError):
  216. """
  217. A 'reload' operation failed.
  218. This exception is a subclass of ``IOError``.
  219. """
  220. def __init__(self):
  221. IOError.__init__(self, 'reload failed, filename is not set.')
  222. class DuplicateError(ConfigObjError):
  223. """
  224. The keyword or section specified already exists.
  225. """
  226. class ConfigspecError(ConfigObjError):
  227. """
  228. An error occured whilst parsing a configspec.
  229. """
  230. class InterpolationError(ConfigObjError):
  231. """Base class for the two interpolation errors."""
  232. class InterpolationLoopError(InterpolationError):
  233. """Maximum interpolation depth exceeded in string interpolation."""
  234. def __init__(self, option):
  235. InterpolationError.__init__(
  236. self,
  237. 'interpolation loop detected in value "%s".' % option)
  238. class RepeatSectionError(ConfigObjError):
  239. """
  240. This error indicates additional sections in a section with a
  241. ``__many__`` (repeated) section.
  242. """
  243. class MissingInterpolationOption(InterpolationError):
  244. """A value specified for interpolation was missing."""
  245. def __init__(self, option):
  246. InterpolationError.__init__(
  247. self,
  248. 'missing option "%s" in interpolation.' % option)
  249. class UnreprError(ConfigObjError):
  250. """An error parsing in unrepr mode."""
  251. class InterpolationEngine(object):
  252. """
  253. A helper class to help perform string interpolation.
  254. This class is an abstract base class; its descendants perform
  255. the actual work.
  256. """
  257. # compiled regexp to use in self.interpolate()
  258. _KEYCRE = re.compile(r"%\(([^)]*)\)s")
  259. def __init__(self, section):
  260. # the Section instance that "owns" this engine
  261. self.section = section
  262. def interpolate(self, key, value):
  263. def recursive_interpolate(key, value, section, backtrail):
  264. """The function that does the actual work.
  265. ``value``: the string we're trying to interpolate.
  266. ``section``: the section in which that string was found
  267. ``backtrail``: a dict to keep track of where we've been,
  268. to detect and prevent infinite recursion loops
  269. This is similar to a depth-first-search algorithm.
  270. """
  271. # Have we been here already?
  272. if backtrail.has_key((key, section.name)):
  273. # Yes - infinite loop detected
  274. raise InterpolationLoopError(key)
  275. # Place a marker on our backtrail so we won't come back here again
  276. backtrail[(key, section.name)] = 1
  277. # Now start the actual work
  278. match = self._KEYCRE.search(value)
  279. while match:
  280. # The actual parsing of the match is implementation-dependent,
  281. # so delegate to our helper function
  282. k, v, s = self._parse_match(match)
  283. if k is None:
  284. # That's the signal that no further interpolation is needed
  285. replacement = v
  286. else:
  287. # Further interpolation may be needed to obtain final value
  288. replacement = recursive_interpolate(k, v, s, backtrail)
  289. # Replace the matched string with its final value
  290. start, end = match.span()
  291. value = ''.join((value[:start], replacement, value[end:]))
  292. new_search_start = start + len(replacement)
  293. # Pick up the next interpolation key, if any, for next time
  294. # through the while loop
  295. match = self._KEYCRE.search(value, new_search_start)
  296. # Now safe to come back here again; remove marker from backtrail
  297. del backtrail[(key, section.name)]
  298. return value
  299. # Back in interpolate(), all we have to do is kick off the recursive
  300. # function with appropriate starting values
  301. value = recursive_interpolate(key, value, self.section, {})
  302. return value
  303. def _fetch(self, key):
  304. """Helper function to fetch values from owning section.
  305. Returns a 2-tuple: the value, and the section where it was found.
  306. """
  307. # switch off interpolation before we try and fetch anything !
  308. save_interp = self.section.main.interpolation
  309. self.section.main.interpolation = False
  310. # Start at section that "owns" this InterpolationEngine
  311. current_section = self.section
  312. while True:
  313. # try the current section first
  314. val = current_section.get(key)
  315. if val is not None:
  316. break
  317. # try "DEFAULT" next
  318. val = current_section.get('DEFAULT', {}).get(key)
  319. if val is not None:
  320. break
  321. # move up to parent and try again
  322. # top-level's parent is itself
  323. if current_section.parent is current_section:
  324. # reached top level, time to give up
  325. break
  326. current_section = current_section.parent
  327. # restore interpolation to previous value before returning
  328. self.section.main.interpolation = save_interp
  329. if val is None:
  330. raise MissingInterpolationOption(key)
  331. return val, current_section
  332. def _parse_match(self, match):
  333. """Implementation-dependent helper function.
  334. Will be passed a match object corresponding to the interpolation
  335. key we just found (e.g., "%(foo)s" or "$foo"). Should look up that
  336. key in the appropriate config file section (using the ``_fetch()``
  337. helper function) and return a 3-tuple: (key, value, section)
  338. ``key`` is the name of the key we're looking for
  339. ``value`` is the value found for that key
  340. ``section`` is a reference to the section where it was found
  341. ``key`` and ``section`` should be None if no further
  342. interpolation should be performed on the resulting value
  343. (e.g., if we interpolated "$$" and returned "$").
  344. """
  345. raise NotImplementedError()
  346. class ConfigParserInterpolation(InterpolationEngine):
  347. """Behaves like ConfigParser."""
  348. _KEYCRE = re.compile(r"%\(([^)]*)\)s")
  349. def _parse_match(self, match):
  350. key = match.group(1)
  351. value, section = self._fetch(key)
  352. return key, value, section
  353. class TemplateInterpolation(InterpolationEngine):
  354. """Behaves like string.Template."""
  355. _delimiter = '$'
  356. _KEYCRE = re.compile(r"""
  357. \$(?:
  358. (?P<escaped>\$) | # Two $ signs
  359. (?P<named>[_a-z][_a-z0-9]*) | # $name format
  360. {(?P<braced>[^}]*)} # ${name} format
  361. )
  362. """, re.IGNORECASE | re.VERBOSE)
  363. def _parse_match(self, match):
  364. # Valid name (in or out of braces): fetch value from section
  365. key = match.group('named') or match.group('braced')
  366. if key is not None:
  367. value, section = self._fetch(key)
  368. return key, value, section
  369. # Escaped delimiter (e.g., $$): return single delimiter
  370. if match.group('escaped') is not None:
  371. # Return None for key and section to indicate it's time to stop
  372. return None, self._delimiter, None
  373. # Anything else: ignore completely, just return it unchanged
  374. return None, match.group(), None
  375. interpolation_engines = {
  376. 'configparser': ConfigParserInterpolation,
  377. 'template': TemplateInterpolation,
  378. }
  379. def __newobj__(cls, *args):
  380. # Hack for pickle
  381. return cls.__new__(cls, *args)
  382. class Section(dict):
  383. """
  384. A dictionary-like object that represents a section in a config file.
  385. It does string interpolation if the 'interpolation' attribute
  386. of the 'main' object is set to True.
  387. Interpolation is tried first from this object, then from the 'DEFAULT'
  388. section of this object, next from the parent and its 'DEFAULT' section,
  389. and so on until the main object is reached.
  390. A Section will behave like an ordered dictionary - following the
  391. order of the ``scalars`` and ``sections`` attributes.
  392. You can use this to change the order of members.
  393. Iteration follows the order: scalars, then sections.
  394. """
  395. def __setstate__(self, state):
  396. dict.update(self, state[0])
  397. self.__dict__.update(state[1])
  398. def __reduce__(self):
  399. state = (dict(self), self.__dict__)
  400. return (__newobj__, (self.__class__,), state)
  401. def __init__(self, parent, depth, main, indict=None, name=None):
  402. """
  403. * parent is the section above
  404. * depth is the depth level of this section
  405. * main is the main ConfigObj
  406. * indict is a dictionary to initialise the section with
  407. """
  408. if indict is None:
  409. indict = {}
  410. dict.__init__(self)
  411. # used for nesting level *and* interpolation
  412. self.parent = parent
  413. # used for the interpolation attribute
  414. self.main = main
  415. # level of nesting depth of this Section
  416. self.depth = depth
  417. # purely for information
  418. self.name = name
  419. #
  420. self._initialise()
  421. # we do this explicitly so that __setitem__ is used properly
  422. # (rather than just passing to ``dict.__init__``)
  423. for entry, value in indict.iteritems():
  424. self[entry] = value
  425. def _initialise(self):
  426. # the sequence of scalar values in this Section
  427. self.scalars = []
  428. # the sequence of sections in this Section
  429. self.sections = []
  430. # for comments :-)
  431. self.comments = {}
  432. self.inline_comments = {}
  433. # the configspec
  434. self.configspec = None
  435. # for defaults
  436. self.defaults = []
  437. self.default_values = {}
  438. def _interpolate(self, key, value):
  439. try:
  440. # do we already have an interpolation engine?
  441. engine = self._interpolation_engine
  442. except AttributeError:
  443. # not yet: first time running _interpolate(), so pick the engine
  444. name = self.main.interpolation
  445. if name == True: # note that "if name:" would be incorrect here
  446. # backwards-compatibility: interpolation=True means use default
  447. name = DEFAULT_INTERPOLATION
  448. name = name.lower() # so that "Template", "template", etc. all work
  449. class_ = interpolation_engines.get(name, None)
  450. if class_ is None:
  451. # invalid value for self.main.interpolation
  452. self.main.interpolation = False
  453. return value
  454. else:
  455. # save reference to engine so we don't have to do this again
  456. engine = self._interpolation_engine = class_(self)
  457. # let the engine do the actual work
  458. return engine.interpolate(key, value)
  459. def __getitem__(self, key):
  460. """Fetch the item and do string interpolation."""
  461. val = dict.__getitem__(self, key)
  462. if self.main.interpolation and isinstance(val, basestring):
  463. return self._interpolate(key, val)
  464. return val
  465. def __setitem__(self, key, value, unrepr=False):
  466. """
  467. Correctly set a value.
  468. Making dictionary values Section instances.
  469. (We have to special case 'Section' instances - which are also dicts)
  470. Keys must be strings.
  471. Values need only be strings (or lists of strings) if
  472. ``main.stringify`` is set.
  473. ``unrepr`` must be set when setting a value to a dictionary, without
  474. creating a new sub-section.
  475. """
  476. if not isinstance(key, basestring):
  477. raise ValueError('The key "%s" is not a string.' % key)
  478. # add the comment
  479. if not self.comments.has_key(key):
  480. self.comments[key] = []
  481. self.inline_comments[key] = ''
  482. # remove the entry from defaults
  483. if key in self.defaults:
  484. self.defaults.remove(key)
  485. #
  486. if isinstance(value, Section):
  487. if not self.has_key(key):
  488. self.sections.append(key)
  489. dict.__setitem__(self, key, value)
  490. elif isinstance(value, dict) and not unrepr:
  491. # First create the new depth level,
  492. # then create the section
  493. if not self.has_key(key):
  494. self.sections.append(key)
  495. new_depth = self.depth + 1
  496. dict.__setitem__(
  497. self,
  498. key,
  499. Section(
  500. self,
  501. new_depth,
  502. self.main,
  503. indict=value,
  504. name=key))
  505. else:
  506. if not self.has_key(key):
  507. self.scalars.append(key)
  508. if not self.main.stringify:
  509. if isinstance(value, basestring):
  510. pass
  511. elif isinstance(value, (list, tuple)):
  512. for entry in value:
  513. if not isinstance(entry, basestring):
  514. raise TypeError('Value is not a string "%s".' % entry)
  515. else:
  516. raise TypeError('Value is not a string "%s".' % value)
  517. dict.__setitem__(self, key, value)
  518. def __delitem__(self, key):
  519. """Remove items from the sequence when deleting."""
  520. dict. __delitem__(self, key)
  521. if key in self.scalars:
  522. self.scalars.remove(key)
  523. else:
  524. self.sections.remove(key)
  525. del self.comments[key]
  526. del self.inline_comments[key]
  527. def get(self, key, default=None):
  528. """A version of ``get`` that doesn't bypass string interpolation."""
  529. try:
  530. return self[key]
  531. except KeyError:
  532. return default
  533. def update(self, indict):
  534. """
  535. A version of update that uses our ``__setitem__``.
  536. """
  537. for entry in indict:
  538. self[entry] = indict[entry]
  539. def pop(self, key, *args):
  540. """
  541. 'D.pop(k[,d]) -> v, remove specified key and return the corresponding value.
  542. If key is not found, d is returned if given, otherwise KeyError is raised'
  543. """
  544. val = dict.pop(self, key, *args)
  545. if key in self.scalars:
  546. del self.comments[key]
  547. del self.inline_comments[key]
  548. self.scalars.remove(key)
  549. elif key in self.sections:
  550. del self.comments[key]
  551. del self.inline_comments[key]
  552. self.sections.remove(key)
  553. if self.main.interpolation and isinstance(val, basestring):
  554. return self._interpolate(key, val)
  555. return val
  556. def popitem(self):
  557. """Pops the first (key,val)"""
  558. sequence = (self.scalars + self.sections)
  559. if not sequence:
  560. raise KeyError(": 'popitem(): dictionary is empty'")
  561. key = sequence[0]
  562. val = self[key]
  563. del self[key]
  564. return key, val
  565. def clear(self):
  566. """
  567. A version of clear that also affects scalars/sections
  568. Also clears comments and configspec.
  569. Leaves other attributes alone :
  570. depth/main/parent are not affected
  571. """
  572. dict.clear(self)
  573. self.scalars = []
  574. self.sections = []
  575. self.comments = {}
  576. self.inline_comments = {}
  577. self.configspec = None
  578. def setdefault(self, key, default=None):
  579. """A version of setdefault that sets sequence if appropriate."""
  580. try:
  581. return self[key]
  582. except KeyError:
  583. self[key] = default
  584. return self[key]
  585. def items(self):
  586. """D.items() -> list of D's (key, value) pairs, as 2-tuples"""
  587. return zip((self.scalars + self.sections), self.values())
  588. def keys(self):
  589. """D.keys() -> list of D's keys"""
  590. return (self.scalars + self.sections)
  591. def values(self):
  592. """D.values() -> list of D's values"""
  593. return [self[key] for key in (self.scalars + self.sections)]
  594. def iteritems(self):
  595. """D.iteritems() -> an iterator over the (key, value) items of D"""
  596. return iter(self.items())
  597. def iterkeys(self):
  598. """D.iterkeys() -> an iterator over the keys of D"""
  599. return iter((self.scalars + self.sections))
  600. __iter__ = iterkeys
  601. def itervalues(self):
  602. """D.itervalues() -> an iterator over the values of D"""
  603. return iter(self.values())
  604. def __repr__(self):
  605. """x.__repr__() <==> repr(x)"""
  606. return '{%s}' % ', '.join([('%s: %s' % (repr(key), repr(self[key])))
  607. for key in (self.scalars + self.sections)])
  608. __str__ = __repr__
  609. __str__.__doc__ = "x.__str__() <==> str(x)"
  610. # Extra methods - not in a normal dictionary
  611. def dict(self):
  612. """
  613. Return a deepcopy of self as a dictionary.
  614. All members that are ``Section`` instances are recursively turned to
  615. ordinary dictionaries - by calling their ``dict`` method.
  616. >>> n = a.dict()
  617. >>> n == a
  618. 1
  619. >>> n is a
  620. 0
  621. """
  622. newdict = {}
  623. for entry in self:
  624. this_entry = self[entry]
  625. if isinstance(this_entry, Section):
  626. this_entry = this_entry.dict()
  627. elif isinstance(this_entry, list):
  628. # create a copy rather than a reference
  629. this_entry = list(this_entry)
  630. elif isinstance(this_entry, tuple):
  631. # create a copy rather than a reference
  632. this_entry = tuple(this_entry)
  633. newdict[entry] = this_entry
  634. return newdict
  635. def merge(self, indict):
  636. """
  637. A recursive update - useful for merging config files.
  638. >>> a = '''[section1]
  639. ... option1 = True
  640. ... [[subsection]]
  641. ... more_options = False
  642. ... # end of file'''.splitlines()
  643. >>> b = '''# File is user.ini
  644. ... [section1]
  645. ... option1 = False
  646. ... # end of file'''.splitlines()
  647. >>> c1 = ConfigObj(b)
  648. >>> c2 = ConfigObj(a)
  649. >>> c2.merge(c1)
  650. >>> c2
  651. ConfigObj({'section1': {'option1': 'False', 'subsection': {'more_options': 'False'}}})
  652. """
  653. for key, val in indict.items():
  654. if (key in self and isinstance(self[key], dict) and
  655. isinstance(val, dict)):
  656. self[key].merge(val)
  657. else:
  658. self[key] = val
  659. def rename(self, oldkey, newkey):
  660. """
  661. Change a keyname to another, without changing position in sequence.
  662. Implemented so that transformations can be made on keys,
  663. as well as on values. (used by encode and decode)
  664. Also renames comments.
  665. """
  666. if oldkey in self.scalars:
  667. the_list = self.scalars
  668. elif oldkey in self.sections:
  669. the_list = self.sections
  670. else:
  671. raise KeyError('Key "%s" not found.' % oldkey)
  672. pos = the_list.index(oldkey)
  673. #
  674. val = self[oldkey]
  675. dict.__delitem__(self, oldkey)
  676. dict.__setitem__(self, newkey, val)
  677. the_list.remove(oldkey)
  678. the_list.insert(pos, newkey)
  679. comm = self.comments[oldkey]
  680. inline_comment = self.inline_comments[oldkey]
  681. del self.comments[oldkey]
  682. del self.inline_comments[oldkey]
  683. self.comments[newkey] = comm
  684. self.inline_comments[newkey] = inline_comment
  685. def walk(self, function, raise_errors=True,
  686. call_on_sections=False, **keywargs):
  687. """
  688. Walk every member and call a function on the keyword and value.
  689. Return a dictionary of the return values
  690. If the function raises an exception, raise the errror
  691. unless ``raise_errors=False``, in which case set the return value to
  692. ``False``.
  693. Any unrecognised keyword arguments you pass to walk, will be pased on
  694. to the function you pass in.
  695. Note: if ``call_on_sections`` is ``True`` then - on encountering a
  696. subsection, *first* the function is called for the *whole* subsection,
  697. and then recurses into it's members. This means your function must be
  698. able to handle strings, dictionaries and lists. This allows you
  699. to change the key of subsections as well as for ordinary members. The
  700. return value when called on the whole subsection has to be discarded.
  701. See the encode and decode methods for examples, including functions.
  702. .. admonition:: caution
  703. You can use ``walk`` to transform the names of members of a section
  704. but you mustn't add or delete members.
  705. >>> config = '''[XXXXsection]
  706. ... XXXXkey = XXXXvalue'''.splitlines()
  707. >>> cfg = ConfigObj(config)
  708. >>> cfg
  709. ConfigObj({'XXXXsection': {'XXXXkey': 'XXXXvalue'}})
  710. >>> def transform(section, key):
  711. ... val = section[key]
  712. ... newkey = key.replace('XXXX', 'CLIENT1')
  713. ... section.rename(key, newkey)
  714. ... if isinstance(val, (tuple, list, dict)):
  715. ... pass
  716. ... else:
  717. ... val = val.replace('XXXX', 'CLIENT1')
  718. ... section[newkey] = val
  719. >>> cfg.walk(transform, call_on_sections=True)
  720. {'CLIENT1section': {'CLIENT1key': None}}
  721. >>> cfg
  722. ConfigObj({'CLIENT1section': {'CLIENT1key': 'CLIENT1value'}})
  723. """
  724. out = {}
  725. # scalars first
  726. for i in range(len(self.scalars)):
  727. entry = self.scalars[i]
  728. try:
  729. val = function(self, entry, **keywargs)
  730. # bound again in case name has changed
  731. entry = self.scalars[i]
  732. out[entry] = val
  733. except Exception:
  734. if raise_errors:
  735. raise
  736. else:
  737. entry = self.scalars[i]
  738. out[entry] = False
  739. # then sections
  740. for i in range(len(self.sections)):
  741. entry = self.sections[i]
  742. if call_on_sections:
  743. try:
  744. function(self, entry, **keywargs)
  745. except Exception:
  746. if raise_errors:
  747. raise
  748. else:
  749. entry = self.sections[i]
  750. out[entry] = False
  751. # bound again in case name has changed
  752. entry = self.sections[i]
  753. # previous result is discarded
  754. out[entry] = self[entry].walk(
  755. function,
  756. raise_errors=raise_errors,
  757. call_on_sections=call_on_sections,
  758. **keywargs)
  759. return out
  760. def as_bool(self, key):
  761. """
  762. Accepts a key as input. The corresponding value must be a string or
  763. the objects (``True`` or 1) or (``False`` or 0). We allow 0 and 1 to
  764. retain compatibility with Python 2.2.
  765. If the string is one of ``True``, ``On``, ``Yes``, or ``1`` it returns
  766. ``True``.
  767. If the string is one of ``False``, ``Off``, ``No``, or ``0`` it returns
  768. ``False``.
  769. ``as_bool`` is not case sensitive.
  770. Any other input will raise a ``ValueError``.
  771. >>> a = ConfigObj()
  772. >>> a['a'] = 'fish'
  773. >>> a.as_bool('a')
  774. Traceback (most recent call last):
  775. ValueError: Value "fish" is neither True nor False
  776. >>> a['b'] = 'True'
  777. >>> a.as_bool('b')
  778. 1
  779. >>> a['b'] = 'off'
  780. >>> a.as_bool('b')
  781. 0
  782. """
  783. val = self[key]
  784. if val == True:
  785. return True
  786. elif val == False:
  787. return False
  788. else:
  789. try:
  790. if not isinstance(val, basestring):
  791. # TODO: Why do we raise a KeyError here?
  792. raise KeyError()
  793. else:
  794. return self.main._bools[val.lower()]
  795. except KeyError:
  796. raise ValueError('Value "%s" is neither True nor False' % val)
  797. def as_int(self, key):
  798. """
  799. A convenience method which coerces the specified value to an integer.
  800. If the value is an invalid literal for ``int``, a ``ValueError`` will
  801. be raised.
  802. >>> a = ConfigObj()
  803. >>> a['a'] = 'fish'
  804. >>> a.as_int('a')
  805. Traceback (most recent call last):
  806. ValueError: invalid literal for int() with base 10: 'fish'
  807. >>> a['b'] = '1'
  808. >>> a.as_int('b')
  809. 1
  810. >>> a['b'] = '3.2'
  811. >>> a.as_int('b')
  812. Traceback (most recent call last):
  813. ValueError: invalid literal for int() with base 10: '3.2'
  814. """
  815. return int(self[key])
  816. def as_float(self, key):
  817. """
  818. A convenience method which coerces the specified value to a float.
  819. If the value is an invalid literal for ``float``, a ``ValueError`` will
  820. be raised.
  821. >>> a = ConfigObj()
  822. >>> a['a'] = 'fish'
  823. >>> a.as_float('a')
  824. Traceback (most recent call last):
  825. ValueError: invalid literal for float(): fish
  826. >>> a['b'] = '1'
  827. >>> a.as_float('b')
  828. 1.0
  829. >>> a['b'] = '3.2'
  830. >>> a.as_float('b')
  831. 3.2000000000000002
  832. """
  833. return float(self[key])
  834. def as_list(self, key):
  835. """
  836. A convenience method which fetches the specified value, guaranteeing
  837. that it is a list.
  838. >>> a = ConfigObj()
  839. >>> a['a'] = 1
  840. >>> a.as_list('a')
  841. [1]
  842. >>> a['a'] = (1,)
  843. >>> a.as_list('a')
  844. [1]
  845. >>> a['a'] = [1]
  846. >>> a.as_list('a')
  847. [1]
  848. """
  849. result = self[key]
  850. if isinstance(result, (tuple, list)):
  851. return list(result)
  852. return [result]
  853. def restore_default(self, key):
  854. """
  855. Restore (and return) default value for the specified key.
  856. This method will only work for a ConfigObj that was created
  857. with a configspec and has been validated.
  858. If there is no default value for this key, ``KeyError`` is raised.
  859. """
  860. default = self.default_values[key]
  861. dict.__setitem__(self, key, default)
  862. if key not in self.defaults:
  863. self.defaults.append(key)
  864. return default
  865. def restore_defaults(self):
  866. """
  867. Recursively restore default values to all members
  868. that have them.
  869. This method will only work for a ConfigObj that was created
  870. with a configspec and has been validated.
  871. It doesn't delete or modify entries without default values.
  872. """
  873. for key in self.default_values:
  874. self.restore_default(key)
  875. for section in self.sections:
  876. self[section].restore_defaults()
  877. class ConfigObj(Section):
  878. """An object to read, create, and write config files."""
  879. _keyword = re.compile(r'''^ # line start
  880. (\s*) # indentation
  881. ( # keyword
  882. (?:".*?")| # double quotes
  883. (?:'.*?')| # single quotes
  884. (?:[^'"=].*?) # no quotes
  885. )
  886. \s*=\s* # divider
  887. (.*) # value (including list values and comments)
  888. $ # line end
  889. ''',
  890. re.VERBOSE)
  891. _sectionmarker = re.compile(r'''^
  892. (\s*) # 1: indentation
  893. ((?:\[\s*)+) # 2: section marker open
  894. ( # 3: section name open
  895. (?:"\s*\S.*?\s*")| # at least one non-space with double quotes
  896. (?:'\s*\S.*?\s*')| # at least one non-space with single quotes
  897. (?:[^'"\s].*?) # at least one non-space unquoted
  898. ) # section name close
  899. ((?:\s*\])+) # 4: section marker close
  900. \s*(\#.*)? # 5: optional comment
  901. $''',
  902. re.VERBOSE)
  903. # this regexp pulls list values out as a single string
  904. # or single values and comments
  905. # FIXME: this regex adds a '' to the end of comma terminated lists
  906. # workaround in ``_handle_value``
  907. _valueexp = re.compile(r'''^
  908. (?:
  909. (?:
  910. (
  911. (?:
  912. (?:
  913. (?:".*?")| # double quotes
  914. (?:'.*?')| # single quotes
  915. (?:[^'",\#][^,\#]*?) # unquoted
  916. )
  917. \s*,\s* # comma
  918. )* # match all list items ending in a comma (if any)
  919. )
  920. (
  921. (?:".*?")| # double quotes
  922. (?:'.*?')| # single quotes
  923. (?:[^'",\#\s][^,]*?)| # unquoted
  924. (?:(?<!,)) # Empty value
  925. )? # last item in a list - or string value
  926. )|
  927. (,) # alternatively a single comma - empty list
  928. )
  929. \s*(\#.*)? # optional comment
  930. $''',
  931. re.VERBOSE)
  932. # use findall to get the members of a list value
  933. _listvalueexp = re.compile(r'''
  934. (
  935. (?:".*?")| # double quotes
  936. (?:'.*?')| # single quotes
  937. (?:[^'",\#].*?) # unquoted
  938. )
  939. \s*,\s* # comma
  940. ''',
  941. re.VERBOSE)
  942. # this regexp is used for the value
  943. # when lists are switched off
  944. _nolistvalue = re.compile(r'''^
  945. (
  946. (?:".*?")| # double quotes
  947. (?:'.*?')| # single quotes
  948. (?:[^'"\#].*?)| # unquoted
  949. (?:) # Empty value
  950. )
  951. \s*(\#.*)? # optional comment
  952. $''',
  953. re.VERBOSE)
  954. # regexes for finding triple quoted values on one line
  955. _single_line_single = re.compile(r"^'''(.*?)'''\s*(#.*)?$")
  956. _single_line_double = re.compile(r'^"""(.*?)"""\s*(#.*)?$')
  957. _multi_line_single = re.compile(r"^(.*?)'''\s*(#.*)?$")
  958. _multi_line_double = re.compile(r'^(.*?)"""\s*(#.*)?$')
  959. _triple_quote = {
  960. "'''": (_single_line_single, _multi_line_single),
  961. '"""': (_single_line_double, _multi_line_double),
  962. }
  963. # Used by the ``istrue`` Section method
  964. _bools = {
  965. 'yes': True, 'no': False,
  966. 'on': True, 'off': False,
  967. '1': True, '0': False,
  968. 'true': True, 'false': False,
  969. }
  970. def __init__(self, infile=None, options=None, _inspec=False, **kwargs):
  971. """
  972. Parse a config file or create a config file object.
  973. ``ConfigObj(infile=None, options=None, **kwargs)``
  974. """
  975. self._inspec = _inspec
  976. # init the superclass
  977. Section.__init__(self, self, 0, self)
  978. infile = infile or []
  979. options = dict(options or {})
  980. # keyword arguments take precedence over an options dictionary
  981. options.update(kwargs)
  982. if _inspec:
  983. options['list_values'] = False
  984. defaults = OPTION_DEFAULTS.copy()
  985. # TODO: check the values too.
  986. for entry in options:
  987. if entry not in defaults:
  988. raise TypeError('Unrecognised option "%s".' % entry)
  989. # Add any explicit options to the defaults
  990. defaults.update(options)
  991. self._initialise(defaults)
  992. configspec = defaults['configspec']
  993. self._original_configspec = configspec
  994. self._load(infile, configspec)
  995. def _load(self, infile, configspec):
  996. if isinstance(infile, basestring):
  997. self.filename = infile
  998. if os.path.isfile(infile):
  999. h = open(infile, 'rb')
  1000. infile = h.read() or []
  1001. h.close()
  1002. elif self.file_error:
  1003. # raise an error if the file doesn't exist
  1004. raise IOError('Config file not found: "%s".' % self.filename)
  1005. else:
  1006. # file doesn't already exist
  1007. if self.create_empty:
  1008. # this is a good test that the filename specified
  1009. # isn't impossible - like on a non-existent device
  1010. h = open(infile, 'w')
  1011. h.write('')
  1012. h.close()
  1013. infile = []
  1014. elif isinstance(infile, (list, tuple)):
  1015. infile = list(infile)
  1016. elif isinstance(infile, dict):
  1017. # initialise self
  1018. # the Section class handles creating subsections
  1019. if isinstance(infile, ConfigObj):
  1020. # get a copy of our ConfigObj
  1021. infile = infile.dict()
  1022. for entry in infile:
  1023. self[entry] = infile[entry]
  1024. del self._errors
  1025. if configspec is not None:
  1026. self._handle_configspec(configspec)
  1027. else:
  1028. self.configspec = None
  1029. return
  1030. elif getattr(infile, 'read', MISSING) is not MISSING:
  1031. # This supports file like objects
  1032. infile = infile.read() or []
  1033. # needs splitting into lines - but needs doing *after* decoding
  1034. # in case it's not an 8 bit encoding
  1035. else:
  1036. raise TypeError('infile must be a filename, file like object, or list of lines.')
  1037. if infile:
  1038. # don't do it for the empty ConfigObj
  1039. infile = self._handle_bom(infile)
  1040. # infile is now *always* a list
  1041. #
  1042. # Set the newlines attribute (first line ending it finds)
  1043. # and strip trailing '\n' or '\r' from lines
  1044. for line in infile:
  1045. if (not line) or (line[-1] not in ('\r', '\n', '\r\n')):
  1046. continue
  1047. for end in ('\r\n', '\n', '\r'):
  1048. if line.endswith(end):
  1049. self.newlines = end
  1050. break
  1051. break
  1052. infile = [line.rstrip('\r\n') for line in infile]
  1053. self._parse(infile)
  1054. # if we had any errors, now is the time to raise them
  1055. if self._errors:
  1056. info = "at line %s." % self._errors[0].line_number
  1057. if len(self._errors) > 1:
  1058. msg = "Parsing failed with several errors.\nFirst error %s" % info
  1059. error = ConfigObjError(msg)
  1060. else:
  1061. error = self._errors[0]
  1062. # set the errors attribute; it's a list of tuples:
  1063. # (error_type, message, line_number)
  1064. error.errors = self._errors
  1065. # set the config attribute
  1066. error.config = self
  1067. raise error
  1068. # delete private attributes
  1069. del self._errors
  1070. if configspec is None:
  1071. self.configspec = None
  1072. else:
  1073. self._handle_configspec(configspec)
  1074. def _initialise(self, options=None):
  1075. if options is None:
  1076. options = OPTION_DEFAULTS
  1077. # initialise a few variables
  1078. self.filename = None
  1079. self._errors = []
  1080. self.raise_errors = options['raise_errors']
  1081. self.interpolation = options['interpolation']
  1082. self.list_values = options['list_values']
  1083. self.create_empty = options['create_empty']
  1084. self.file_error = options['file_error']
  1085. self.stringify = options['stringify']
  1086. self.indent_type = options['indent_type']
  1087. self.encoding = options['encoding']
  1088. self.default_encoding = options['default_encoding']
  1089. self.BOM = False
  1090. self.newlines = None
  1091. self.write_empty_values = options['write_empty_values']
  1092. self.unrepr = options['unrepr']
  1093. self.initial_comment = []
  1094. self.final_comment = []
  1095. self.configspec = None
  1096. if self._inspec:
  1097. self.list_values = False
  1098. # Clear section attributes as well
  1099. Section._initialise(self)
  1100. def __repr__(self):
  1101. return ('ConfigObj({%s})' %
  1102. ', '.join([('%s: %s' % (repr(key), repr(self[key])))
  1103. for key in (self.scalars + self.sections)]))
  1104. def _handle_bom(self, infile):
  1105. """
  1106. Handle any BOM, and decode if necessary.
  1107. If an encoding is specified, that *must* be used - but the BOM should
  1108. still be removed (and the BOM attribute set).
  1109. (If the encoding is wrongly specified, then a BOM for an alternative
  1110. encoding won't be discovered or removed.)
  1111. If an encoding is not specified, UTF8 or UTF16 BOM will be detected and
  1112. removed. The BOM attribute will be set. UTF16 will be decoded to
  1113. unicode.
  1114. NOTE: This method must not be called with an empty ``infile``.
  1115. Specifying the *wrong* encoding is likely to cause a
  1116. ``UnicodeDecodeError``.
  1117. ``infile`` must always be returned as a list of lines, but may be
  1118. passed in as a single string.
  1119. """
  1120. if ((self.encoding is not None) and
  1121. (self.encoding.lower() not in BOM_LIST)):
  1122. # No need to check for a BOM
  1123. # the encoding specified doesn't have one
  1124. # just decode
  1125. return self._decode(infile, self.encoding)
  1126. if isinstance(infile, (list, tuple)):
  1127. line = infile[0]
  1128. else:
  1129. line = infile
  1130. if self.encoding is not None:
  1131. # encoding explicitly supplied
  1132. # And it could have an associated BOM
  1133. # TODO: if encoding is just UTF16 - we ought to check for both
  1134. # TODO: big endian and little endian versions.
  1135. enc = BOM_LIST[self.encoding.lower()]
  1136. if enc == 'utf_16':
  1137. # For UTF16 we try big endian and little endian
  1138. for BOM, (encoding, final_encoding) in BOMS.items():
  1139. if not final_encoding:
  1140. # skip UTF8
  1141. continue
  1142. if infile.startswith(BOM):
  1143. ### BOM discovered
  1144. ##self.BOM = True
  1145. # Don't need to remove BOM
  1146. return self._decode(infile, encoding)
  1147. # If we get this far, will *probably* raise a DecodeError
  1148. # As it doesn't appear to start with a BOM
  1149. return self._decode(infile, self.encoding)
  1150. # Must be UTF8
  1151. BOM = BOM_SET[enc]
  1152. if not line.startswith(BOM):
  1153. return self._decode(infile, self.encoding)
  1154. newline = line[len(BOM):]
  1155. # BOM removed
  1156. if isinstance(infile, (list, tuple)):
  1157. infile[0] = newline
  1158. else:
  1159. infile = newline
  1160. self.BOM = True
  1161. return self._decode(infile, self.encoding)
  1162. # No encoding specified - so we need to check for UTF8/UTF16
  1163. for BOM, (encoding, final_encoding) in BOMS.items():
  1164. if not line.startswith(BOM):
  1165. continue
  1166. else:
  1167. # BOM discovered
  1168. self.encoding = final_encoding
  1169. if not final_encoding:
  1170. self.BOM = True
  1171. # UTF8
  1172. # remove BOM
  1173. newline = line[len(BOM):]
  1174. if isinstance(infile, (list, tuple)):
  1175. infile[0] = newline
  1176. else:
  1177. infile = newline
  1178. # UTF8 - don't decode
  1179. if isinstance(infile, basestring):
  1180. return infile.splitlines(True)
  1181. else:
  1182. return infile
  1183. # UTF16 - have to decode
  1184. return self._decode(infile, encoding)
  1185. # No BOM discovered and no encoding specified, just return
  1186. if isinstance(infile, basestring):
  1187. # infile read from a file will be a single string
  1188. return infile.splitlines(True)
  1189. return infile
  1190. def _a_to_u(self, aString):
  1191. """Decode ASCII strings to unicode if a self.encoding is specified."""
  1192. if self.encoding:
  1193. return aString.decode('ascii')
  1194. else:
  1195. return aString
  1196. def _decode(self, infile, encoding):
  1197. """
  1198. Decode infile to unicode. Using the specified encoding.
  1199. if is a string, it also needs converting to a list.
  1200. """
  1201. if isinstance(infile, basestring):
  1202. # can't be unicode
  1203. # NOTE: Could raise a ``UnicodeDecodeError``
  1204. return infile.decode(encoding).splitlines(True)
  1205. for i, line in enumerate(infile):
  1206. if not isinstance(line, unicode):
  1207. # NOTE: The isinstance test here handles mixed lists of unicode/string
  1208. # NOTE: But the decode will break on any non-string values
  1209. # NOTE: Or could raise a ``UnicodeDecodeError``
  1210. infile[i] = line.decode(encoding)
  1211. return infile
  1212. def _decode_element(self, line):
  1213. """Decode element to unicode if necessary."""
  1214. if not self.encoding:
  1215. return line
  1216. if isinstance(line, str) and self.default_encoding:
  1217. return line.decode(self.default_encoding)
  1218. return line
  1219. def _str(self, value):
  1220. """
  1221. Used by ``stringify`` within validate, to turn non-string values
  1222. into strings.
  1223. """
  1224. if not isinstance(value, basestring):
  1225. return str(value)
  1226. else:
  1227. return value
  1228. def _parse(self, infile):
  1229. """Actually parse the config file."""
  1230. temp_list_values = self.list_values
  1231. if self.unrepr:
  1232. self.list_values = False
  1233. comment_list = []
  1234. done_start = False
  1235. this_section = self
  1236. maxline = len(infile) - 1
  1237. cur_index = -1
  1238. reset_comment = False
  1239. while cur_index < maxline:
  1240. if reset_comment:
  1241. comment_list = []
  1242. cur_index += 1
  1243. line = infile[cur_index]
  1244. sline = line.strip()
  1245. # do we have anything on the line ?
  1246. if not sline or sline.startswith('#'):
  1247. reset_comment = False
  1248. comment_list.append(line)
  1249. continue
  1250. if not done_start:
  1251. # preserve initial comment
  1252. self.initial_comment = comment_list
  1253. comment_list = []
  1254. done_start = True
  1255. reset_comment = True
  1256. # first we check if it's a section marker
  1257. mat = self._sectionmarker.match(line)
  1258. if mat is not None:
  1259. # is a section line
  1260. (indent, sect_open, sect_name, sect_close, comment) = mat.groups()
  1261. if indent and (self.indent_type is None):
  1262. self.indent_type = indent
  1263. cur_depth = sect_open.count('[')
  1264. if cur_depth != sect_close.count(']'):
  1265. self._handle_error("Cannot compute the section depth at line %s.",
  1266. NestingError, infile, cur_index)
  1267. continue
  1268. if cur_depth < this_section.depth:
  1269. # the new section is dropping back to a previous level
  1270. try:
  1271. parent = self._match_depth(this_section,
  1272. cur_depth).parent
  1273. except SyntaxError:
  1274. self._handle_error("Cannot compute nesting level at line %s.",
  1275. NestingError, infile, cur_index)
  1276. continue
  1277. elif cur_depth == this_section.depth:
  1278. # the new section is a sibling of the current section
  1279. parent = this_section.parent
  1280. elif cur_depth == this_section.depth + 1:
  1281. # the new section is a child the current section
  1282. parent = this_section
  1283. else:
  1284. self._handle_error("Section too nested at line %s.",
  1285. NestingError, infile, cur_index)
  1286. sect_name = self._unquote(sect_name)
  1287. if parent.has_key(sect_name):
  1288. self._handle_error('Duplicate section name at line %s.',
  1289. DuplicateError, infile, cur_index)
  1290. continue
  1291. # create the new section
  1292. this_section = Section(
  1293. parent,
  1294. cur_depth,
  1295. self,
  1296. name=sect_name)
  1297. parent[sect_name] = this_section
  1298. parent.inline_comments[sect_name] = comment
  1299. parent.comments[sect_name] = comment_list
  1300. continue
  1301. #
  1302. # it's not a section marker,
  1303. # so it should be a valid ``key = value`` line
  1304. mat = self._keyword.match(line)
  1305. if mat is None:
  1306. # it neither matched as a keyword
  1307. # or a section marker
  1308. self._handle_error(
  1309. 'Invalid line at line "%s".',
  1310. ParseError, infile, cur_index)
  1311. else:
  1312. # is a keyword value
  1313. # value will include any inline comment
  1314. (indent, key, value) = mat.groups()
  1315. if indent and (self.indent_type is None):
  1316. self.indent_type = indent
  1317. # check for a multiline value
  1318. if value[:3] in ['"""', "'''"]:
  1319. try:
  1320. (value, comment, cur_index) = self._multiline(
  1321. value, infile, cur_index, maxline)
  1322. except SyntaxError:
  1323. self._handle_error(
  1324. 'Parse error in value at line %s.',
  1325. ParseError, infile, cur_index)
  1326. continue
  1327. else:
  1328. if self.unrepr:
  1329. comment = ''
  1330. try:
  1331. value = unrepr(value)
  1332. except Exception, e:
  1333. if type(e) == UnknownType:
  1334. msg = 'Unknown name or type in value at line %s.'
  1335. else:
  1336. msg = 'Parse error in value at line %s.'
  1337. self._handle_error(msg, UnreprError, infile,
  1338. cur_index)
  1339. continue
  1340. else:
  1341. if self.unrepr:
  1342. comment = ''
  1343. try:
  1344. value = unrepr(value)
  1345. except Exception, e:
  1346. if isinstance(e, UnknownType):
  1347. msg = 'Unknown name or type in value at line %s.'
  1348. else:
  1349. msg = 'Parse error in value at line %s.'
  1350. self._handle_error(msg, UnreprError, infile,
  1351. cur_index)
  1352. continue
  1353. else:
  1354. # extract comment and lists
  1355. try:
  1356. (value, comment) = self._handle_value(value)
  1357. except SyntaxError:
  1358. self._handle_error(
  1359. 'Parse error in value at line %s.',
  1360. ParseError, infile, cur_index)
  1361. continue
  1362. #
  1363. key = self._unquote(key)
  1364. if this_section.has_key(key):
  1365. self._handle_error(
  1366. 'Duplicate keyword name at line %s.',
  1367. DuplicateError, infile, cur_index)
  1368. continue
  1369. # add the key.
  1370. # we set unrepr because if we have got this far we will never
  1371. # be creating a new section
  1372. this_section.__setitem__(key, value, unrepr=True)
  1373. this_section.inline_comments[key] = comment
  1374. this_section.comments[key] = comment_list
  1375. continue
  1376. #
  1377. if self.indent_type is None:
  1378. # no indentation used, set the type accordingly
  1379. self.indent_type = ''
  1380. # preserve the final comment
  1381. if not self and not self.initial_comment:
  1382. self.initial_comment = comment_list
  1383. elif not reset_comment:
  1384. self.final_comment = comment_list
  1385. self.list_values = temp_list_values
  1386. def _match_depth(self, sect, depth):
  1387. """
  1388. Given a section and a depth level, walk back through the sections
  1389. parents to see if the depth level matches a previous section.
  1390. Return a reference to the right section,
  1391. or raise a SyntaxError.
  1392. """
  1393. while depth < sect.depth:
  1394. if sect is sect.parent:
  1395. # we've reached the top level already
  1396. raise SyntaxError()
  1397. sect = sect.parent
  1398. if sect.depth == depth:
  1399. return sect
  1400. # shouldn't get here
  1401. raise SyntaxError()
  1402. def _handle_error(self, text, ErrorClass, infile, cur_index):
  1403. """
  1404. Handle an error according to the error settings.
  1405. Either raise the error or store it.
  1406. The error will have occured at ``cur_index``
  1407. """
  1408. line = infile[cur_index]
  1409. cur_index += 1
  1410. message = text % cur_index
  1411. error = ErrorClass(message, cur_index, line)
  1412. if self.raise_errors:
  1413. # raise the error - parsing stops here
  1414. raise error
  1415. # store the error
  1416. # reraise when parsing has finished
  1417. self._errors.append(error)
  1418. def _unquote(self, value):
  1419. """Return an unquoted version of a value"""
  1420. if (value[0] == value[-1]) and (value[0] in ('"', "'")):
  1421. value = value[1:-1]
  1422. return value
  1423. def _quote(self, value, multiline=True):
  1424. """
  1425. Return a safely quoted version of a value.
  1426. Raise a ConfigObjError if the value cannot be safely quoted.
  1427. If multiline is ``True`` (default) then use triple quotes
  1428. if necessary.
  1429. * Don't quote values that don't need it.
  1430. * Recursively quote members of a list and return a comma joined list.
  1431. * Multiline is ``False`` for lists.
  1432. * Obey list syntax for empty and single member lists.
  1433. If ``list_values=False`` then the value is only quoted if it contains
  1434. a ``\\n`` (is multiline) or '#'.
  1435. If ``write_empty_values`` is set, and the value is an empty string, it
  1436. won't be quoted.
  1437. """
  1438. if multiline and self.write_empty_values and value == '':
  1439. # Only if multiline is set, so that it is used for values not
  1440. # keys, and not values that are part of a list
  1441. return ''
  1442. if multiline and isinstance(value, (list, tuple)):
  1443. if not value:
  1444. return ','
  1445. elif len(value) == 1:
  1446. return self._quote(value[0], multiline=False) + ','
  1447. return ', '.join([self._quote(val, multiline=False)
  1448. for val in value])
  1449. if not isinstance(value, basestring):
  1450. if self.stringify:
  1451. value = str(value)
  1452. else:
  1453. raise TypeError('Value "%s" is not a string.' % value)
  1454. if not value:
  1455. return '""'
  1456. no_lists_no_quotes = not self.list_values and '\n' not in value and '#' not in value
  1457. need_triple = multiline and ((("'" in value) and ('"' in value)) or ('\n' in value ))
  1458. hash_triple_quote = multiline and not need_triple and ("'" in value) and ('"' in value) and ('#' in value)
  1459. check_for_single = (no_lists_no_quotes or not need_triple) and not hash_triple_quote
  1460. if check_for_single:
  1461. if not self.list_values:
  1462. # we don't quote if ``list_values=False``
  1463. quot = noquot
  1464. # for normal values either single or double quotes will do
  1465. elif '\n' in value:
  1466. # will only happen if multiline is off - e.g. '\n' in key
  1467. raise ConfigObjError('Value "%s" cannot be safely quoted.' % value)
  1468. elif ((value[0] not in wspace_plus) and
  1469. (value[-1] not in wspace_plus) and
  1470. (',' not in value)):
  1471. quot = noquot
  1472. else:
  1473. quot = self._get_single_quote(value)
  1474. else:
  1475. # if value has '\n' or "'" *and* '"', it will need triple quotes
  1476. quot = self._get_triple_quote(value)
  1477. if quot == noquot and '#' in value and self.list_values:
  1478. quot = self._get_single_quote(value)
  1479. return quot % value
  1480. def _get_single_quote(self, value):
  1481. if ("'" in value) and ('"' in value):
  1482. raise ConfigObjError('Value "%s" cannot be safely quoted.' % value)
  1483. elif '"' in value:
  1484. quot = squot
  1485. else:
  1486. quot = dquot
  1487. return quot
  1488. def _get_triple_quote(self, value):
  1489. if (value.find('"""') != -1) and (value.find("'''") != -1):
  1490. raise ConfigObjError('Value "%s" cannot be safely quoted.' % value)
  1491. if value.find('"""') == -1:
  1492. quot = tdquot
  1493. else:
  1494. quot = tsquot
  1495. return quot
  1496. def _handle_value(self, value):
  1497. """
  1498. Given a value string, unquote, remove comment,
  1499. handle lists. (including empty and single member lists)
  1500. """
  1501. if self._inspec:
  1502. # Parsing a configspec so don't handle comments
  1503. return (value, '')
  1504. # do we look for lists in values ?
  1505. if not self.list_values:
  1506. mat = self._nolistvalue.match(value)
  1507. if mat is None:
  1508. raise SyntaxError()
  1509. # NOTE: we don't unquote here
  1510. return mat.groups()
  1511. #
  1512. mat = self._valueexp.match(value)
  1513. if mat is None:
  1514. # the value is badly constructed, probably badly quoted,
  1515. # or an invalid list
  1516. raise SyntaxError()
  1517. (list_values, single, empty_list, comment) = mat.groups()
  1518. if (list_values == '') and (single is None):
  1519. # change this if you want to accept empty values
  1520. raise SyntaxError()
  1521. # NOTE: note there is no error handling from here if the regex
  1522. # is wrong: then incorrect values will slip through
  1523. if empty_list is not None:
  1524. # the single comma - meaning an empty list
  1525. return ([], comment)
  1526. if single is not None:
  1527. # handle empty values
  1528. if list_values and not single:
  1529. # FIXME: the '' is a workaround because our regex now matches
  1530. # '' at the end of a list if it has a trailing comma
  1531. single = None
  1532. else:
  1533. single = single or '""'
  1534. single = self._unquote(single)
  1535. if list_values == '':
  1536. # not a list value
  1537. return (single, comment)
  1538. the_list = self._listvalueexp.findall(list_values)
  1539. the_list = [self._unquote(val) for val in the_list]
  1540. if single is not None:
  1541. the_list += [single]
  1542. return (the_list, comment)
  1543. def _multiline(self, value, infile, cur_index, maxline):
  1544. """Extract the value, where we are in a multiline situation."""
  1545. quot = value[:3]
  1546. newvalue = value[3:]
  1547. single_line = self._triple_quote[quot][0]
  1548. multi_line = self._triple_quote[quot][1]
  1549. mat = single_line.match(value)
  1550. if mat is not None:
  1551. retval = list(mat.groups())
  1552. retval.append(cur_index)
  1553. return retval
  1554. elif newvalue.find(quot) != -1:
  1555. # somehow the triple quote is missing
  1556. raise SyntaxError()
  1557. #
  1558. while cur_index < maxline:
  1559. cur_index += 1
  1560. newvalue += '\n'
  1561. line = infile[cur_index]
  1562. if line.find(quot) == -1:
  1563. newvalue += line
  1564. else:
  1565. # end of multiline, process it
  1566. break
  1567. else:
  1568. # we've got to the end of the config, oops...
  1569. raise SyntaxError()
  1570. mat = multi_line.match(line)
  1571. if mat is None:
  1572. # a badly formed line
  1573. raise SyntaxError()
  1574. (value, comment) = mat.groups()
  1575. return (newvalue + value, comment, cur_index)
  1576. def _handle_configspec(self, configspec):
  1577. """Parse the configspec."""
  1578. # FIXME: Should we check that the configspec was created with the
  1579. # correct settings ? (i.e. ``list_values=False``)
  1580. if not isinstance(configspec, ConfigObj):
  1581. try:
  1582. configspec = ConfigObj(configspec,
  1583. raise_errors=True,
  1584. file_error=True,
  1585. _inspec=True)
  1586. except ConfigObjError, e:
  1587. # FIXME: Should these errors have a reference
  1588. # to the already parsed ConfigObj ?
  1589. raise ConfigspecError('Parsing configspec failed: %s' % e)
  1590. except IOError, e:
  1591. raise IOError('Reading configspec failed: %s' % e)
  1592. self.configspec = configspec
  1593. def _set_configspec(self, section, copy):
  1594. """
  1595. Called by validate. Handles setting the configspec on subsections
  1596. including sections to be validated by __many__
  1597. """
  1598. configspec = section.configspec
  1599. many = configspec.get('__many__')
  1600. if isinstance(many, dict):
  1601. for entry in section.sections:
  1602. if entry not in configspec:
  1603. section[entry].configspec = many
  1604. for entry in configspec.sections:
  1605. if entry == '__many__':
  1606. continue
  1607. if entry not in section:
  1608. section[entry] = {}
  1609. if copy:
  1610. # copy comments
  1611. section.comments[entry] = configspec.comments.get(entry, [])
  1612. section.inline_comments[entry] = configspec.inline_comments.get(entry, '')
  1613. # Could be a scalar when we expect a section
  1614. if isinstance(section[entry], Section):
  1615. section[entry].configspec = configspec[entry]
  1616. def _write_line(self, indent_string, entry, this_entry, comment):
  1617. """Write an individual line, for the write method"""
  1618. # NOTE: the calls to self._quote here handles non-StringType values.
  1619. if not self.unrepr:
  1620. val = self._decode_element(self._quote(this_entry))
  1621. else:
  1622. val = repr(this_entry)
  1623. return '%s%s%s%s%s' % (indent_string,
  1624. self._decode_element(self._quote(entry, multiline=False)),
  1625. self._a_to_u(' = '),
  1626. val,
  1627. self._decode_element(comment))
  1628. def _write_marker(self, indent_string, depth, entry, comment):
  1629. """Write a section marker line"""
  1630. return '%s%s%s%s%s' % (indent_string,
  1631. self._a_to_u('[' * depth),
  1632. self._quote(self._decode_element(entry), multiline=False),
  1633. self._a_to_u(']' * depth),
  1634. self._decode_element(comment))
  1635. def _handle_comment(self, comment):
  1636. """Deal with a comment."""
  1637. if not comment:
  1638. return ''
  1639. start = self.indent_type
  1640. if not comment.startswith('#'):
  1641. start += self._a_to_u(' # ')
  1642. return (start + comment)
  1643. # Public methods
  1644. def write(self, outfile=None, section=None):
  1645. """
  1646. Write the current ConfigObj as a file
  1647. tekNico: FIXME: use StringIO instead of real files
  1648. >>> filename = a.filename
  1649. >>> a.filename = 'test.ini'
  1650. >>> a.write()
  1651. >>> a.filename = filename
  1652. >>> a == ConfigObj('test.ini', raise_errors=True)
  1653. 1
  1654. """
  1655. if self.indent_type is None:
  1656. # this can be true if initialised from a dictionary
  1657. self.indent_type = DEFAULT_INDENT_TYPE
  1658. out = []
  1659. cs = self._a_to_u('#')
  1660. csp = self._a_to_u('# ')
  1661. if section is None:
  1662. int_val = self.interpolation
  1663. self.interpolation = False
  1664. section = self
  1665. for line in self.initial_comment:
  1666. line = self._decode_element(line)
  1667. stripped_line = line.strip()
  1668. if stripped_line and not stripped_line.startswith(cs):
  1669. line = csp + line
  1670. out.append(line)
  1671. indent_string = self.indent_type * section.depth
  1672. for entry in (section.scalars + section.sections):
  1673. if entry in section.defaults:
  1674. # don't write out default values
  1675. continue
  1676. for comment_line in section.comments[entry]:
  1677. comment_line = self._decode_element(comment_line.lstrip())
  1678. if comment_line and not comment_line.startswith(cs):
  1679. comment_line = csp + comment_line
  1680. out.append(indent_string + comment_line)
  1681. this_entry = section[entry]
  1682. comment = self._handle_comment(section.inline_comments[entry])
  1683. if isinstance(this_entry, dict):
  1684. # a section
  1685. out.append(self._write_marker(
  1686. indent_string,
  1687. this_entry.depth,
  1688. entry,
  1689. comment))
  1690. out.extend(self.write(section=this_entry))
  1691. else:
  1692. out.append(self._write_line(
  1693. indent_string,
  1694. entry,
  1695. this_entry,
  1696. comment))
  1697. if section is self:
  1698. for line in self.final_comment:
  1699. line = self._decode_element(line)
  1700. stripped_line = line.strip()
  1701. if stripped_line and not stripped_line.startswith(cs):
  1702. line = csp + line
  1703. out.append(line)
  1704. self.interpolation = int_val
  1705. if section is not self:
  1706. return out
  1707. if (self.filename is None) and (outfile is None):
  1708. # output a list of lines
  1709. # might need to encode
  1710. # NOTE: This will *screw* UTF16, each line will start with the BOM
  1711. if self.encoding:
  1712. out = [l.encode(self.encoding) for l in out]
  1713. if (self.BOM and ((self.encoding is None) or
  1714. (BOM_LIST.get(self.encoding.lower()) == 'utf_8'))):
  1715. # Add the UTF8 BOM
  1716. if not out:
  1717. out.append('')
  1718. out[0] = BOM_UTF8 + out[0]
  1719. return out
  1720. # Turn the list to a string, joined with correct newlines
  1721. newline = self.newlines or os.linesep
  1722. output = self._a_to_u(newline).join(out)
  1723. if self.encoding:
  1724. output = output.encode(self.encoding)
  1725. if self.BOM and ((self.encoding is None) or match_utf8(self.encoding)):
  1726. # Add the UTF8 BOM
  1727. output = BOM_UTF8 + output
  1728. if not output.endswith(newline):
  1729. output += newline
  1730. if outfile is not None:
  1731. outfile.write(output)
  1732. else:
  1733. h = open(self.filename, 'wb')
  1734. h.write(output)
  1735. h.close()
  1736. def validate(self, validator, preserve_errors=False, copy=False,
  1737. section=None):
  1738. """
  1739. Test the ConfigObj against a configspec.
  1740. It uses the ``validator`` object from *validate.py*.
  1741. To run ``validate`` on the current ConfigObj, call: ::
  1742. test = config.validate(validator)
  1743. (Normally having previously passed in the configspec when the ConfigObj
  1744. was created - you can dynamically assign a dictionary of checks to the
  1745. ``configspec`` attribute of a section though).
  1746. It returns ``True`` if everything passes, or a dictionary of
  1747. pass/fails (True/False). If every member of a subsection passes, it
  1748. will just have the value ``True``. (It also returns ``False`` if all
  1749. members fail).
  1750. In addition, it converts the values from strings to their native
  1751. types if their checks pass (and ``stringify`` is set).
  1752. If ``preserve_errors`` is ``True`` (``False`` is default) then instead
  1753. of a marking a fail with a ``False``, it will preserve the actual
  1754. exception object. This can contain info about the reason for failure.
  1755. For example the ``VdtValueTooSmallError`` indicates that the value
  1756. supplied was too small. If a value (or section) is missing it will
  1757. still be marked as ``False``.
  1758. You must have the validate module to use ``preserve_errors=True``.
  1759. You can then use the ``flatten_errors`` function to turn your nested
  1760. results dictionary into a flattened list of failures - useful for
  1761. displaying meaningful error messages.
  1762. """
  1763. if section is None:
  1764. if self.configspec is None:
  1765. raise ValueError('No configspec supplied.')
  1766. if preserve_errors:
  1767. # We do this once to remove a top level dependency on the validate module
  1768. # Which makes importing configobj faster
  1769. from validate import VdtMissingValue
  1770. self._vdtMissingValue = VdtMissingValue
  1771. section = self
  1772. if copy:
  1773. section.initial_comment = section.configspec.initial_comment
  1774. section.final_comment = section.configspec.final_comment
  1775. section.encoding = section.configspec.encoding
  1776. section.BOM = section.configspec.BOM
  1777. section.newlines = section.configspec.newlines
  1778. section.indent_type = section.configspec.indent_type
  1779. #
  1780. configspec = section.configspec
  1781. self._set_configspec(section, copy)
  1782. def validate_entry(entry, spec, val, missing, ret_true, ret_false):
  1783. try:
  1784. check = validator.check(spec,
  1785. val,
  1786. missing=missing
  1787. )
  1788. except validator.baseErrorClass, e:
  1789. if not preserve_errors or isinstance(e, self._vdtMissingValue):
  1790. out[entry] = False
  1791. else:
  1792. # preserve the error
  1793. out[entry] = e
  1794. ret_false = False
  1795. ret_true = False
  1796. else:
  1797. try:
  1798. section.default_values.pop(entry, None)
  1799. except AttributeError:
  1800. # For Python 2.2 compatibility
  1801. try:
  1802. del section.default_values[entry]
  1803. except KeyError:
  1804. pass
  1805. try:
  1806. section.default_values[entry] = validator.get_default_value(configspec[entry])
  1807. except (KeyError, AttributeError):
  1808. # No default or validator has no 'get_default_value' (e.g. SimpleVal)
  1809. pass
  1810. ret_false = False
  1811. out[entry] = True
  1812. if self.stringify or missing:
  1813. # if we are doing type conversion
  1814. # or the value is a supplied default
  1815. if not self.stringify:
  1816. if isinstance(check, (list, tuple)):
  1817. # preserve lists
  1818. check = [self._str(item) for item in check]
  1819. elif missing and check is None:
  1820. # convert the None from a default to a ''
  1821. check = ''
  1822. else:
  1823. check = self._str(check)
  1824. if (check != val) or missing:
  1825. section[entry] = check
  1826. if not copy and missing and entry not in section.defaults:
  1827. section.defaults.append(entry)
  1828. return ret_true, ret_false
  1829. #
  1830. out = {}
  1831. ret_true = True
  1832. ret_false = True
  1833. unvalidated = [k for k in section.scalars if k not in configspec]
  1834. incorrect_sections = [k for k in configspec.sections if k in section.scalars]
  1835. incorrect_scalars = [k for k in configspec.scalars if k in section.sections]
  1836. for entry in configspec.scalars:
  1837. if entry in ('__many__', '___many___'):
  1838. # reserved names
  1839. continue
  1840. if (not entry in section.scalars) or (entry in section.defaults):
  1841. # missing entries
  1842. # or entries from defaults
  1843. missing = True
  1844. val = None
  1845. if copy and not entry in section.scalars:
  1846. # copy comments
  1847. section.comments[entry] = (
  1848. configspec.comments.get(entry, []))
  1849. section.inline_comments[entry] = (
  1850. configspec.inline_comments.get(entry, ''))
  1851. #
  1852. else:
  1853. missing = False
  1854. val = section[entry]
  1855. ret_true, ret_false = validate_entry(entry, configspec[entry], val,
  1856. missing, ret_true, ret_false)
  1857. many = None
  1858. if '__many__' in configspec.scalars:
  1859. many = configspec['__many__']
  1860. elif '___many___' in configspec.scalars:
  1861. many = configspec['___many___']
  1862. if many is not None:
  1863. for entry in unvalidated:
  1864. val = section[entry]
  1865. ret_true, ret_false = validate_entry(entry, many, val, False,
  1866. ret_true, ret_false)
  1867. for entry in incorrect_scalars:
  1868. ret_true = False
  1869. if not preserve_errors:
  1870. out[entry] = False
  1871. else:
  1872. ret_false = False
  1873. msg = 'Value %r was provided as a section' % entry
  1874. out[entry] = validator.baseErrorClass(msg)
  1875. for entry in incorrect_sections:
  1876. ret_true = False
  1877. if not preserve_errors:
  1878. out[entry] = False
  1879. else:
  1880. ret_false = False
  1881. msg = 'Section %r was provided as a single value' % entry
  1882. out[entry] = validator.baseErrorClass(msg)
  1883. # Missing sections will have been created as empty ones when the
  1884. # configspec was read.
  1885. for entry in section.sections:
  1886. # FIXME: this means DEFAULT is not copied in copy mode
  1887. if section is self and entry == 'DEFAULT':
  1888. continue
  1889. if section[entry].configspec is None:
  1890. continue
  1891. if copy:
  1892. section.comments[entry] = configspec.comments.get(entry, [])
  1893. section.inline_comments[entry] = configspec.inline_comments.get(entry, '')
  1894. check = self.validate(validator, preserve_errors=preserve_errors, copy=copy, section=section[entry])
  1895. out[entry] = check
  1896. if check == False:
  1897. ret_true = False
  1898. elif check == True:
  1899. ret_false = False
  1900. else:
  1901. ret_true = False
  1902. ret_false = False
  1903. #
  1904. if ret_true:
  1905. return True
  1906. elif ret_false:
  1907. return False
  1908. return out
  1909. def reset(self):
  1910. """Clear ConfigObj instance and restore to 'freshly created' state."""
  1911. self.clear()
  1912. self._initialise()
  1913. # FIXME: Should be done by '_initialise', but ConfigObj constructor (and reload)
  1914. # requires an empty dictionary
  1915. self.configspec = None
  1916. # Just to be sure ;-)
  1917. self._original_configspec = None
  1918. def reload(self):
  1919. """
  1920. Reload a ConfigObj from file.
  1921. This method raises a ``ReloadError`` if the ConfigObj doesn't have
  1922. a filename attribute pointing to a file.
  1923. """
  1924. if not isinstance(self.filename, basestring):
  1925. raise ReloadError()
  1926. filename = self.filename
  1927. current_options = {}
  1928. for entry in OPTION_DEFAULTS:
  1929. if entry == 'configspec':
  1930. continue
  1931. current_options[entry] = getattr(self, entry)
  1932. configspec = self._original_configspec
  1933. current_options['configspec'] = configspec
  1934. self.clear()
  1935. self._initialise(current_options)
  1936. self._load(filename, configspec)
  1937. class SimpleVal(object):
  1938. """
  1939. A simple validator.
  1940. Can be used to check that all members expected are present.
  1941. To use it, provide a configspec with all your members in (the value given
  1942. will be ignored). Pass an instance of ``SimpleVal`` to the ``validate``
  1943. method of your ``ConfigObj``. ``validate`` will return ``True`` if all
  1944. members are present, or a dictionary with True/False meaning
  1945. present/missing. (Whole missing sections will be replaced with ``False``)
  1946. """
  1947. def __init__(self):
  1948. self.baseErrorClass = ConfigObjError
  1949. def check(self, check, member, missing=False):
  1950. """A dummy check method, always returns the value unchanged."""
  1951. if missing:
  1952. raise self.baseErrorClass()
  1953. return member
  1954. # Check / processing functions for options
  1955. def flatten_errors(cfg, res, levels=None, results=None):
  1956. """
  1957. An example function that will turn a nested dictionary of results
  1958. (as returned by ``ConfigObj.validate``) into a flat list.
  1959. ``cfg`` is the ConfigObj instance being checked, ``res`` is the results
  1960. dictionary returned by ``validate``.
  1961. (This is a recursive function, so you shouldn't use the ``levels`` or
  1962. ``results`` arguments - they are used by the function.)
  1963. Returns a list of keys that failed. Each member of the list is a tuple :
  1964. ::
  1965. ([list of sections...], key, result)
  1966. If ``validate`` was called with ``preserve_errors=False`` (the default)
  1967. then ``result`` will always be ``False``.
  1968. *list of sections* is a flattened list of sections that the key was found
  1969. in.
  1970. If the section was missing (or a section was expected and a scalar provided
  1971. - or vice-versa) then key will be ``None``.
  1972. If the value (or section) was missing then ``result`` will be ``False``.
  1973. If ``validate`` was called with ``preserve_errors=True`` and a value
  1974. was present, but failed the check, then ``result`` will be the exception
  1975. object returned. You can use this as a string that describes the failure.
  1976. For example *The value "3" is of the wrong type*.
  1977. >>> import validate
  1978. >>> vtor = validate.Validator()
  1979. >>> my_ini = '''
  1980. ... option1 = True
  1981. ... [section1]
  1982. ... option1 = True
  1983. ... [section2]
  1984. ... another_option = Probably
  1985. ... [section3]
  1986. ... another_option = True
  1987. ... [[section3b]]
  1988. ... value = 3
  1989. ... value2 = a
  1990. ... value3 = 11
  1991. ... '''
  1992. >>> my_cfg = '''
  1993. ... option1 = boolean()
  1994. ... option2 = boolean()
  1995. ... option3 = boolean(default=Bad_value)
  1996. ... [section1]
  1997. ... option1 = boolean()
  1998. ... option2 = boolean()
  1999. ... option3 = boolean(default=Bad_value)
  2000. ... [section2]
  2001. ... another_option = boolean()
  2002. ... [section3]
  2003. ... another_option = boolean()
  2004. ... [[section3b]]
  2005. ... value = integer
  2006. ... value2 = integer
  2007. ... value3 = integer(0, 10)
  2008. ... [[[section3b-sub]]]
  2009. ... value = string
  2010. ... [section4]
  2011. ... another_option = boolean()
  2012. ... '''
  2013. >>> cs = my_cfg.split('\\n')
  2014. >>> ini = my_ini.split('\\n')
  2015. >>> cfg = ConfigObj(ini, configspec=cs)
  2016. >>> res = cfg.validate(vtor, preserve_errors=True)
  2017. >>> errors = []
  2018. >>> for entry in flatten_errors(cfg, res):
  2019. ... section_list, key, error = entry
  2020. ... section_list.insert(0, '[root]')
  2021. ... if key is not None:
  2022. ... section_list.append(key)
  2023. ... else:
  2024. ... section_list.append('[missing]')
  2025. ... section_string = ', '.join(section_list)
  2026. ... errors.append((section_string, ' = ', error))
  2027. >>> errors.sort()
  2028. >>> for entry in errors:
  2029. ... print entry[0], entry[1], (entry[2] or 0)
  2030. [root], option2 = 0
  2031. [root], option3 = the value "Bad_value" is of the wrong type.
  2032. [root], section1, option2 = 0
  2033. [root], section1, option3 = the value "Bad_value" is of the wrong type.
  2034. [root], section2, another_option = the value "Probably" is of the wrong type.
  2035. [root], section3, section3b, section3b-sub, [missing] = 0
  2036. [root], section3, section3b, value2 = the value "a" is of the wrong type.
  2037. [root], section3, section3b, value3 = the value "11" is too big.
  2038. [root], section4, [missing] = 0
  2039. """
  2040. if levels is None:
  2041. # first time called
  2042. levels = []
  2043. results = []
  2044. if res is True:
  2045. return results
  2046. if res is False or isinstance(res, Exception):
  2047. results.append((levels[:], None, res))
  2048. if levels:
  2049. levels.pop()
  2050. return results
  2051. for (key, val) in res.items():
  2052. if val == True:
  2053. continue
  2054. if isinstance(cfg.get(key), dict):
  2055. # Go down one level
  2056. levels.append(key)
  2057. flatten_errors(cfg[key], val, levels, results)
  2058. continue
  2059. results.append((levels[:], key, val))
  2060. #
  2061. # Go up one level
  2062. if levels:
  2063. levels.pop()
  2064. #
  2065. return results
  2066. """*A programming language is a medium of expression.* - Paul Graham"""