===================================== ``grail.misc.iniconfigparser`` module ===================================== .. include:: ..\version.h .. include:: ref.h .. contents:: Table of Contents :backlinks: top ----------- Description ----------- Provides a simpler interface for the Python built-in ConfigParser module [#python-lib-configparser]_. The :c:`ConfigParser` module in python is a very powerful module, however if you just wish to store and retrieve values, and maybe provide some default values, the :c:`ConfigParser` tends to be rather heavy weight. This module allows you to create, read and write to an INI file in a convenient easy to use way. As an example, consider you want to save "ore" features, that maybe a user has set within your script. You want to have these values available from run-to-run of your script, but you also wish to provide a nice to read format for the user to edit. In this case the INI file structure is ideal. .. Python:: from grail.misc import iniconfigparser ini = iniconfigparser.IniConfigParser() ini.read("myini.ini") ini.set("ore", "start-cu", ".23") ini.set("ort", "start-au", ".301") Later you can retrieve those values from the file via, .. Python:: start_value = ini.get("ore", "start-cu", default="0.0") If the "start-cu" option is not within the "ore" section, the default value will be returned. .. Note:: Its important to know that :c:`IniConfigParser` isa :c:`ConfigParser` object. In other words the :c:`IniConfigParser` inherits form the :c:`ConfigParser`. Its just a specialized version that has its :f:`get()` and :f:`set()` method logic overridden. The remaining logic for a :c:`ConfigParser` is still available. --------------------- IniConfigParser Class --------------------- class :dc:`IniConfigParser([iscase])` A specialized :c:`ConfigParser` object. Basically provides some additional methods to the :c:`ConfigParser` methods to help make working with an extremely simple INI file much easier. This object has its :f:`set()` or :f:`get()` method overridden to allow a INI file to flesh itself out when you insert attributes that do not exist. For example, when using the :f:`get()` method you can provide a default value that is used if we can not locate the existing option/section. As another example, consider that the :f:`set()` method will generate a section if the section you specify did not exist. Finally, note that the :c:`ConfigParser` object provides the ability to specify default values. To simply this object, default values where left out. If you wish to have that behavior use the :c:`ConfigParser` object. Argument: :a:`iscase` : integer Indicate if you wish to be case sensitive in compares or not. :df:`get(section, option[, default])` Retrieves the value for the option with in the given section. Allows you to optionally provide a default value, which is inserted into the INI file on write. You can read an INI file like this, :: [section] option = value Leading whitespace is removed from the value. Arguments: :a:`section` : string Name of the section in the INI file. :a:`option` : string Name of an option within the section. :a:`default` : string Value to use if we can not find the option (uses a blank string). Returns: Either the value in the given section's option or the value specified by default. .. Note:: If the value is not defined, then the default value will be assigned to the option. When you write the contents to a file via :f:`write()`, this will write the default value to the file. :df:`set(section, option, value)` Sets a value for a given section's option. You can read the INI file and the parameters for this method as, :: [section] option = value Arguments: :a:`section` : string Name of the section in the INI file. :a:`option` : string Name of an option within the section. :a:`value` : string Value you wish to insert for that option. .. Note:: If the section is not already in the INI file it will be created. All other methods defined for this object are the same as the :c:`ConfigParser` object [#python-lib-configparser]_. ---- .. [#python-lib-configparser] *Python Library*. "ConfigParser -- Configuration file parser". 30 May 2003. 3 June 2004.