API Reference for Enthought Tool Suite 2.7.1

Mix of Traits and ConfigObj.

Provides:

- Coupling a Traits object to a ConfigObj one, so that changes to the Traited
  instance propagate back into the ConfigObj.

- A declarative interface for describing configurations that automatically maps
  to valid ConfigObj representations.

- From these descriptions, valid .conf files can be auto-generated, with class
  docstrings and traits information used for initial auto-documentation.

- Hierarchical inclusion of files, so that a base config can be overridden only
  in specific spots.

- Automatic GUI editing of configuration objects.


Notes:

The file creation policy is:

1. Creating a TConfigManager(FooConfig,'missingfile.conf')  will work
fine, and 'missingfile.conf' will be created empty.

2. Creating TConfigManager(FooConfig,'OKfile.conf') where OKfile.conf has

include = 'missingfile.conf'

conks out with IOError.

My rationale is that creating top-level empty files is a common and
reasonable need, but that having invalid include statements should
raise an error right away, so people know immediately that their files
have gone stale.


TODO:

  - Turn the currently interactive tests into proper doc/unit tests.  Complete
    docstrings. 

  - Write the real ipython1 config system using this.  That one is more
  complicated than either the MPL one or the fake 'ipythontest' that I wrote
  here, and it requires solving the issue of declaring references to other
  objects inside the config files.

  - [Low priority] Write a custom TraitsUI view so that hierarchical
  configurations provide nicer interactive editing.  The automatic system is
  remarkably good, but for very complex configurations having a nicely
  organized view would be nice.

Variables

• nullConf

  nullConf = mkConfigObj(None)
  
  

Classes

• RecursiveConfigObj - Object-oriented interface for recursive ConfigObj constructions.
• TConfig - A class representing configuration objects
• TConfigError
• TConfigInvalidKeyError
• TConfigManager - A simple object to manage and sync a TConfig and a ConfigObj pair.

Function summary

• comment(strng, indent = '')
• configObj2Str(cobj)
• dedent(txt)
• filter_scalars(sc)
• fmonitor(fconf)
• get_instance_sections(inst)
• get_scalars(obj)
• get_sections(obj, sectionClass)
• getConfigFilename(conf)
• mkConfigObj(filename, makeMissingFile = True)
• partition_instance(obj)
• path_to_root(obj)
• set_value(fconf, path, key, value)
• short_str(txt, line_length = 80, max_lines = 6)
• tconf2File(tconf, fname, force = False)

Functions

• comment(strng, indent = '')

  return an input string, commented out

• configObj2Str(cobj)

  Dump a Configobj instance to a string.

• dedent(txt)

  A modified version of textwrap.dedent, specialized for docstrings.

  This version doesn't get confused by the first line of text having inconsistent indentation from the rest, which happens a lot in docstrings.

  Examples:	>>> s = ''' ... First line. ... More... ... End''' >>> print dedent(s) First line. More... End >>> s = '''First line ... More... ... End''' >>> print dedent(s) First line More... End

• filter_scalars(sc)

  input sc MUST be sorted!!!

• fmonitor(fconf)

  Make a monitor for coupling TConfig instances to ConfigObj ones.

  We must use a closure because Traits makes assumptions about the functions used with on_trait_change() that prevent the use of a callable instance.

• get_instance_sections(inst)

  Return sections for a TConf instance

• get_scalars(obj)

  Return scalars for a TConf class object

• get_sections(obj, sectionClass)

  Return sections for a TConf class object

• getConfigFilename(conf)

  Find the filename attribute of a ConfigObj given a sub-section object.

• mkConfigObj(filename, makeMissingFile = True)

  Return a ConfigObj instance with our hardcoded conventions.

  Use a simple factory that wraps our option choices for using ConfigObj. I'm hard-wiring certain choices here, so we'll always use instances with THESE choices.

  Parameters:	filename : string File to read from.
  Keywords:	makeMissingFile : bool (True) If true, the file named by filename may not yet exist and it will be automatically created (empty). Else, if filename doesn't exist, an IOError will be raised.

• partition_instance(obj)

  Return scalars,sections for a given TConf instance.

• path_to_root(obj)

  Find the path to the root of a nested TConfig instance.

• set_value(fconf, path, key, value)

  Set a value on a ConfigObj instance, arbitrarily deep.

• short_str(txt, line_length = 80, max_lines = 6)

  Shorten a text input if necessary.

• tconf2File(tconf, fname, force = False)

  Write a TConfig instance to a given filename.

  Keywords:	force : bool (False) If true, force writing even if the file exists.

Imported Names

Copyright © 2002-2008 Enthought, Inc.