Package grizzled :: Module config :: Class Configuration

Class Configuration

ConfigParser.RawConfigParser --+        
                               |        
       ConfigParser.ConfigParser --+    
                                   |    
       ConfigParser.SafeConfigParser --+
                                       |
                                      Configuration

Configuration file parser. See the module documentation for details.

Instance Methods

__init__(self, defaults=None, permit_includes=True, use_ordered_sections=False, strict_substitution=False)
Construct a new Configuration object.

dict

defaults(self)
Returns the instance-wide defaults.

sections(self)
Get the list of available sections, not including DEFAULT.

add_section(self, section)
Add a section named section to the instance.

bool

has_section(self, section)
Determine whether a section exists in the configuration.

list

options(self, section)
Get a list of options available in the specified section.

bool

has_option(self, section, option)
Determine whether a section has a specific option.

list

read(self, filenames)
Attempt to read and parse a list of filenames or URLs, returning a list of filenames or URLs which were successfully parsed.

readfp(self, fp, filename=None)
Read and parse configuration data from a file or file-like object.

str

get(self, section, option, optional=False)
Get an option from a section.

int

getint(self, section, option, optional=False)
Convenience method that coerces the result of a call to get() to an int.

float

getfloat(self, section, option, optional=False)
Convenience method that coerces the result of a call to get() to a float.

bool

getboolean(self, section, option, optional=False)
Convenience method that coerces the result of a call to get() to a boolean.

bool

getlist(self, section, option, sep=None, optional=False)
Convenience method that coerces the result of a call to get() to a list.

str

get_one_of(self, section, options, optional=False, default=None, value_type=str)
Retrieve at most one of a list or set of options from a section.

list

items(self, section)
Get all items in a section.

set(self, section, option, value)
If the given section exists, set the given option to the specified value; otherwise raise NoSectionError.

write(self, fileobj)
Write a representation of the configuration to the specified file-like object.

remove_section(self, section)
Remove a section from the instance.

optionxform(self, option_name)
Transforms the option name in option_name as found in an input file or as passed in by client code to the form that should be used in the internal structures.

Inherited from ConfigParser.RawConfigParser: remove_option

Class Variables
Inherited from `ConfigParser.RawConfigParser`: `OPTCRE`, `SECTCRE`

Method Details

init(self, defaults=None, permit_includes=True, use_ordered_sections=False, strict_substitution=False)
(Constructor)

Construct a new Configuration object.

Parameters:

defaults (dict) - dictionary of default values
permit_includes (bool) - whether or not to permit includes
use_ordered_sections (bool) - whether or not to use an ordered dictionary for the section names. If True, then a call to sections() will return the sections in the order they were encountered in the file. If False, the order is based on the hash keys for the sections' names.
strict_substitution (bool) - If True, then throw an exception if attempting to substitute a non-existent variable. Otherwise, simple substitute an empty value.

Overrides: ConfigParser.RawConfigParser.__init__

defaults(self)

Returns the instance-wide defaults.

Returns: dict: the instance-wide defaults, or None if there aren't any
Overrides: ConfigParser.RawConfigParser.defaults

sections(self)

Get the list of available sections, not including DEFAULT. It's not really useful to call this method before calling read() or readfp().

Returns a list of sections.

Decorators:

@property

Overrides: ConfigParser.RawConfigParser.sections

add_section(self, section)

Add a section named section to the instance. If a section by the given name already exists, DuplicateSectionError is raised.

Parameters:

section (str) - name of section to add

Raises:

DuplicateSectionError - section already exists

Overrides: ConfigParser.RawConfigParser.add_section

has_section(self, section)

Determine whether a section exists in the configuration. Ignores the DEFAULT section.

Parameters:

section (str) - name of section

Returns: bool

True if the section exists in the configuration, False if not.

Overrides: ConfigParser.RawConfigParser.has_section

options(self, section)

Get a list of options available in the specified section.

Parameters:

section (str) - name of section

Returns: list

list of available options. May be empty.

Raises:

NoSectionError - no such section

Overrides: ConfigParser.RawConfigParser.options

has_option(self, section, option)

Determine whether a section has a specific option.

Parameters:

section (str) - name of section
option (str) - name of option to check

Returns: bool

True if the section exists in the configuration and has the specified option, False if not.

Overrides: ConfigParser.RawConfigParser.has_option

read(self, filenames)

Attempt to read and parse a list of filenames or URLs, returning a list of filenames or URLs which were successfully parsed. If filenames is a string or Unicode string, it is treated as a single filename or URL. If a file or URL named in filenames cannot be opened, that file will be ignored. This is designed so that you can specify a list of potential configuration file locations (for example, the current directory, the user's home directory, and some system-wide directory), and all existing configuration files in the list will be read. If none of the named files exist, the Configuration instance will contain an empty dataset. An application which requires initial values to be loaded from a file should load the required file or files using readfp() before calling read() for any optional files:

import Configuration
import os

config = Configuration.Configuration()
config.readfp(open('defaults.cfg'))
config.read(['site.cfg', os.path.expanduser('~/.myapp.cfg')])

Parameters:

filenames (list or string) - list of file names or URLs, or the string for a single filename or URL

Returns: list

list of successfully parsed filenames or URLs

Overrides: ConfigParser.RawConfigParser.read

readfp(self, fp, filename=None)

Read and parse configuration data from a file or file-like object. (Only the readline() moethod is used.)

Parameters:

fp (file) - File-like object with a readline() method
filename (str) - Name associated with fp, for error messages. If omitted or None, then fp.name is used. If fp has no name attribute, then "<???"> is used.

Overrides: ConfigParser.RawConfigParser.readfp

get(self, section, option, optional=False)

Get an option from a section.

Parameters:

section (str) - name of section
option (str) - name of option to check
optional (bool) - True to return None if the option doesn't exist. False to throw an exception if the option doesn't exist.

Returns: str

the option value

Raises:

NoSectionError - no such section
NoOptionError - no such option in the section

Overrides: ConfigParser.RawConfigParser.get

getint(self, section, option, optional=False)

Convenience method that coerces the result of a call to get() to an int.

Parameters:

section (str) - name of section
option (str) - name of option to check
optional (bool) - True to return None if the option doesn't exist. False to throw an exception if the option doesn't exist.

Returns: int

the option value

Raises:

NoSectionError - no such section
NoOptionError - no such option in the section

Overrides: ConfigParser.RawConfigParser.getint

getfloat(self, section, option, optional=False)

Convenience method that coerces the result of a call to get() to a float.

Parameters:

section (str) - name of section
option (str) - name of option to check
optional (bool) - True to return None if the option doesn't exist. False to throw an exception if the option doesn't exist.

Returns: float

the option value

Raises:

NoSectionError - no such section
NoOptionError - no such option in the section

Overrides: ConfigParser.RawConfigParser.getfloat

getboolean(self, section, option, optional=False)

Convenience method that coerces the result of a call to get() to a boolean. Accepted boolean values are "1", "yes", "true", and "on", which cause this method to return True, and "0", "no", "false", and "off", which cause it to return False. These string values are checked in a case-insensitive manner. Any other value will cause it to raise ValueError.

:Parameters:a

section : str: name of section
option : str: name of option to check
optional : bool: True to return None if the option doesn't exist. False to throw an exception if the option doesn't exist.

Returns: bool

the option value (True or False)

Raises:

NoSectionError - no such section
NoOptionError - no such option in the section
ValueError - non-boolean value encountered

Overrides: ConfigParser.RawConfigParser.getboolean

getlist(self, section, option, sep=None, optional=False)

Convenience method that coerces the result of a call to get() to a list. The value is split using the separator(s) specified by the sep argument. A sep value of None uses white space. The result is a list of string values.

Parameters:

section (str) - name of section
option (str) - name of option to check
sep (str) - list element separator to use. Defaults to white space.
optional (bool) - True to return None if the option doesn't exist. False to throw an exception if the option doesn't exist.

Returns: bool

the option value (True or False)

Raises:

NoSectionError - no such section
NoOptionError - no such option in the section

get_one_of(self, section, options, optional=False, default=None, value_type=str)

Retrieve at most one of a list or set of options from a section. This method is useful if there are multiple possible names for a single option. For example, suppose you permit either a user_name or a login_name option, but not both, in a section called credentials. You can use the following code to retrieve the option value:

from grizzled.config import Configuration

config = Configuration()
config.read('/path/to/config')
user = config.get_one_of('credentials', ['user_name', 'login_name'])

If both options exist, get_one_of() will a NoOptionError. If neither option exists, get_one_of() will throw a NoOptionError if optional is False and there's no default value; otherwise, it will return the default value.

Parameters:

section (str) - name of section
options (list or set) - list or set of allowable option names
optional (bool) - True to return None if the option doesn't exist. False to throw an exception if the option doesn't exist.
default (str) - The default value, if the option does not exist.
value_type (type) - The type to which to coerce the value. The value is coerced by casting.

Returns: str

the option value, or None if nonexistent and optional is True

Raises:

NoSectionError - no such section
NoOptionError - none of the named options are in the section

items(self, section)

Get all items in a section.

Parameters:

section (str) - name of section

Returns: list

a list of (name, value) tuples for each option in in section

Raises:

NoSectionError - no such section

Overrides: ConfigParser.RawConfigParser.items

set(self, section, option, value)

If the given section exists, set the given option to the specified value; otherwise raise NoSectionError.

Parameters:

section (str) - name of section
option (str) - name of option to check
value (str) - the value to set

Raises:

NoSectionError - no such section

Overrides: ConfigParser.RawConfigParser.set

write(self, fileobj)

Write a representation of the configuration to the specified file-like object. This output can be parsed by a future read() call.

NOTE: Includes and variable references are not reconstructed. That is, the configuration data is written in expanded form.

Parameters:

fileobj (file) - file-like object to which to write the configuration

Overrides: ConfigParser.RawConfigParser.write

remove_section(self, section)

Remove a section from the instance. If a section by the given name does not exist, NoSectionError is raised.

Parameters:

section (str) - name of section to remove

Raises:

NoSectionError - no such section

Overrides: ConfigParser.RawConfigParser.remove_section

optionxform(self, option_name)

Transforms the option name in option_name as found in an input file or as passed in by client code to the form that should be used in the internal structures. The default implementation returns a lower-case version of option_name; subclasses may override this or client code can set an attribute of this name on instances to affect this behavior. Setting this to str(), for example, would make option names case sensitive.

Overrides: ConfigParser.RawConfigParser.optionxform

Class Configuration

__init__(self, defaults=None, permit_includes=True, use_ordered_sections=False, strict_substitution=False) (Constructor)

defaults(self)

sections(self)

add_section(self, section)

has_section(self, section)

options(self, section)

has_option(self, section, option)

read(self, filenames)

readfp(self, fp, filename=None)

get(self, section, option, optional=False)

getint(self, section, option, optional=False)

getfloat(self, section, option, optional=False)

getboolean(self, section, option, optional=False)

getlist(self, section, option, sep=None, optional=False)

get_one_of(self, section, options, optional=False, default=None, value_type=str)

items(self, section)

set(self, section, option, value)

write(self, fileobj)

remove_section(self, section)

optionxform(self, option_name)

init(self, defaults=None, permit_includes=True, use_ordered_sections=False, strict_substitution=False)
(Constructor)