Core API

Parser

coil.parse(string, **kwargs)

Parse a coil string.

See Parser for possible keyword arguments.

Parameters:file_name (str) – String containing data to parse. Returns:The root object. Return type:Struct

coil.parse_file(file_name, **kwargs)

Open and parse a coil file.

See Parser for possible keyword arguments.

Parameters:file_name (str) – Name of file to parse. Returns:The root object. Return type:Struct

class coil.parser.Parser(input_, path=None, encoding=None, expand=True, defaults=(), ignore_missing=(), ignore_types=(), permissive=False)

Bases: object

The standard coil parser.

Parameters:

• input – An iterator over lines of input. Typically a file object or list of strings.
• path – Path to input file, used for errors and @file imports.
• encoding – Read strings using the given encoding. All string values will be unicode objects rather than str.
• expand – Enables/disables expansion of the parsed tree.
• defaults – See Struct.expanditem
• ignore_missing – See Struct.expanditem
• ignore_types – See Struct.expanditem
• permissive – Disable some validation checks. Currently this just includes checking for double-setting atrributes.

root()

Get the root Struct.

Return type:Struct

prototype()

Get the raw unexpanded prototype, you probably don’t want this.

Return type:StructPrototype

Struct

class coil.struct.Struct(base=(), container=None, name=None, location=None)

Bases: coil.tokenizer.Location, UserDict.DictMixin

A dict-like object for use in trees.

Parameters:

• base – A dict, Struct, or a sequence of (key, value) pairs to initialize with. Any child dict or Struct will be recursively copied.
• container – the parent Struct if there is one.
• name – The name of this Struct in its container.
• location – The where this Struct is defined. This is normally only used by the Parser.

keep

Signal set() to preserve location data for key

get(path, default=<object object at 0x7f83c1725370>)

Get a value from any Struct in the tree.

Parameters:

• path – key or arbitrary path to fetch.
• default – return this value if item is missing. Note that the behavior here differs from a dict. If default is unspecified and missing a KeyMissingError will be raised as __getitem__ does, not return None.

Returns:

The fetched item or the value of default.

set(path, value, location=None)

Set a value in any Struct in the tree.

Parameters:

• path – key or arbitrary path to set.
• value – value to save.
• location – defines where this value was defined. Set to Struct.keep to not modify the location if it is already set, this is used by expanditem().

merge(other)

Recursively merge a coil Struct tree.

This is similar to update() except that it will update the entire subtree rather than just this object.

keys()

Get an ordered list of keys.

attributes()

Alias for keys().

Only for compatibility with Coil <= 0.2.2.

has_key(key)

True if key is in this Struct

iteritems()

Iterate over the ordered list of (key, value) pairs.

sort(cmp=None, reverse=False)

Sort in place. By default items are sorted by key.

Alternate sort methods may be provided by giving a custom cmp method. The arguments to cmp will be (key, value) pairs.

expand(defaults=(), ignore_missing=(), recursive=True, ignore_types=(), _block=())

Expand all Link and sub-string variables in this and, if recursion is enabled, all child Struct objects. This is normally called during parsing but may be useful if more control is required.

This method modifies the tree!

Parameters:

• defaults – See expandvalue()
• ignore_missing – expandvalue()
• recursive (bool) – recursively expand sub-structs
• ignore_types – expandvalue()
• _block – See expandvalue()

expanditem(path, defaults=(), ignore_missing=(), ignore_types=(), _block=())

Fetch and expand an item at the given path. All Link and sub-string variables will be followed in the process. This method is a no-op if value is a Struct, use the Struct.expand() method instead.

This method does not make any changes to the tree.

Parameters:

• path – A key or arbitrary path to get.
• defaults – See expandvalue()
• ignore_missing – See expandvalue()
• ignore_types – expandvalue()
• _block – See expandvalue()

expandvalue(value, defaults=(), ignore_missing=(), ignore_types=(), _block=())

Use this Struct to expand the given value. All Link and sub-string variables will be followed in the process. This method is a no-op if value is a Struct, use the expand() method instead.

This method does not make any changes to the tree.

Parameters:

• value – Any value to expand, typically a Link or string.
• defaults (dict) – default values to use if undefined.
• ignore_missing (True or any container) – a set of keys that are ignored if undefined and not in defaults. If simply set to True then all are ignored. Otherwise raise KeyMissingError.
• ignore_types (container of strings) –

  a set of types that should be ignored during expansion. Possible values in the set are:

  • ‘strings’: Don’t expand ${foo} references in strings.
  • ‘links’: Don’t follow links, leaves the Link object.

  More values will be added in the future.

• _block – a set of absolute paths that cannot be expanded. This is only for use internally to avoid circular references.

unexpanded(absolute=False, recursive=True)

Find a set of all keys that have not been expanded. This is generally only useful if expand() was run with the ignore_missing parameter was set to see got missed.

Normally only the short key name is given as it would be provided in defaults or ignore_missing parameters for the various expansion methods. Set absolute=True to return the full path for each key instead.

Parameters:

• absolute (bool) – Enables absolute paths.
• recursive (bool) – recursively search sub-structs

Returns:

unexpanded keys

Return type:

set

copy()

Recursively copy this Struct

dict()

Recursively copy this Struct into dict objects

path(path=None)

Get the absolute path of this Struct if path is None, otherwise the relative path from this Struct to the given path.

string(strict=True, prefix='')

Convert this Struct tree to the coil text format.

Note that if any value is a unicode string then this will return a unicode object rather than a str.

Parameters:

• strict (bool) – If True then fail if the tree contains any values that cannot be represented in the coil text format.
• prefix (string) – Start each line with the given prefix. Used internally to properly intend sub-structs.

flatten(strict=True, prefix='', path='')

Alternate version of Struct.string() that generates a flat key: value list rather than a Struct tree. This is equally as valid as the standard format and sometimes is easier to read.

Parameters:

• strict (bool) – If True then fail if the tree contains any values that cannot be represented in the coil text format.
• prefix (string) – Start each line with the given prefix.
• path – path to prefix each key with. Used for recursion.

Type :

string

classmethod validate_key(key)

Check if the given key is valid.

Return type:bool

classmethod validate_path(path)

Check if the given path is valid.

Return type:bool

clear()

items()

iterkeys()

itervalues()

pop(key, *args)

popitem()

setdefault(key, default=None)

update(other=None, **kwargs)

values()

Errors

exception coil.errors.CoilError(location, reason)

Bases: exceptions.Exception

Generic error for Coil

location(location)

Update the parser location for this exception. This is useful for properly tagging StructError instances that are raised during parse time.

exception coil.errors.StructError(struct, reason)

Bases: coil.errors.CoilError

Generic error for coil.struct.Struct objects, used by various Key errors.

exception coil.errors.KeyMissingError(struct, key)

Bases: coil.errors.StructError, exceptions.KeyError

The given key was not found

exception coil.errors.KeyTypeError(struct, key)

Bases: coil.errors.StructError, exceptions.TypeError

The given key was not a string

exception coil.errors.KeyValueError(struct, key)

Bases: coil.errors.StructError, exceptions.ValueError

The given key contained invalid characters

exception coil.errors.ValueTypeError(struct, key, item_type, need_type)

Bases: coil.errors.StructError

The given item in a path was not the correct type

exception coil.errors.CoilParseError(location, reason)

Bases: coil.errors.CoilError

General error during parsing

exception coil.errors.CoilUnicodeError(location, reason)

Bases: coil.errors.CoilParseError

Invalid unicode string