@@ -333,3 +333,90 @@ The :class:`SafeConfigParser` class implements the same extended interface as
333333 otherwise raise :exc: `NoSectionError `. *value * must be a string (:class: `str `
334334 or :class: `unicode `); if not, :exc: `TypeError ` is raised.
335335
336+
337+ Examples
338+ --------
339+
340+ An example of writing to a configuration file::
341+
342+ import ConfigParser
343+
344+ config = ConfigParser.RawConfigParser()
345+
346+ # When adding sections or items, add them in the reverse order of
347+ # how you want them to be displayed in the actual file.
348+ # In addition, please note that using RawConfigParser's and the raw
349+ # mode of ConfigParser's respective set functions, you can assign
350+ # non-string values to keys internally, but will receive an error
351+ # when attempting to write to a file or when you get it in non-raw
352+ # mode. SafeConfigParser does not allow such assignments to take place.
353+ config.add_section('Section1')
354+ config.set('Section1', 'int', '15')
355+ config.set('Section1', 'bool', 'true')
356+ config.set('Section1', 'float', '3.1415')
357+ config.set('Section1', 'baz', 'fun')
358+ config.set('Section1', 'bar', 'Python')
359+ config.set('Section1', 'foo', '%(bar)s is %(baz)s!')
360+
361+ # Writing our configuration file to 'example.cfg'
362+ with open('example.cfg', 'wb') as configfile:
363+ config.write(configfile)
364+
365+ An example of reading the configuration file again::
366+
367+ import ConfigParser
368+
369+ config = ConfigParser.RawConfigParser()
370+ config.read('example.cfg')
371+
372+ # getfloat() raises an exception if the value is not a float
373+ # getint() and getboolean() also do this for their respective types
374+ float = config.getfloat('Section1', 'float')
375+ int = config.getint('Section1', 'int')
376+ print float + int
377+
378+ # Notice that the next output does not interpolate '%(bar)s' or '%(baz)s'.
379+ # This is because we are using a RawConfigParser().
380+ if config.getboolean('Section1', 'bool'):
381+ print config.get('Section1', 'foo')
382+
383+ To get interpolation, you will need to use a :class: `ConfigParser ` or
384+ :class: `SafeConfigParser `::
385+
386+ import ConfigParser
387+
388+ config = ConfigParser.ConfigParser()
389+ config.read('example.cfg')
390+
391+ # Set the third, optional argument of get to 1 if you wish to use raw mode.
392+ print config.get('Section1', 'foo', 0) # -> "Python is fun!"
393+ print config.get('Section1', 'foo', 1) # -> "%(bar)s is %(baz)s!"
394+
395+ # The optional fourth argument is a dict with members that will take
396+ # precedence in interpolation.
397+ print config.get('Section1', 'foo', 0, {'bar': 'Documentation',
398+ 'baz': 'evil'})
399+
400+ Defaults are available in all three types of ConfigParsers. They are used in
401+ interpolation if an option used is not defined elsewhere. ::
402+
403+ import ConfigParser
404+
405+ # New instance with 'bar' and 'baz' defaulting to 'Life' and 'hard' each
406+ config = ConfigParser.SafeConfigParser({'bar': 'Life', 'baz': 'hard'})
407+ config.read('example.cfg')
408+
409+ print config.get('Section1', 'foo') # -> "Python is fun!"
410+ config.remove_option('Section1', 'bar')
411+ config.remove_option('Section1', 'baz')
412+ print config.get('Section1', 'foo') # -> "Life is hard!"
413+
414+ The function ``opt_move `` below can be used to move options between sections::
415+
416+ def opt_move(config, section1, section2, option):
417+ try:
418+ config.set(section2, option, config.get(section1, option, 1))
419+ except ConfigParser.NoSectionError:
420+ # Create non-existent section
421+ config.add_section(section2)
422+ opt_move(config, section1, section2, option)
0 commit comments