Python Modules

Here is the documentation of some of the python modules:

SDshelllib

SDshellibTxt

implements the interactive layer of StructuredData.

StructuredData.SDshelllib.addpaths(path1, path2, formatspec='')[source]

combines paths according to the rules.

StructuredData.SDshelllib.combinepaths(paths, formatspec='')[source]

combines paths according to the rules.

StructuredData.SDshelllib.error(exception, st)[source]

print an error message.

StructuredData.SDshelllib.find(pattern, formatspec='', paths=None, sdc=None)[source]

return paths and values for a given pattern.

find links for a pattern.

StructuredData.SDshelllib.findval(value, formatspec='', pattern=None, paths=None, sdc=None)[source]

return paths and values for a given value.

StructuredData.SDshelllib.format(val, formatspec='')[source]

formats a value according to the given format.

StructuredData.SDshelllib.get(pattern, formatspec='', paths=None, sdc=None)[source]

get a part of the structure for a given pattern.

return links for a path.

StructuredData.SDshelllib.h(item=None, level=None)

implement the shell’s help function.

StructuredData.SDshelllib.help(item=None, level=None)[source]

implement the shell’s help function.

StructuredData.SDshelllib.ifind(pattern, formatspec='', paths=None, sdc=None)[source]

return paths and values for a given “i”-pattern.

StructuredData.SDshelllib.ifindval(val_pattern, formatspec='', pattern=None, paths=None, sdc=None)[source]

return paths and values for a value matching an “i”-pattern.

StructuredData.SDshelllib.internal_find(type_, pattern, path_list=None, formatspec='', sdc=None)[source]

internal find function.

This is used to cover several flavours of find functions.

StructuredData.SDshelllib.internal_findval(type_, val_pattern, pattern=None, path_list=None, formatspec='', sdc=None)[source]

internal findval function.

This is used to cover several flavours of findval functions.

StructuredData.SDshelllib.joinpath(keys, formatspec='')[source]

splits a path according to the rules.

StructuredData.SDshelllib.p(formatspec='', pattern=None, sdc=None)

generic print to the console.

StructuredData.SDshelllib.pathkey2string(pk)[source]

convert a list of keys to a path (string).

StructuredData.SDshelllib.paths(pattern='*', formatspec='', paths=None, sdc=None)[source]

returns a list of all matching paths in a StructuredDataContainer.

StructuredData.SDshelllib.poppath(path, formatspec='', no=1)[source]

removes parts of a path from the end.

StructuredData.SDshelllib.pr(formatspec='', pattern=None, sdc=None)[source]

generic print to the console.

StructuredData.SDshelllib.r(filename=None, formatspec='', sdc=None)

generic read from file.

If bool(sdc) is False, use the global SDC variable. Note: this function does not create a new StructuredDataStore, use newsdc() if you want to create a new one.

returns:
sdc
StructuredData.SDshelllib.read(filename=None, formatspec='', sdc=None)[source]

generic read from file.

If bool(sdc) is False, use the global SDC variable. Note: this function does not create a new StructuredDataStore, use newsdc() if you want to create a new one.

returns:
sdc
StructuredData.SDshelllib.rewrite(formatspec='', pattern=None, sdc=None)[source]

write the StructuredData back to the file.

StructuredData.SDshelllib.rw(formatspec='', pattern=None, sdc=None)

write the StructuredData back to the file.

StructuredData.SDshelllib.rxfind(pattern, formatspec='', paths=None, sdc=None)[source]

return paths and values for a given regexp.

StructuredData.SDshelllib.rxfindval(val_pattern, formatspec='', pattern=None, paths=None, sdc=None)[source]

return paths and values for a value matching a regexp.

StructuredData.SDshelllib.splitpath(path, formatspec='')[source]

splits a path according to the rules.

StructuredData.SDshelllib.string2pathkey(st)[source]

convert a path (string) to a list of keys.

StructuredData.SDshelllib.substpath(path, pattern, formatspec='')[source]

removes parts of a path from the end.

StructuredData.SDshelllib.typecheck(sdc=None)[source]

perform a typecheck on the StructuredDataContainer.

StructuredData.SDshelllib.typefind(pattern, formatspec='', sdc=None)[source]

find a type for a pattern.

StructuredData.SDshelllib.typeget(path, formatspec='', sdc=None)[source]

get a type for a path.

StructuredData.SDshelllib.typematch(path, formatspec='', sdc=None)[source]

try to find a typecheck for the given path.

StructuredData.SDshelllib.typepaths(pattern='*', formatspec='', sdc=None)[source]

find typepaths for a pattern.

StructuredData.SDshelllib.w(filename=None, formatspec='', pattern=None, sdc=None)

generic write to a file.

StructuredData.SDshelllib.write(filename=None, formatspec='', pattern=None, sdc=None)[source]

generic write to a file.

SDshelllibTxt

SDshellibTxt

implements the text layer of StructuredData.

StructuredData.SDshelllibTxt.addpaths(path1, path2, formatspec='')[source]

combines paths according to the rules.

StructuredData.SDshelllibTxt.combinepaths(paths, formatspec='')[source]

combines paths according to the rules.

StructuredData.SDshelllibTxt.find(pattern, formatspec='', paths=None, sdc=None)[source]

return paths and values for a given pattern.

find links for a pattern.

StructuredData.SDshelllibTxt.findval(value, formatspec='', pattern=None, paths=None, sdc=None)[source]

return paths and values for a given value.

StructuredData.SDshelllibTxt.format(val, formatspec='')[source]

formats a value according to the given format.

StructuredData.SDshelllibTxt.get(pattern, formatspec='', paths=None, sdc=None)[source]

get a part of the structure for a given pattern.

return links for a path.

StructuredData.SDshelllibTxt.ifind(pattern, formatspec='', paths=None, sdc=None)[source]

return paths and values for a given “i”-pattern.

StructuredData.SDshelllibTxt.ifindval(val_pattern, formatspec='', pattern=None, paths=None, sdc=None)[source]

return paths and values for a value matching an “i”-pattern.

StructuredData.SDshelllibTxt.internal_find(type_, pattern, path_list=None, formatspec='', sdc=None)[source]

internal find function.

This is used to cover several flavours of find functions.

StructuredData.SDshelllibTxt.internal_findval(type_, val_pattern, pattern=None, path_list=None, formatspec='', sdc=None)[source]

internal findval function.

This is used to cover several flavours of findval functions.

StructuredData.SDshelllibTxt.joinpath(keys, formatspec='')[source]

joins a path according to the rules.

StructuredData.SDshelllibTxt.paths(pattern='*', formatspec='', paths=None, sdc=None)[source]

returns a list of all matching paths in a StructuredDataContainer.

StructuredData.SDshelllibTxt.poppath(path, formatspec='', no=1)[source]

removes parts of a path from the end.

StructuredData.SDshelllibTxt.rxfind(pattern, formatspec='', paths=None, sdc=None)[source]

return paths and values for a given regexp.

StructuredData.SDshelllibTxt.rxfindval(val_pattern, formatspec='', pattern=None, paths=None, sdc=None)[source]

return paths and values for a value matching a regexp.

StructuredData.SDshelllibTxt.splitpath(path, formatspec='')[source]

splits a path according to the rules.

StructuredData.SDshelllibTxt.substpath(path, pattern, formatspec='')[source]

removes parts of a path from the end.

StructuredData.SDshelllibTxt.typefind(pattern, formatspec='', sdc=None)[source]

find a type for a pattern.

StructuredData.SDshelllibTxt.typeget(path, formatspec='', sdc=None)[source]

get a type for a path.

StructuredData.SDshelllibTxt.typematch(path, formatspec='', sdc=None)[source]

try to find a typecheck for the given path.

StructuredData.SDshelllibTxt.typepaths(pattern='*', formatspec='', sdc=None)[source]

find typepaths for a pattern.

SDshelllibFun

SDshellibFun

implements the functional layer of StructuredData.

StructuredData.SDshelllibFun.SDtype()[source]

return the software stack on which we are running.

StructuredData.SDshelllibFun.addpaths(path1, path2)[source]

combine 2 paths. One may be a list of paths.

StructuredData.SDshelllibFun.change(path, value, sdc=None)[source]

changes a single value.

StructuredData.SDshelllibFun.clear_store(sdc=None)[source]

clear the store of a StructuredDataContainer.

StructuredData.SDshelllibFun.clear_types(sdc=None)[source]

clear the types of a StructuredDataContainer.

StructuredData.SDshelllibFun.combinepaths(paths)[source]

combine partial paths to a new one.

StructuredData.SDshelllibFun.copy(sdc=None)[source]

returns a copy of a StructuredDataContainer.

StructuredData.SDshelllibFun.delete(path, sdc=None)[source]

delete a single value.

StructuredData.SDshelllibFun.error(exception, st)[source]

raise an exception (why is this needed?).

StructuredData.SDshelllibFun.filter_out(pattern, sdc=None)[source]

returns a filtered StructuredDataContainer.

StructuredData.SDshelllibFun.find(pattern, show_links=False, paths=None, sdc=None)[source]

return paths and values for a given pattern.

find links for a pattern.

StructuredData.SDshelllibFun.findval(value, show_links=False, pattern=None, paths=None, sdc=None)[source]

return paths and values for a given value.

StructuredData.SDshelllibFun.get(pattern, show_links=False, paths=None, sdc=None)[source]

get a part of the structure for a given pattern.

return links for a path.

StructuredData.SDshelllibFun.global_sym(name)[source]

return a global symbol of the given name.

StructuredData.SDshelllibFun.help(item=None, level=None)[source]

implement the shell’s help function.

StructuredData.SDshelllibFun.ifind(pattern, show_links=False, paths=None, sdc=None)[source]

return paths and values for a given “i”-pattern.

StructuredData.SDshelllibFun.ifindval(val_pattern, show_links=False, pattern=None, paths=None, sdc=None)[source]

return paths and values for a value matching an “i”-pattern.

StructuredData.SDshelllibFun.internal_find(type_, pattern, show_links=False, path_list=None, sdc=None)[source]

internal find function.

This is used to cover several flavours of find functions.

StructuredData.SDshelllibFun.internal_findval(type_, val_pattern, show_links=False, pattern=None, path_list=None, sdc=None)[source]

internal findval function.

This is used to cover several flavours of findval functions.

StructuredData.SDshelllibFun.joinpath(keys)[source]

joins a path according to the rules.

create a link to an existing value at another path.

StructuredData.SDshelllibFun.lockdir(dirname)[source]

define a directory read-only.

StructuredData.SDshelllibFun.lockfile(filename)[source]

define a filename read-only.

StructuredData.SDshelllibFun.locksdc(sdc)[source]

make the sdc read-only.

StructuredData.SDshelllibFun.namedsdc(arg=None)[source]

create a new StructuredDataContainer-Key.

here an sdc-key and an sdc-object are identical.

StructuredData.SDshelllibFun.newsdc()[source]

create a new StructuredDataContainer-Key.

StructuredData.SDshelllibFun.pathkey2string(pk)[source]

unapply escaping rules on ‘.’,’[‘,’]’ in pk.

StructuredData.SDshelllibFun.paths(pattern='*', paths=None, sdc=None)[source]

returns a list of all matching paths in a StructuredDataContainer.

StructuredData.SDshelllibFun.poppath(path, no=1)[source]

removes parts of a path from the end.

StructuredData.SDshelllibFun.put(path, value, sdc=None)[source]

add a single value.

StructuredData.SDshelllibFun.read(filename=None, formatspec='', sdc=None)[source]

generic read from file.

If bool(sdc) is False, use the global SDC variable. Note: this function does not create a new StructuredDataStore, use newsdc() if you want to create a new one.

returns:
(sdc, list_of_read_files)

refresh the internal link cache.

StructuredData.SDshelllibFun.rxfind(pattern, show_links=False, paths=None, sdc=None)[source]

return paths and values for a given regexp.

StructuredData.SDshelllibFun.rxfindval(val_pattern, show_links=False, pattern=None, paths=None, sdc=None)[source]

return paths and values for a value matching a regexp.

StructuredData.SDshelllibFun.sdc_get(sdc)

returns an sdc-object from an sdc-key.

This function is not here to be called directly. It intended to be overridden by an application defined function that is then called whenever a new sdc object is read or written to. In this “dummy” implementation of the function, it simply returns the sdc object since the sdc-key and sdc-object are identical here.

StructuredData.SDshelllibFun.sdc_register(sdc, user_key=None)

create an sdc key from a new sdc object.

This function is not here to be called directly. It intended to be overridden by an application defined function that is then called whenever a new sdc object is created. In this “dummy” implementation of the function, it simply returns the sdc object, so sdc-key and sdc-object are identical here.

The user_key is an user provided key for the sdc object. Since this implementation simply returns the sdc object itself, the user_key is ignored here. However, if this function is overridden, the user_key may be taken into account by the new function.

StructuredData.SDshelllibFun.splitpath(path)[source]

splits a path according to the rules.

StructuredData.SDshelllibFun.string2pathkey(st)[source]

apply escaping rules on ‘.’,’[‘,’]’ in st.

StructuredData.SDshelllibFun.struc2sym(struc)

return a global symbol from a structure.

In XMLRPC we cannot simply transfer references global objects. So can implement here a way to get a global object from an arbitrary structure. The default is to return the object itself.

StructuredData.SDshelllibFun.substpath(path, pattern)[source]

changes the path according to a pattern.

StructuredData.SDshelllibFun.sym2struc(sym)

return structure from a global symbol.

vardict is usually global().

In XMLRPC we cannot simply transfer references global objects. So can implement here a way to convert a global object to an arbitrary structure. The default is to return the object itself.

StructuredData.SDshelllibFun.typeadditem(path, item, sdc=None)[source]

add an item to a type definition.

StructuredData.SDshelllibFun.typecheck(sdc=None)[source]

perform a typecheck on the StructuredDataContainer.

StructuredData.SDshelllibFun.typedelete(path, sdc=None)[source]

delete a type.

StructuredData.SDshelllibFun.typedeleteitem(path, item, sdc=None)[source]

delete an item in a type definition.

StructuredData.SDshelllibFun.typefind(pattern, sdc=None)[source]

find a type for a pattern.

StructuredData.SDshelllibFun.typeget(path, sdc=None)[source]

get a type for a path.

StructuredData.SDshelllibFun.typematch(path, sdc=None)[source]

try to find a typecheck for the given path.

StructuredData.SDshelllibFun.typepaths(pattern='*', sdc=None)[source]

find typepaths for a pattern.

StructuredData.SDshelllibFun.typeput(path, value, sdc=None)[source]

set a type.

StructuredData.SDshelllibFun.write(filename=None, formatspec='', pattern=None, sdc=None)[source]

generic write to a file.

returns:
name of the written file or, when not bool(filename), the data itself or (when error() raises no exception) std_return in case of an error.

SDshelllibBase

class StructuredData.SDshelllibBase.MultiStringOption(values, defaults)[source]

A helper class for string options.

Here are some examples:

>>> m= _MultiStringOption({"a":0, "b":0, "c":0, "x":1, "y":1},[None,"y"])
>>> m.parse("x:b")
['b', 'x']
>>> m.parse("x:b:a")
Traceback (most recent call last):
    ...
ValueError: contradicting part 'a' in spec 'x:b:a'
>>> m.parse("a")
['a', 'y']
>>> m.parse("x")
[None, 'x']
>>> m.parse("z")
Traceback (most recent call last):
    ...
ValueError: unknown part 'z' in spec 'z'
parse(spec)[source]

parse a spec string.

parameters:
spec - specification string
returns:
a tuple (result, new):
StructuredData.SDshelllibBase.as_csv(iterator, delimiter)[source]

return as csv data.

StructuredData.SDshelllibBase.is_readonly(path)[source]

returns True of the path (file) should not be written.

StructuredData.SDshelllibBase.module_functions(modules)[source]

return all functions of a dict of modules.

modules must be a dict mapping module names to module objects. The function returns a dict mapping function names to function objects.

StructuredData.SDshelllibBase.prettyprint(filename, struct)[source]

pretty print a structure to console or a file.

StructuredData.SDshelllibBase.use_file_lock(flag)[source]

switch file locking on and off.

StructuredData.SDshelllibBase.write_yml(filename, struct)[source]

write in yaml to console or a file.

SDshellrpclib

Classes

StructuredData - a package to manage StructuredData.

class StructuredData.Classes.MatchPaths(spec=None, check_func=None)[source]

This class provides a store for paths and a match function.

This class provides a store for paths that can be used to find matching paths for a given path. A path within the MatchPaths object may contain wildcards, “*” matches any map key and any list index. Each path in a MatchPaths object is associated with an arbitrary value.

Here is the algorithm for the path matching:

take all MatchPaths paths with the same length as path

from the first element of the matchpath and the path to the last element:

take all matchpaths where the current element is the same as the element in path

if there is no matchpath that matches take all matchpaths that have a wildcard as current element

continue the loop with the now smaller list of matchpaths

The paths are internally stored in a different format in order to make the match function efficient. However, the MatchPaths object can be converted back to a normal dictionary.

A path should be a StructuredDataStore - path, see also the documentation there. This object manages a list of paths where each path is mapped to an arbitrary object.

add(spec, check_func=None)[source]

add paths, spec must be a dict or a list of pairs.

This method adds paths and values from a given dictionary or a given list of pairs. A check function may be provided by the optional parameter check_func. This function is called on each value found in the given dictionary or list (note: only for the value, not for the path). The user may choose to raise an exception in the check function, if a value doesn’t match certain criteria.

Here are some examples:

>>> m=MatchPaths({"A":"a"})
>>> m.add({"B.C":"x","D.E":"y"})
>>> print m
MatchPaths({ 'A': 'a', 'B.C': 'x', 'D.E': 'y'})
>>> m=MatchPaths({"A":"a"})
>>> m.add((("B.C","x"),("D.E","y")))
>>> print m
MatchPaths({ 'A': 'a', 'B.C': 'x', 'D.E': 'y'})
>>> m=MatchPaths({"A":"a"})
>>> m.add([("B.C","x"),("D.E","y")])
>>> print m
MatchPaths({ 'A': 'a', 'B.C': 'x', 'D.E': 'y'})
>>> m.add({"*": "top wildcard", "A.*" : "a-wildcard", "B.C.*": "BC wildcard"})
>>> print m
MatchPaths(
  { '*': 'top wildcard',
    'A': 'a',
    'A.*': 'a-wildcard',
    'B.C': 'x',
    'B.C.*': 'BC wildcard',
    'D.E': 'y'}
)
as_path_dict()[source]

convert the MatchPaths object to a dictionary.

This method returns a dictionary than contains all the data of the MatchPaths object.

Here is an example:

>>> import pprint
>>> d={ "#": "top level",
...     "*": "top level, '*'",
...     "a": "top level 'a'",
...     "*.*": "level 2, '*.*'",
...     "a.*": "level 2, 'a.*'",
...     "a.*.b": "level 3, a.*.b",
...     "a.*.*": "level 3, a.*.*"
...   }
>>> m=MatchPaths(d)
>>> pprint.pprint(m.as_path_dict())
{'#': 'top level',
 '*': "top level, '*'",
 '*.*': "level 2, '*.*'",
 'a': "top level 'a'",
 'a.*': "level 2, 'a.*'",
 'a.*.*': 'level 3, a.*.*',
 'a.*.b': 'level 3, a.*.b'}
clone(deepcopy=True)[source]

clones a MatchPaths object.

Here is an example:

>>> d={ "#": "top level",
...     "a": "top level 'a'",
...     "*.*": "level 2, '*.*'",
...     "a.*": "level 2, 'a.*'",
...   }
>>> m=MatchPaths(d)
>>> print str(m)
MatchPaths(
  { '#': 'top level',
    '*.*': "level 2, '*.*'",
    'a': "top level 'a'",
    'a.*': "level 2, 'a.*'"}
)
>>> shallow= m.clone(False)
>>> deep= m.clone(True)
>>> m["*.*"]= "NEW!!"
>>> print str(m)
MatchPaths(
  { '#': 'top level',
    '*.*': 'NEW!!',
    'a': "top level 'a'",
    'a.*': "level 2, 'a.*'"}
)
>>> print str(shallow)
MatchPaths(
  { '#': 'top level',
    '*.*': 'NEW!!',
    'a': "top level 'a'",
    'a.*': "level 2, 'a.*'"}
)
>>> print str(deep)
MatchPaths(
  { '#': 'top level',
    '*.*': "level 2, '*.*'",
    'a': "top level 'a'",
    'a.*': "level 2, 'a.*'"}
)
iterator_add(iterator, check_func=None)[source]

add typespecs from an iterator to the MatchPaths.

This method adds paths from a iterator. The iterator must provide pairs consisting of a path and a value. A check function may be provided by the optional parameter check_func. This function is called on each value found in the given dictionary or list (note: only for the value, not for the path). The user may choose to raise an exception in the check function, if a value doesn’t match certain criteria.

No testcode here since this is implicitly tested by the testcode of method “add”.

lock()[source]

make the MatchPaths object read-only.

m_direct_iter(pattern='', length=None, paths_found_set=None)[source]

walk through all types.

returns lists of strings. SpecialKey objects are returned as objects.

IMPORTANT NOTE: The keylist returned at each iteration is NOT a new list but the same list with a new content at each iteration. If you use this iterator to store the keylist somewhere keep in mind that you have to make a shallow copy of the keylist like in “my_keylist= keylist[:]”. Note that list comprehension [x for x in s.m_direct_iter] WILL NOT work due to this reason.

Here are some examples:

>>> d={ "#": "top level",
...     "*": "top level, '*'",
...     "a": "top level 'a'",
...     "*.*": "level 2, '*.*'",
...     "a.*": "level 2, 'a.*'",
...     "n.*": "level 2, 'n.*",
...     "n[2]": "level 2, 'n[2]",
...     "a.b.C": "level 3, a.b.C",
...     "a.*.c": "level 3, a.*.c",
...     "a.*.*": { "mykey": 2 }
... }
>>> m=MatchPaths(d)
>>> def p(m,pattern,length,pathset=None):
...     res= [(p,kl[:],v) for (p,kl,v) in m.m_direct_iter(
...                                         pattern, 
...                                         length= length,
...                                         paths_found_set= pathset)]
...     res.sort(key= lambda x: x[0])
...     pprint.pprint(res)
>>> p(m,"",None)
[('#', [ROOTKEY], 'top level'),
 ('*', [ANYKEY], "top level, '*'"),
 ('*.*', [ANYKEY, ANYKEY], "level 2, '*.*'"),
 ('a', ['a'], "top level 'a'"),
 ('a.*', ['a', ANYKEY], "level 2, 'a.*'"),
 ('a.*.*', ['a', ANYKEY, ANYKEY], {'mykey': 2}),
 ('a.*.c', ['a', ANYKEY, 'c'], 'level 3, a.*.c'),
 ('a.b.C', ['a', 'b', 'C'], 'level 3, a.b.C'),
 ('n.*', ['n', ANYKEY], "level 2, 'n.*"),
 ('n[2]', ['n', 2], "level 2, 'n[2]")]
>>> p(m,"",2)
[('*.*', [ANYKEY, ANYKEY], "level 2, '*.*'"),
 ('a.*', ['a', ANYKEY], "level 2, 'a.*'"),
 ('n.*', ['n', ANYKEY], "level 2, 'n.*"),
 ('n[2]', ['n', 2], "level 2, 'n[2]")]
>>> p(m,"",5)
[]
>>> p(m,"",3)
[('a.*.*', ['a', ANYKEY, ANYKEY], {'mykey': 2}),
 ('a.*.c', ['a', ANYKEY, 'c'], 'level 3, a.*.c'),
 ('a.b.C', ['a', 'b', 'C'], 'level 3, a.b.C')]
>>> p(m,"a.*",None)
[('a.*', ['a', ANYKEY], "level 2, 'a.*'")]
>>> p(m,"a.**",None)
[('a.*', ['a', ANYKEY], "level 2, 'a.*'"),
 ('a.*.*', ['a', ANYKEY, ANYKEY], {'mykey': 2}),
 ('a.*.c', ['a', ANYKEY, 'c'], 'level 3, a.*.c'),
 ('a.b.C', ['a', 'b', 'C'], 'level 3, a.b.C')]
>>> p(m,"a.**",2)
[('a.*', ['a', ANYKEY], "level 2, 'a.*'")]
>>> p(m,"a.**",3)
[('a.*.*', ['a', ANYKEY, ANYKEY], {'mykey': 2}),
 ('a.*.c', ['a', ANYKEY, 'c'], 'level 3, a.*.c'),
 ('a.b.C', ['a', 'b', 'C'], 'level 3, a.b.C')]
>>> p(m,"**",1)
[('*', [ANYKEY], "top level, '*'"), ('a', ['a'], "top level 'a'")]
>>> p(m,"**",0)
[]
>>> p(m,"",0)
[('#', [ROOTKEY], 'top level')]
>>> pset= set()
>>> p(m,"a.b.*",None,pset)
[('a.b.C', ['a', 'b', 'C'], 'level 3, a.b.C')]
>>> p(m,"a.**",None,pset)
[('a.*', ['a', ANYKEY], "level 2, 'a.*'"),
 ('a.*.*', ['a', ANYKEY, ANYKEY], {'mykey': 2}),
 ('a.*.c', ['a', ANYKEY, 'c'], 'level 3, a.*.c')]
match(path, return_matchpath=False)[source]

match a path in the MatchPaths.

This method returns the value of the path in the MatchPaths object that matches the given path best.

Here are some examples:

>>> d={ "#": "top level",
...     "*": "top level, '*'",
...     "a": "top level 'a'",
...     "*.*": "level 2, '*.*'",
...     "a.*": "level 2, 'a.*'",
...     "n.*": "level 2, 'n.*",
...     "n[2]": "level 2, 'n[2]",
...     "a.b.C": "level 3, a.b.C",
...     "a.*.c": "level 3, a.*.c",
...     "a.*.*": "level 3, a.*.*"
... }
>>> m=MatchPaths(d)
>>> m.match("#")
'top level'
>>> m.match("abc")
"top level, '*'"
>>> m.match("a")
"top level 'a'"
>>> m.match("x.y")
"level 2, '*.*'"
>>> m.match("a.y")
"level 2, 'a.*'"
>>> m.match("a.y.c")
'level 3, a.*.c'
>>> m.match("a.b.c")
'level 3, a.*.c'
>>> m.match("a.b.C")
'level 3, a.b.C'
>>> m.match("a.x.y")
'level 3, a.*.*'
>>> m.match("n[2]")
"level 2, 'n[2]"
>>> m.match("n[0]")
"level 2, 'n.*"
>>> m.match("x.y.z")
>>> m=MatchPaths(d)
>>> m.match("#",True)
('#', 'top level')
>>> m.match("abc",True)
('*', "top level, '*'")
>>> m.match("x.y",True)
('*.*', "level 2, '*.*'")
>>> m.match("a.b.c",True)
('a.*.c', 'level 3, a.*.c')
>>> m.match("a.b.C",True)
('a.b.C', 'level 3, a.b.C')
>>> m.match("n[2]",True)
('n[2]', "level 2, 'n[2]")
>>> m.match("n[0]",True)
('n.*', "level 2, 'n.*")

search by a given pattern.

A pattern is a StructuredDataStore path which may contain wildcards. A wildcard for a key in a dictionary or a list item is “*”.

Here are some examples:

>>> d={ "#": "top level",
...     "*": "top level, '*'",
...     "\*": "star",
...     "a": "top level 'a'",
...     "*.*": "level 2, '*.*'",
...     "a.*": "level 2, 'a.*'",
...     "n.*": "level 2, 'n.*",
...     "n[2]": "level 2, 'n[2]",
...     "a.b.C": "level 3, a.b.C",
...     "a.*.c": "level 3, a.*.c",
...     "a.*.*": { "mykey": 2 }
... }
>>> m=MatchPaths(d)
>>> 
>>> def test(pattern, length= None):
...   pprint.pprint(sorted(m.simple_search(pattern,length)))
>>> test("**")
['*', '*.*', '\\*', 'a', 'a.*', 'a.*.*', 'a.*.c', 'a.b.C', 'n.*', 'n[2]']
>>> test("\*")
['\\*']
>>> test("a.**")
['a.*', 'a.*.*', 'a.*.c', 'a.b.C']
>>> test("a.b.**")
['a.b.C']
>>> test("#")
Traceback (most recent call last):
    ...
ValueError: unexpected specialkey: ROOTKEY
>>> test("\#")
[]
>>> test("*")
['*', '\\*', 'a']
>>> test("*.*")
['*.*', 'a.*', 'n.*', 'n[2]']
>>> test("",0)
['#']
>>> test("a.**")
['a.*', 'a.*.*', 'a.*.c', 'a.b.C']
>>> test("a.**",2)
['a.*']
>>> test("a.**",3)
['a.*.*', 'a.*.c', 'a.b.C']
class StructuredData.Classes.SingleTypeSpec(dict_)[source]

a single type specification.

Optimized for quicker typechecks.

Here are some examples:

>>> s= SingleTypeSpec("integer")
>>> repr(s)
"SingleTypeSpec('integer')"
>>> str(s)
"SingleTypeSpec('integer')"
>>> s.check(1)
>>> s.check(1.2)
Traceback (most recent call last):
    ...
TypeError: integer expected, got: 1.2
>>> s=SingleTypeSpec({"optional_struct":["x","y","z"]})
>>> repr(s)
"SingleTypeSpec({'optional_struct': ['x', 'y', 'z']})"
>>> str(s)
"SingleTypeSpec({ 'optional_struct': ['x', 'y', 'z']})"
>>> s.check({"x":1,"z":2})
>>> s.check({"x":1,"a":2})
Traceback (most recent call last):
    ...
TypeError: key a not in list of allowed keys
items()[source]

returns the internal set of items if there is one.

Since this method returns the internal set object, it can be used to manipulate the set directly.

Here are some examples:

>>> s= SingleTypeSpec("integer")
>>> s.items()
Traceback (most recent call last):
    ...
TypeError: the typespec has no items
>>> s=SingleTypeSpec({"optional_struct":["x","y","z"]})
>>> pprint.pprint(s.items())
set(['x', 'y', 'z'])
>>> s.items().add("w")
>>> print s
SingleTypeSpec({ 'optional_struct': ['w', 'x', 'y', 'z']})
>>> s.items().remove("x")
>>> print s
SingleTypeSpec({ 'optional_struct': ['w', 'y', 'z']})
to_dict()[source]

convert the SingleTypeSpec object to a dictionary.

class StructuredData.Classes.SpecialKey(type_, data=None)[source]

This class implements a data type for special path elements. Currently there are three kinds implemented, the “any_key” type which matches any key (exactly one key), “any_keys” which matches any key (one or more) and the “root” which is used to represent the root of a StructuredDataStore. Note that in order to make objects of this class usable for being dictionary keys, instances for each type of this class are instantiated, ANYKEY, ANYKEYS and ROOTKEY. You should only use these and not instantiate SpecialKey objects of your own. Use the function string_to_keyobject to create a SpecialKey object from a string, this function uses the predefined objects, too.

is_root()[source]

returns True if the object is of type “root”.

static keysubst(keylist, pattern_keylist)[source]

change a keylist according to a pattern-keylist.

Each wildcard in the pattern means that the corresponding key of the keylist remains unchanged. The non-wildcard parts in the pattern replace the corresponding key. If the pattern_keylist is shorter than the keylist, the remaining keys of the keylist are removed. If the pattern_keylist is longer than the keylist the remaining keys of the pattern_keylist are appended. However, these remaining keys MUST NOT be wildcards.

Here are some examples:

>>> def pathsubst(path, pattern):
...   l= SpecialKey.keysubst(StructuredDataStore.split_path(path),
...                          StructuredDataStore.split_path(pattern))
...   return StructuredDataStore.join_path(l)
... 
>>> pathsubst("a.b.c","*.*.x")
'a.b.x'
>>> pathsubst("a.b.c","*.y.*")
'a.y.c'
>>> pathsubst("a.b.c","*.*.*")
'a.b.c'
>>> pathsubst("a.b.c","*.*")
'a.b'
>>> pathsubst("a.b.c","*.*.*.x")
'a.b.c.x'
>>> pathsubst("a.b.c","*.*.*.*")
Traceback (most recent call last):
    ...
ValueError: keylist too short for patternlist
>>> pathsubst("a.b.c","*[3].*")
'a[3].c'
>>> pathsubst("a.b.c","X.**")
'X.b.c'
>>> pathsubst("a.b.c","X.**.x.y")
'X.b.c.x.y'
>>> pathsubst("a.b.c","X.**.x.*")
Traceback (most recent call last):
    ...
ValueError: keylist too short for patternlist
static list_match(pattern_list, keylist)[source]

matches a pattern_list against a keylist.

A pattern_list is a list of integers, strings and SpecialKey objects. A keylist is a list of integers and strings.

Here are some examples:

>>> def test(pattern,path):
...   pl= StructuredDataStore.split_path(pattern)
...   l = StructuredDataStore.split_path(path)
...   return SpecialKey.list_match(pl, l)
... 
>>> test("a.*","a.x")
True
>>> test("a.*","v.x")
False
>>> test("a.*.c","a[3].c")
True
>>> test("a.*.c","a[3].d")
False
>>> test("a.*.**","a[3].d")
True
>>> test("a.*.**","a[3].e")
True
>>> test("a.*.**","a[3][7]")
True
>>> test("a.**","a[3][7]")
True
>>> test("a.*.**","a.b.c")
True
>>> test("a.*.**","a.b")
False
>>> test("a.*","a.b.c")
False
>>> test("a.**","a.b.c")
True
>>> test("a.b.**","a.b.c")
True
match(val)[source]

matches the wildcard against an item.

This method checks if the SpecialKey matches a given string. It returns True if it does, False otherwise. It raises an exception if the SpecialKey object is not a wildcard.

Here are some examples:

>>> m= SpecialKey(SpecialKeyTypes.any_key)
>>> m.match("ab")
True
>>> m.match("xy")
True
>>> m.match([1,2])
False
>>> m.match(ANYKEY)
True
>>> m.match(ANYKEYS)
True
>>> m.match(ROOTKEY)
True
recursive_wildcard()[source]

returns True if the object is of type “any_keys”.

simple_wildcard()[source]

returns True if the object is of type “any_key”.

class StructuredData.Classes.StructuredDataContainer(dict_=None)[source]

This is a simple container that can hold a StructuredDataStore, StructuredDataTypes or both. A StructuredDataContainer is a map that always has the key “SDC-Metadata and the optional keys “SDC-Store” and “SDC-Types”.

SDC-Metadata:
This is a simple map that contains information on the format used. Currently it has only one key, “version” which has as value the current version number of the format as a string. As of the writing of this document, the current version is “1.0”.
SDC-Store:
This is the StructuredDataStore map.
SDC-Types:
This is the StructuredDataTypes map.
add(dict_)[source]

add data to the StructuredDataContainer from a dict.

This method adds new data to the StructuredDataContainer object. The data provided to this method must be a dictionary with two optional keys, “SDC-Store” and “SDC-Types”. The data referenced by “SDC-Store” is added to the internal StructuredDataStore object. The data referenced by “SDC-Types” is added to the internal StructuredDataTypes object.

Here is an example:

>>> t= StructuredDataContainer({"**SDC-Metadata**": { "version": "1.0" },
...                             "**SDC-Store**":
...                               { "a": { "x": 1 } },
...                             "**SDC-Types**":
...                               { "a.x" : "integer" }
...                            }
...                           )
>>> 
>>> print(t)
StructuredDataContainer(
  { '**SDC-Metadata**': { 'version': '1.0'}},
  StructuredDataStore({ 'a': { 'x': 1}}),
  StructuredDataTypes({ 'a.x': 'integer'})
  )
>>> 
>>> t.add({"**SDC-Metadata**": { "version": "1.0" },
...        "**SDC-Store**":
...           { "a": { "y": 2.0 } },
...       }
...      )
>>> 
>>> print(t)
StructuredDataContainer(
  { '**SDC-Metadata**': { 'version': '1.0'}},
  StructuredDataStore({ 'a': { 'x': 1, 'y': 2.0}}),
  StructuredDataTypes({ 'a.x': 'integer'})
  )
>>> 
>>> t.add({"**SDC-Metadata**": { "version": "1.0" },
...        "**SDC-Types**":
...           { "a.y" : "real" }
...       }
...      )
>>> print(t)
StructuredDataContainer(
  { '**SDC-Metadata**': { 'version': '1.0'}},
  StructuredDataStore({ 'a': { 'x': 1, 'y': 2.0}}),
  StructuredDataTypes({ 'a.x': 'integer', 'a.y': 'real'})
  )
add_yaml_file(filename)[source]

add data to the StructuredDataContainer from a yaml file.

add_yaml_string(st)[source]

add data to the StructuredDataContainer from a yaml string.

as_dict()[source]

return the object as a dictionary.

This method returns a dictionary that contains all the information of the StructuredDataContainer object.

Here is an example:

>>> import pprint
>>> d= { "**SDC-Metadata**": { "version": "1.0" },
...      "**SDC-Store**"    : { "a":1, "b":2 },
...      "**SDC-Types**"   : { "#": {"typed_map": "string"} }
...    }
>>> t= StructuredDataContainer(d)
>>> pprint.pprint(t.as_dict())
{'**SDC-Metadata**': {'version': '1.0'},
 '**SDC-Store**': {'a': 1, 'b': 2},
 '**SDC-Types**': {'#': {'typed_map': 'string'}}}
as_yaml_file(filename)[source]

return the StructuredDataContainer as a yaml file.

Does also lock the file during writing.

as_yaml_string()[source]

return the StructuredDataContainer as a yaml string.

clear_store()[source]

remove the StructuredDataStore object.

clear_types()[source]

remove the StructuredDataTypes.

clone(deepcopy=True)[source]

clones a StructuredDataContainer object.

Here is an example:

>>> d= { "**SDC-Metadata**": { "version": "1.0" },
...      "**SDC-Store**"   : { "a": { "x":1, "y":2 }, "b":10 },
...      "**SDC-Types**"   : { "#": {"typed_map": "string"} }
...    }
>>> t= StructuredDataContainer(d)
>>> shallow= t.clone(False)
>>> deep   = t.clone(True)
>>> t.store()["a.y"]= "NEW"
>>> t.store().setitem("a.z", "ADDED", True)
>>> print t
StructuredDataContainer(
  { '**SDC-Metadata**': { 'version': '1.0'}},
  StructuredDataStore({ 'a': { 'x': 1, 'y': 'NEW', 'z': 'ADDED'}, 'b': 10}),
  StructuredDataTypes({ '#': { 'typed_map': 'string'}})
  )
>>> print shallow
StructuredDataContainer(
  { '**SDC-Metadata**': { 'version': '1.0'}},
  StructuredDataStore({ 'a': { 'x': 1, 'y': 'NEW', 'z': 'ADDED'}, 'b': 10}),
  StructuredDataTypes({ '#': { 'typed_map': 'string'}})
  )
>>> print deep
StructuredDataContainer(
  { '**SDC-Metadata**': { 'version': '1.0'}},
  StructuredDataStore({ 'a': { 'x': 1, 'y': 2}, 'b': 10}),
  StructuredDataTypes({ '#': { 'typed_map': 'string'}})
  )
static from_yaml_file(filename)[source]

create a StructuredDataContainer from a yaml file.

Does also lock the file during reading.

static from_yaml_string(st)[source]

create a StructuredDataContainer from a yaml file.

lock()[source]

make the StructuredDataContainer read-only.

meta()[source]

return the metadata dictionary of the object.

pickle(filename)[source]

write StructuredDataContainer pickled.

set_store(data)[source]

set the StructuredDataStore in the object.

set_types(types_)[source]

set the StructuredDataTypes contained in the object.

store()[source]

return the StructuredDataStore contained in the object.

typecheck(other=None)[source]

perform a typecheck on the data.

This method performs a typecheck on the contained StructuredDataStore. If there is also a StructuredDataTypes object in the container, this is used for the typechecks. Otherwise, the parameter “other” is used to retrieve type check information. This parameter may either be a StructuredDataTypes object or a StructuredDataContainer with embedded StructuredDataTypes.

parameters:

other
This optional parameter is used to provide the type checking information. If this parameter is omitted, the function looks for type checking information embedded in the StructuredDataContainer. If it is not found there either, an AssertionError is raised. The parameter may be a StructuredDataTypes object or a StructuredDataContainer object with embeeded type checking information.

Here are some examples:

>>> d= { "**SDC-Metadata**": { "version": "1.0" },
...      "**SDC-Store**" : { "a":1, "b":2 },
...      "**SDC-Types**": { "#": {"typed_map": "string"} }
...    }
>>> t= StructuredDataContainer(d)
>>> t.typecheck()
>>> d= { "**SDC-Metadata**": { "version": "1.0" },
...      "**SDC-Store**" : { 2  :1, "b":2 },
...      "**SDC-Types**": { "#": {"typed_map": "string"} }
...    }
>>> t= StructuredDataContainer(d)
>>> t.typecheck()
Traceback (most recent call last):
    ...
TypeError: error at path "#": string expected, got: 2
types()[source]

return the StructuredDataTypes contained in the object.

class StructuredData.Classes.StructuredDataStore(data=None)[source]

defines a universal data store.

This class is used to represent the StructuredDataStore. A StructuredDataStore contains the pure data as a python dictionary which may contain simple values or references to further dictionaries or lists. It also may contain a link dictionary. This dictionary maps python object ids (every python object has an id) to sets of keylists. When the StructuredDataStore is modified by using it’s methods it tries to keep the link dictionary up to date (if it exists), but it cannot cover all cases. Especially you should use the link method when you plan to refer to the same data at several places of the StructuredDataStore.

add(data)[source]

adds new data to the StructuredDataStore object.

This adds new data from a given dictionary representation of a StructuredDataStore. Note that different from the update method of dict, dictionaries in the structure that already exist are not replaced with the ones given in the new structure but new keys are added. Data must be a dict or a list of pairs.

annotated_join_path(keylist)[source]

similar to join_path, but give hints on links.

All keys in the path that relate to a linked object, one that is referred by other paths as well, get a “*” appended at the end.

Note that list indices get the star appended to the closing bracket. Here are some examples:

>>> d= { "A": { "B": 1, "C": None},
...      "x": {"y":None},
...      "l": [["val"], 1, None]
...    }
>>> d["x"]["y"]= d["A"]
>>> d["l"][2]= d["l"][0]
>>> d["A"]["C"]= d["l"][0]
>>> p= StructuredDataStore(d)
>>> print p
StructuredDataStore(
  { 'A': { 'B': 1, 'C': ['val']},
    'l': [['val'], 1, ['val']],
    'x': { 'y': { 'B': 1, 'C': ['val']}}}
)
>>> p.annotated_join_path(["A","B"])
'A*.B'
>>> p.annotated_join_path(["A","B","C"])
Traceback (most recent call last):
    ...
KeyError: 'at key C, item is a scalar'
>>> p.annotated_join_path(["A","C"])
'A*.C*'
>>> p.annotated_join_path(["l",0])
'l[0]*'
>>> p.annotated_join_path(["l",1])
'l[1]'
>>> p.annotated_join_path(["l",2])
'l[2]*'
>>> p.annotated_join_path(["x"])
'x'
>>> p.annotated_join_path(["x","y"])
'x.y*'
static append_path(path, key)[source]

append a key to a path.

The key is a path key or a pair of a path key and an extra string.

Here are some examples:

>>> print StructuredDataStore.append_path("a.b","c")
a.b.c
>>> print StructuredDataStore.append_path("a.b",3)
a.b[3]
>>> print StructuredDataStore.append_path("a[1]","c")
a[1].c
>>> print StructuredDataStore.append_path("a[1]",2)
a[1][2]
>>> print StructuredDataStore.append_path("","c")
c
>>> print StructuredDataStore.append_path("",3)
[3]
>>> print StructuredDataStore.append_path("a[1]","x.y")
a[1].x\.y
>>> print StructuredDataStore.append_path("a[1]","*")
a[1].\*
>>> print StructuredDataStore.append_path("a[1]","**")
a[1].\**
as_csv(stream=None, delimiter=', ', align_values=False, value_first=False)[source]

return the data in csv form.

This method returns the StructuredDataStore as csv. If the parameter “stream” is supplied it writes to that stream, otherwise it returns a string.

parameters:

stream
the stream to print to. If this is None, return a string with the data.
align_values
the value is in the last column, all values are aligned meaning they are all at the same column number. If thus parameter is False, the values are in the last column of each line but they may be at different column numbers in the different lines.
value_first
put the value in the first column, before all keys.

Here is a simple example:

>>> d={"key1":1, "key2": {"A":"x","B":"y"}, "key3":[1,2,3,{"float":1.23}]}
>>> p= StructuredDataStore(d)
>>> print p.as_csv()
key1,1
key2,A,x
key2,B,y
key3,0,1
key3,1,2
key3,2,3
key3,3,float,1.23

>>> print p.as_csv(value_first= True)
1,key1
x,key2,A
y,key2,B
1,key3,0
2,key3,1
3,key3,2
1.23,key3,3,float

>>> print p.as_csv(align_values=True)
key1,,,1
key2,A,,x
key2,B,,y
key3,0,,1
key3,1,,2
key3,2,,3
key3,3,float,1.23
as_dict()[source]

return the as_dict data.

This method returns the StructuredDataStore as a python dictionary. Note that this does not copy the data, it just returns the internal dictionary.

Here is a simple example:

>>> d={"key1":1, "key2": {"A":"x","B":"y"}, "key3":[1,2,3,{"float":1.23}]}
>>> p= StructuredDataStore(d)
>>> p.as_dict()
{'key3': [1, 2, 3, {'float': 1.23}], 'key2': {'A': 'x', 'B': 'y'}, 'key1': 1}
as_flat_dict(pattern='', show_links=False, path_list=None)[source]

return the data in the “flat dict” form.

This method returns the StructuredDataStore as a flat python dictionary. This is a dictionary that maps paths to values.

Here are some examples:

>>> d={"key1":1, "key2": {"A":"x","B":"y"}, "key3":[1,2,3,{"float":1.23}]}
>>> p= StructuredDataStore(d)
>>> pprint.pprint(p.as_flat_dict())
{'key1': 1,
 'key2.A': 'x',
 'key2.B': 'y',
 'key3[0]': 1,
 'key3[1]': 2,
 'key3[2]': 3,
 'key3[3].float': 1.23}
>>> pprint.pprint(p.as_flat_dict(pattern="key3.**"))
{'key3[0]': 1, 'key3[1]': 2, 'key3[2]': 3, 'key3[3].float': 1.23}
>>> pprint.pprint(p.as_flat_dict(pattern="key3[3].**"))
{'key3[3].float': 1.23}
>>> pprint.pprint(p.as_flat_dict(pattern="key3[3].float"))
{'key3[3].float': 1.23}
>>> pprint.pprint(p.as_flat_dict(pattern=["key2.**","key3.*"]))
{'key2.A': 'x', 'key2.B': 'y', 'key3[0]': 1, 'key3[1]': 2, 'key3[2]': 3}
clear()[source]

delete all data.

This removes all data from the object.

clone(deepcopy=True)[source]

clones a StructuredDataStore object.

This creates a copy of the StructuredDataStore. If the parameter deepcopy is True, a deep copy is performed where the new StructuredDataStore is completely independent from the first StructuredDataStore meaning that changes on the first one do never affect the new one.

Here are some examples:

>>> d= { "A": { "B": 1, "C": 2}, 
...      "x": {"y":None},
...      "l": [["val"], 1, None]
...    }
>>> d["x"]["y"]= d["A"]
>>> d["l"][2]= d["l"][0]
>>> p= StructuredDataStore(d)
>>> print p
StructuredDataStore(
  { 'A': { 'B': 1, 'C': 2},
    'l': [['val'], 1, ['val']],
    'x': { 'y': { 'B': 1, 'C': 2}}}
)
>>> shallow= p.clone(False)
>>> deep   = p.clone(True)
>>> p["A"]["B"]="CHANGED!"
>>> print p
StructuredDataStore(
  { 'A': { 'B': 'CHANGED!', 'C': 2},
    'l': [['val'], 1, ['val']],
    'x': { 'y': { 'B': 'CHANGED!', 'C': 2}}}
)
>>> print shallow
StructuredDataStore(
  { 'A': { 'B': 'CHANGED!', 'C': 2},
    'l': [['val'], 1, ['val']],
    'x': { 'y': { 'B': 'CHANGED!', 'C': 2}}}
)
>>> print deep
StructuredDataStore(
  { 'A': { 'B': 1, 'C': 2},
    'l': [['val'], 1, ['val']],
    'x': { 'y': { 'B': 1, 'C': 2}}}
)
delitem(path)[source]

deletes an item from the store.

This is the explicit deletion method, it’s function is the same as __delitem__.

Here is an example:

>>> d={"key1":1, "key2": {"A":"x","B":"y"}, "key3":[1,2,3,{"float":1.23}]}
>>> p= StructuredDataStore(d)
>>> print p
StructuredDataStore(
  { 'key1': 1,
    'key2': { 'A': 'x', 'B': 'y'},
    'key3': [1, 2, 3, { 'float': 1.23}]}
)
>>> p.delitem("key3[3].float")
>>> print p
StructuredDataStore(
  { 'key1': 1, 'key2': { 'A': 'x', 'B': 'y'}, 'key3': [1, 2, 3, { }]}
)
>>> p.delitem("key3[3]")
>>> print p
StructuredDataStore(
  { 'key1': 1, 'key2': { 'A': 'x', 'B': 'y'}, 'key3': [1, 2, 3]}
)
direct_iter(pattern, only_leaves, sorted_, show_links, paths_found_set=None)[source]

Iteration through the StructuredDataStore.

This method returns an iterator on all the nodes of the StructuredDataStore. For each iteration it returns a tuple consisting of the path, the keylist and the value of that node.

parameters:

pattern
A path pattern that is used to filter the results. If this is None or an empty string, the results are not filtered.
only_leaves
If this is true, only nodes that are scalars are returned.
sorted_
If this is true, iteration through map keys is sorted.
show_links
If this is true, links are marked in the result.
paths_found_set
If this parameter is given, it should be a set. Paths that already are in this set are not returned. Paths found are added to this set.

returns:

a tuple (path,keys,value)

IMPORTANT NOTE: The keys returned at each iteration are NOT a new list but the same list with a new content at each iteration. If you use this iterator to store the keylist somewhere keep in mind that you have to make a shallow copy of the keylist like in “my_keylist= keylist[:]”. Note that list comprehension WILL NOT work due to this reason.

Here are some examples:

>>> d={"key1":1, "key2": {"A":"x","B":"y"}, "key3":[1,2,3,{"float":1.23}]}
>>> p= StructuredDataStore(d)
>>> def test(s,pattern,only_leaves,sorted_,
...          show_links=False, paths_found_set= None):
...   for l in s.direct_iter(pattern,only_leaves,
...                             sorted_,show_links,paths_found_set):
...     print repr(l)
>>> test(p,"",False,False)
('key3', ['key3'], [1, 2, 3, {'float': 1.23}])
('key3[0]', ['key3', 0], 1)
('key3[1]', ['key3', 1], 2)
('key3[2]', ['key3', 2], 3)
('key3[3]', ['key3', 3], {'float': 1.23})
('key3[3].float', ['key3', 3, 'float'], 1.23)
('key2', ['key2'], {'A': 'x', 'B': 'y'})
('key2.A', ['key2', 'A'], 'x')
('key2.B', ['key2', 'B'], 'y')
('key1', ['key1'], 1)
>>> test(p,"",False,True)
('key1', ['key1'], 1)
('key2', ['key2'], {'A': 'x', 'B': 'y'})
('key2.A', ['key2', 'A'], 'x')
('key2.B', ['key2', 'B'], 'y')
('key3', ['key3'], [1, 2, 3, {'float': 1.23}])
('key3[0]', ['key3', 0], 1)
('key3[1]', ['key3', 1], 2)
('key3[2]', ['key3', 2], 3)
('key3[3]', ['key3', 3], {'float': 1.23})
('key3[3].float', ['key3', 3, 'float'], 1.23)
>>> pset= set()
>>> test(p,"",True,True,False,pset)
('key1', ['key1'], 1)
('key2.A', ['key2', 'A'], 'x')
('key2.B', ['key2', 'B'], 'y')
('key3[0]', ['key3', 0], 1)
('key3[1]', ['key3', 1], 2)
('key3[2]', ['key3', 2], 3)
('key3[3].float', ['key3', 3, 'float'], 1.23)
>>> test(p,"",False,True,False,pset)
('key2', ['key2'], {'A': 'x', 'B': 'y'})
('key3', ['key3'], [1, 2, 3, {'float': 1.23}])
('key3[3]', ['key3', 3], {'float': 1.23})
>>> d={"key0":1,
...    "key1":{"A":"x1","B":"y1"}, 
...    "key2":{"A":"x2","B":"y2"}, 
...    "key3":[1,2,3,{"float":1.23}]}
>>> p= StructuredDataStore(d)
>>> test(p,"",False,True)
('key0', ['key0'], 1)
('key1', ['key1'], {'A': 'x1', 'B': 'y1'})
('key1.A', ['key1', 'A'], 'x1')
('key1.B', ['key1', 'B'], 'y1')
('key2', ['key2'], {'A': 'x2', 'B': 'y2'})
('key2.A', ['key2', 'A'], 'x2')
('key2.B', ['key2', 'B'], 'y2')
('key3', ['key3'], [1, 2, 3, {'float': 1.23}])
('key3[0]', ['key3', 0], 1)
('key3[1]', ['key3', 1], 2)
('key3[2]', ['key3', 2], 3)
('key3[3]', ['key3', 3], {'float': 1.23})
('key3[3].float', ['key3', 3, 'float'], 1.23)
>>> test(p,"key2",False,True)
('key2', ['key2'], {'A': 'x2', 'B': 'y2'})
>>> test(p,"key2.**",False,True)
('key2.A', ['key2', 'A'], 'x2')
('key2.B', ['key2', 'B'], 'y2')
>>> test(p,"key3",False,True)
('key3', ['key3'], [1, 2, 3, {'float': 1.23}])
>>> test(p,"key3.*",False,True)
('key3[0]', ['key3', 0], 1)
('key3[1]', ['key3', 1], 2)
('key3[2]', ['key3', 2], 3)
('key3[3]', ['key3', 3], {'float': 1.23})
>>> test(p,"key3.**",False,True)
('key3[0]', ['key3', 0], 1)
('key3[1]', ['key3', 1], 2)
('key3[2]', ['key3', 2], 3)
('key3[3]', ['key3', 3], {'float': 1.23})
('key3[3].float', ['key3', 3, 'float'], 1.23)
>>> test(p,"*.A",False,True)
('key1.A', ['key1', 'A'], 'x1')
('key2.A', ['key2', 'A'], 'x2')
>>> test(p,"*[0]",False,True)
('key3[0]', ['key3', 0], 1)
>>> test(p,"*[3].**",False,True)
('key3[3].float', ['key3', 3, 'float'], 1.23)
>>> d={"key1":{"A":"x1","B":"y1"}}
>>> d["key1"]["B"]= d["key1"]
>>> p= StructuredDataStore(d)
>>> test(p,"",False,True)
('key1', ['key1'], {'A': 'x1', 'B': {...}})
('key1.A', ['key1', 'A'], 'x1')
('key1.B', ['key1', 'B'], {'A': 'x1', 'B': {...}})
>>> test(p,"",False,True,True)
('key1*', [('key1', '*')], {'A': 'x1', 'B': {...}})
('key1*.A', [('key1', '*'), 'A'], 'x1')
('key1*.B*', [('key1', '*'), ('B', '*')], {'A': 'x1', 'B': {...}})
static from_flat_dict(data=None)[source]

create StructuredDataStore from a flat dictionary.

This initializes the object from a flat dictionary structure. A flat dictionary is a dictionary that maps paths to values. These paths and the values are used to generate a complete StructuredDataStore structure.

Here is an example:

>>> p= StructuredDataStore.from_flat_dict({"A.B.C":1, "A.B.D":2})
>>> print p
StructuredDataStore({ 'A': { 'B': { 'C': 1, 'D': 2}}})

returns all paths that point to the same data as “path”.

This function returns a set of paths that refer to the same data as the given path including the given path. If no other paths refer to the same data, a set that just contains the given path is returned. Note that “path” is also in the list, so this will return a list with one element, “path” if there are no links.

Here are some examples:

>>> d= { "A": { "B": 1, "C": 2}, 
...      "x": {"y":None},
...      "l": [["val"], 1, None]
...    }
>>> d["x"]["y"]= d["A"]
>>> d["l"][2]= d["l"][0]
>>> s= StructuredDataStore(d)
>>> s.get_links("A")
set(['x.y', 'A'])
>>> s.get_links("x.y")
set(['x.y', 'A'])
>>> s.get_links("x")
set(['x'])
>>> s.get_links("l[2]")
set(['l[2]', 'l[0]'])
>>> s.get_links("A",include="x.*")
set(['x.y'])
>>> s.get_links("A",exclude="x.*")
set(['A'])
>>> s.get_links("l[2]",include="l[0]")
set(['l[0]'])

search all paths for a given i-pattern.

An “i-pattern” is a list of space separated sub-strings. All strings that contain all of these sub-strings in any order (compared case insensitive) match.

Here are some examples:

>>> d={"key1":1, "key2": {"A":"x","B":"y"}, "key3":[1,2,3,{"float":1.23}]}
>>> p= StructuredDataStore(d)
>>> print  p
StructuredDataStore(
  { 'key1': 1,
    'key2': { 'A': 'x', 'B': 'y'},
    'key3': [1, 2, 3, { 'float': 1.23}]}
)
>>> print p.i_search("1")
['key3[1]', 'key1']
>>> print p.i_search("1", add_values= False)
['key3[1]', 'key1']
>>> print p.i_search("float", add_values= False)
['key3[3].float']
>>> print p.i_search("float", add_values= True)
[('key3[3].float', 1.23)]
>>> print p.i_search("2 key", add_values= True)
[('key3[2]', 3), ('key2.A', 'x'), ('key2.B', 'y')]
is_linked(path)[source]

returns True if another path points to the same data.

This function returns True if there is at least one other path that refers to the same data as the given path.

Here are some examples:

>>> d= { "A": { "B": 1, "C": 2}, 
...      "x": {"y":None},
...      "l": [["val"], 1, None]
...    }
>>> d["x"]["y"]= d["A"]
>>> d["l"][2]= d["l"][0]
>>> s= StructuredDataStore(d)
>>> s.is_linked("A")
True
>>> s.is_linked("A.B")
False
>>> s.is_linked("l[2]")
True
static join_path(keylist)[source]

joins a path from a keylist.

This method joins a list of keys to a path. It doesn’t need access to the StructuredDataStore so it is a static method. Usually each key of the keylist is a SpecialKey object, a string or an integer or a pair. In the latter case the pair consists of a SpecialKey, a string or an integer and an extra string. All these are combined to form a StructuredData path.

Here are some examples:

>>> print StructuredDataStore.join_path(["A","B"])
A.B
>>> print StructuredDataStore.join_path(["A.B","C"])
A\.B.C
>>> print StructuredDataStore.join_path(["A",2,"C"])
A[2].C
>>> print StructuredDataStore.join_path(["A","*","C"])
A.\*.C
>>> print StructuredDataStore.join_path(["A","x[3]","C"])
A.x\[3\].C
>>> print StructuredDataStore.join_path(["A",ANYKEY,"B"])
A.*.B
keylist2object(keylist)[source]

get the object that is identified by a keylist.

This method returns for a given keylist the part of the StructuredDataStore it adresses.

Here are some examples:

>>> d={"key1":1, "key2": {"A":"x","B":"y"}, "key3":[1,2,3,{"float":1.23}]}
>>> p= StructuredDataStore(d)
>>> p.keylist2object(["key2"])
{'A': 'x', 'B': 'y'}
>>> p.keylist2object(["key2","B"])
'y'
>>> p.keylist2object(["key3",1])
2
>>> p.keylist2object(["key3",3])
{'float': 1.23}
>>> p.keylist2object(["key3",3,"float"])
1.23
>>> p.keylist2object(["key3",3,"floatx"])
Traceback (most recent call last):
   ...
KeyError: "['key3', 3, 'floatx'] not found (subkey: 'floatx')"
keylist_set(keylist, new_value=None, always_dicts=False)[source]

set the object that is identified by a keylist.

This method sets a value in the StructuredDataStore that is referred by the given keylist. When the parameter create_missing is True, this function can also create data structures on the fly when the given keys do not yet exist at some place in the structure. The last data item created is given by the parameter new_value, which defaults to the value “None”. Note that updates the internal link dictionary correctly only if the value given is not yet present in the StructuredDataStore. If the value is already present in the StructuredDataStore you should use the method link instead.

Here are some examples:

>>> p=StructuredDataStore({})
>>> p.keylist_set(["ab"])
>>> p
StructuredDataStore({'ab': None})
>>> p.keylist_set(["ab","x","y",1,"a"])
>>> p
StructuredDataStore({'ab': {'x': {'y': [None, {'a': None}]}}})
>>> p.keylist_set(["ab","x","z"],"myvalue")
'myvalue'
>>> p
StructuredDataStore({'ab': {'x': {'y': [None, {'a': None}], 'z': 'myvalue'}}})

sets store[from_path]= store[to_path].

This function creates a link. The data for the path “from_path” is changed to refer to the same data as the path “to_path”. This function updates the internal link dictionary accordingly.

Here are some examples:

>>> d= { "A": { "B": 1, "C": 2}, 
...      "x": {"y":None},
...      "l": [["val"], 1, None]
...    }
>>> s= StructuredDataStore(d)
>>> print s
StructuredDataStore(
  { 'A': { 'B': 1, 'C': 2}, 'l': [['val'], 1, None], 'x': { 'y': None}}
)
>>> s.link("x.y", "A")
>>> print s
StructuredDataStore(
  { 'A': { 'B': 1, 'C': 2},
    'l': [['val'], 1, None],
    'x': { 'y': { 'B': 1, 'C': 2}}}
)
>>> s.get_links("A")
set(['x.y', 'A'])
>>> s.link("l[2]","l[0]")
>>> print s
StructuredDataStore(
  { 'A': { 'B': 1, 'C': 2},
    'l': [['val'], 1, ['val']],
    'x': { 'y': { 'B': 1, 'C': 2}}}
)
>>> s.get_links("l[0]")
set(['l[2]', 'l[0]'])

return a dictionary mapping ids to sets of keylists.

This function returns a dictionary mapping object IDs to sets of keylists. The dictionary only contains entries for objects that are referred by the StructuredDataStore at at least two places. The dictionary is computed by iterating over all possible paths in the StructuredDataStore, so it may take some time to complete.

Here are some examples:

>>> d= { "A": { "B": 1, "C": 2}, 
...      "x": {"y":None},
...      "l": [["val"], 1, None]
...    }
>>> d["x"]["y"]= d["A"]
>>> d["l"][2]= d["l"][0]
>>> s= StructuredDataStore(d)

Since the ids in the returned dictionary are not reproducible within this doctest code, we cannot print them directly:

>>> def myprint(linkdict):
...     d= {}
...     l= sorted([list(x) for x in linkdict.values()])
...     idx=1
...     for it in l:
...         d[idx]= set(it)
...         idx+=1
...     pprint.pprint(d)
>>> myprint(s.links_keylist_sets())
{1: set([('l', 0), ('l', 2)]), 2: set([('A',), ('x', 'y')])}

return a dict mapping ids to sets of paths refer to the same data.

This function is similar to links_keylist_sets but it returns a dictionary mapping object IDs to sets of paths.

Here are some examples:

>>> d= { "A": { "B": 1, "C": 2}, 
...      "x": {"y":None},
...      "l": [["val"], 1, None]
...    }
>>> d["x"]["y"]= d["A"]
>>> d["l"][2]= d["l"][0]
>>> s= StructuredDataStore(d)

Since the ids in the returned dictionary are not reproducible within this doctest code, we cannot print them directly:

>>> def myprint(linkdict):
...     d= {}
...     l= sorted([list(x) for x in linkdict.values()])
...     idx=1
...     for it in l:
...         d[idx]= set(it)
...         idx+=1
...     pprint.pprint(d)
>>> myprint(s.links_path_sets())
{1: set(['l[0]', 'l[2]']), 2: set(['A', 'x.y'])}
listdelitem(keylist)[source]

deletes an item from the store.

This is similar to delitem but gets a keylist instead of a path.

Here is an example:

>>> d={"key1":1, "key2": {"A":"x","B":"y"}, "key3":[1,2,3,{"float":1.23}]}
>>> p= StructuredDataStore(d)
>>> print p
StructuredDataStore(
  { 'key1': 1,
    'key2': { 'A': 'x', 'B': 'y'},
    'key3': [1, 2, 3, { 'float': 1.23}]}
)
>>> p.listdelitem(["key3",3,"float"])
>>> print p
StructuredDataStore(
  { 'key1': 1, 'key2': { 'A': 'x', 'B': 'y'}, 'key3': [1, 2, 3, { }]}
)
>>> p.listdelitem(["key3",3])
>>> print p
StructuredDataStore(
  { 'key1': 1, 'key2': { 'A': 'x', 'B': 'y'}, 'key3': [1, 2, 3]}
)
listsetitem(keylist, val, create_missing=False, always_dicts=False)[source]

similar to setitem, but gets a keylist.

This method sets for a given path the part of the StructuredDataStore it addresses. If the parameter create_missing is True, this function can also create data structures on the fly when the given keys do not yet exist at some place in the structure. If the parameter always_dicts is True, the created structures are always dicts and never lists even if some of the elements of the path are integers.

lock()[source]

make the StructuredDataStore read-only.

path2object(path)[source]

get the object a path points to.

This method returns for a given path the part of the StructuredDataStore it adresses.

Here are some examples:

>>> d={"key1":1, "key2": {"A":"x","B":"y"}, "key3":[1,2,3,{"float":1.23}]}
>>> p= StructuredDataStore(d)
>>> p.path2object("key2")
{'A': 'x', 'B': 'y'}
>>> p.path2object("key2.A")
'x'
>>> p.path2object("key3[1]")
2
>>> p.path2object("key3[3]")
{'float': 1.23}
>>> p.path2object("key3[3].float")
1.23
>>> p.path2object("key3[3].floatx")
Traceback (most recent call last):
    ...
KeyError: "['key3', 3, 'floatx'] not found (subkey: 'floatx')"

do get_links for all paths that match a pattern.

This function returns a sorted list of sets of paths where each path in each set refers to the same data. At least one path in each set of paths matches the given pattern.

Here are some examples:

>>> d= { "A": { "B": 1, "C": 2}, 
...      "x": {"y":None},
...      "l": [["val"], 1, None]
...    }
>>> d["x"]["y"]= d["A"]
>>> d["l"][2]= d["l"][0]
>>> s= StructuredDataStore(d)
>>> s.pattern_get_links("l.*")
[set(['l[2]', 'l[0]'])]
>>> s.pattern_get_links("*")
[set(['x.y', 'A'])]
>>> s.pattern_get_links("*.y")
[set(['x.y', 'A'])]
>>> s.pattern_get_links("*.z")
[]
>>> s.pattern_get_links("*",only_multi_links= True)
[set(['x.y', 'A'])]
>>> s.pattern_get_links("*",only_multi_links= False)
[set(['x.y', 'A']), set(['x']), set(['l'])]
>>> s.pattern_get_links("*.y",exclude="*")
[set(['x.y'])]
>>> s.pattern_get_links("*.y",exclude="*.*")
[set(['A'])]
>>> s.pattern_get_links("*",include="*.*")
[set(['x.y'])]
>>> s.pattern_get_links("*",include="*")
[set(['A'])]

refresh the information on links.

This function refreshes the internal link directory of the StructuredDataStore. Since it iterates over all possible paths in the StructuredDataStore it may take some time to complete. You should call this function if you need information about links in the StructuredDataStore after the data has been modifed by functions directly operating on the internal dictionary or after data has been imported.

Here are some examples:

>>> d= { "A": { "B": 1, "C": 2}, 
...      "x": {"y":None},
...      "l": [["val"], 1, None]
...    }
>>> d["x"]["y"]= d["A"]
>>> d["l"][2]= d["l"][0]
>>> s= StructuredDataStore(d)
>>> s.refresh_links()

Since the ids in the returned dictionary are not reproducible within this doctest code, we cannot print them directly:

>>> def myprint(linkdict):
...     d= {}
...     l= sorted([list(x) for x in linkdict.values()])
...     idx=1
...     for it in l:
...         d[idx]= set(it)
...         idx+=1
...     pprint.pprint(d)
>>> myprint(s._link_dict)
{1: set([('l', 0), ('l', 2)]), 2: set([('A',), ('x', 'y')])}

search all paths for a given regexp pattern.

This method is used to search the paths by a given regular expression. It returns a list of paths or a list of path-value pairs. See the documentation of the python module “re” for regular expressions. If the parameter add_values is True, the values addressed by the paths are included in the result.

Here are some examples:

>>> d={"key1":1, "key2": {"A":"x","B":"y"}, "key3":[1,2,3,{"float":1.23}]}
>>> p= StructuredDataStore(d)
>>> print  p
StructuredDataStore(
  { 'key1': 1,
    'key2': { 'A': 'x', 'B': 'y'},
    'key3': [1, 2, 3, { 'float': 1.23}]}
)
>>> print p.regexp_search(r'.*1')
['key3[1]', 'key1']
>>> print p.regexp_search(r'.*1', add_values= False)
['key3[1]', 'key1']
>>> print p.regexp_search(r'.*float', add_values= False)
['key3[3].float']
>>> print p.regexp_search(r'.*float', add_values= True)
[('key3[3].float', 1.23)]
>>> print p.regexp_search(r'^k.*\b[A-Z]', add_values= True)
[('key2.A', 'x'), ('key2.B', 'y')]
>>> d={"key1":1, "key2": {"A":"x","B":"y"}, "key3":[1,2,3,{"float":1.23}]}
>>> d["key2"]["C"]= d["key3"]
>>> p= StructuredDataStore(d)
>>> print p
StructuredDataStore(
  { 'key1': 1,
    'key2': { 'A': 'x', 'B': 'y', 'C': [1, 2, 3, { 'float': 1.23}]},
    'key3': [1, 2, 3, { 'float': 1.23}]}
)
>>> print p.regexp_search(r'.*1', show_links= True)
['key3*[1]', 'key2.C*[1]', 'key1']
>>> print p.regexp_search(r'.*float', add_values= True, show_links= True)
[('key3*[3].float', 1.23), ('key2.C*[3].float', 1.23)]
selection_iter(pattern, path_list, only_leaves, sorted_, show_links, paths_found_set=None)[source]

iteration through a path list.

Here are some examples:

>>> d={"key1":1, "key2": {"A":"x","B":"y"}, "key3":[1,2,3,{"float":1.23}]}
>>> p= StructuredDataStore(d)
>>> def test(s,pattern,path_list,only_leaves,sorted_,
...          show_links=False, paths_found_set= None):
...   for l in s.selection_iter(pattern,path_list,only_leaves,
...                             sorted_,show_links,paths_found_set):
...     print repr(l)
>>> test(p,"",['key3[0]','key3[3]'],False,False)
('key3[0]', ['key3', 0], 1)
('key3[3]', ['key3', 3], {'float': 1.23})
>>> test(p,"",[('key3[0]',1),('key3[2]',3)],False,False)
('key3[0]', ['key3', 0], 1)
('key3[2]', ['key3', 2], 3)
>>> pset= set()
>>> test(p,"",['key3[0]','key3[3]','key3[3].float'],True,True,False,pset)
('key3[0]', ['key3', 0], 1)
('key3[3].float', ['key3', 3, 'float'], 1.23)
>>> test(p,"",['key3[0]','key3[3]','key3[3].float'],False,True,False,pset)
('key3[3]', ['key3', 3], {'float': 1.23})
>>> d={"key1":{"A":"x1","B":"y1"}, 
...    "key2":{"A":"x2","B":"y2"}, 
...    "key3":[1,2,3,{"float":1.23}]}
>>> p= StructuredDataStore(d)
>>> test(p,"key1",['key1','key1.A','key2.A'],False,True)
('key1', ['key1'], {'A': 'x1', 'B': 'y1'})
>>> test(p,"key1.**",['key1','key1.A','key2.A'],False,True)
('key1.A', ['key1', 'A'], 'x1')
>>> test(p,"*.A",['key1','key1.A','key2.A'],False,True)
('key1.A', ['key1', 'A'], 'x1')
('key2.A', ['key2', 'A'], 'x2')
>>> d={"key1":{"A":"x1","B":"y1"}}
>>> d["key1"]["B"]= d["key1"]
>>> p= StructuredDataStore(d)
>>> test(p,"",["key1","key1.A","key1.B"],False,True)
('key1', ['key1'], {'A': 'x1', 'B': {...}})
('key1.A', ['key1', 'A'], 'x1')
('key1.B', ['key1', 'B'], {'A': 'x1', 'B': {...}})
>>> test(p,"",["key1","key1.A","key1.B"],False,True,True)
('key1*', [('key1', '*')], {'A': 'x1', 'B': {...}})
('key1*.A', [('key1', '*'), 'A'], 'x1')
('key1*.B*', [('key1', '*'), ('B', '*')], {'A': 'x1', 'B': {...}})
setitem(path, val, create_missing=False, always_dicts=False)[source]

set the object the path points to.

This method sets for a given path the part of the StructuredDataStore it addresses. If the parameter create_missing is True, this function can also create data structures on the fly when the given keys do not yet exist at some place in the structure. If the parameter always_dicts is True, the created structures are always dicts and never lists even if some of the elements of the path are integers.

Here are some examples:

>>> d={"key1":1, "key2": {"A":"x","B":"y"}, "key3":[1,2,3,{"float":1.23}]}
>>> p= StructuredDataStore(d)
>>> print p
StructuredDataStore(
  { 'key1': 1,
    'key2': { 'A': 'x', 'B': 'y'},
    'key3': [1, 2, 3, { 'float': 1.23}]}
)
>>> p["key1"]= 10
>>> print p
StructuredDataStore(
  { 'key1': 10,
    'key2': { 'A': 'x', 'B': 'y'},
    'key3': [1, 2, 3, { 'float': 1.23}]}
)
>>> p["key2.A"]= "xx"
>>> print p
StructuredDataStore(
  { 'key1': 10,
    'key2': { 'A': 'xx', 'B': 'y'},
    'key3': [1, 2, 3, { 'float': 1.23}]}
)
>>> p["key3[3].float"]= 2.46
>>> print p
StructuredDataStore(
  { 'key1': 10,
    'key2': { 'A': 'xx', 'B': 'y'},
    'key3': [1, 2, 3, { 'float': 2.46}]}
)
>>> p["key3[3].floatx"]= 3.46
Traceback (most recent call last):
    ...
KeyError: "['key3', 3, 'floatx'] not found (subkey: 'floatx')"
>>> p.setitem("key3[3].floatx",3.46,create_missing=True)
>>> print p
StructuredDataStore(
  { 'key1': 10,
    'key2': { 'A': 'xx', 'B': 'y'},
    'key3': [1, 2, 3, { 'float': 2.46, 'floatx': 3.46}]}
)
setitems(pairs, create_missing=False, always_dicts=False)[source]

add new items to the object from a list of pairs.

This method sets for a list of path-value pairs part of the StructuredDataStore they address. If the parameter create_missing is True, this function can also create data structures on the fly when the given keys do not yet exist at some place in the structure.

search all paths for a given pattern.

This method is used to search the paths by a given pattern or list of patterns. It returns a list of paths or a list of path-value pairs.

parameters:

path_patterns
This may be a pattern (a string) or a list of patterns (a list of strings). Only paths that match this or these patterns are returned.
add_values
If this is True, the returned list contains pairs of the path and the value. Otherwise, only paths are returned in the list.
only_leaves
If this is true, only nodes that are scalars are returned.
show_links
If this is true, links are marked in the result.

returns:

A list consisting of paths or path-value pairs.

Here are some examples:

>>> d={"key1":1, "key2": {"A":"x","B":"y"}, "key3":[1,2,3,{"float":1.23}]}
>>> p= StructuredDataStore(d)
>>> print  p
StructuredDataStore(
  { 'key1': 1,
    'key2': { 'A': 'x', 'B': 'y'},
    'key3': [1, 2, 3, { 'float': 1.23}]}
)
>>> print p.simple_search("*.A", add_values=False)
['key2.A']
>>> print p.simple_search("key2.**", add_values=False)
['key2.A', 'key2.B']
>>> print p.simple_search("key3.*.float", add_values=False)
['key3[3].float']
>>> pl=["key2","key2.B","key3[3].float"]
>>> print p.simple_search("*.A", path_list=pl, add_values=False)
[]
>>> print p.simple_search("*.B", path_list=pl, add_values=False)
['key2.B']
>>> print p.simple_search("key2.**", add_values=False)
['key2.A', 'key2.B']
>>> print p.simple_search("key2.**", path_list= pl, add_values=False)
['key2.B']
>>> print p.simple_search("key3.*.float", add_values=True)
[('key3[3].float', 1.23)]
>>> print p.simple_search("key3.**", add_values=True)
[('key3[0]', 1), ('key3[1]', 2), ('key3[2]', 3), ('key3[3].float', 1.23)]
>>> print p.simple_search("key3.*", add_values=True)
[('key3[0]', 1), ('key3[1]', 2), ('key3[2]', 3)]
>>> print p.simple_search("*.A",["key1","key2.A","key2.B"], 
...                       add_values=False)
['key2.A']
>>> print p.simple_search("*.A",["key1","key2.B"], add_values=False)
[]
>>> d={"key1":1, "key2": {"A":"x","B":"y"}, "key3":[1,2,3,{"float":1.23}]}
>>> d["key2"]["C"]= d["key3"]
>>> p= StructuredDataStore(d)
>>> print p
StructuredDataStore(
  { 'key1': 1,
    'key2': { 'A': 'x', 'B': 'y', 'C': [1, 2, 3, { 'float': 1.23}]},
    'key3': [1, 2, 3, { 'float': 1.23}]}
)
>>> print p.simple_search("*.B", add_values=False, show_links=True)
['key2.B']
>>> print p.simple_search("*.C.**", add_values=False, show_links=True)
['key2.C*[0]', 'key2.C*[1]', 'key2.C*[2]', 'key2.C*[3].float']
>>> print p.simple_search("*.C.*", add_values=True, show_links=True)
[('key2.C*[0]', 1), ('key2.C*[1]', 2), ('key2.C*[2]', 3)]
static split_path(path)[source]

splits a path into a keylist.

This static method splits a given path to a list of keys. Note that in the returned list, strings are map keys and integers are list indices. If the path is a pattern, the returned keylist may contain SpecialKey objects like ANYREY or ANYKEYS.

>>> print StructuredDataStore.split_path("A.B")
['A', 'B']
>>> print StructuredDataStore.split_path("")
[]
>>> print StructuredDataStore.split_path(r"A\.B.C")
['A.B', 'C']
>>> print StructuredDataStore.split_path("A[2].C")
['A', 2, 'C']
>>> StructuredDataStore.split_path("A[xy].C")
['A', '[xy]', 'C']
>>> StructuredDataStore.split_path("A[4][3].C")
['A', 4, 3, 'C']
>>> StructuredDataStore.split_path("A.*.C")
['A', ANYKEY, 'C']
>>> StructuredDataStore.split_path("A.**.C")
['A', ANYKEYS, 'C']
universal_iter(patterns, path_list, only_leaves, sorted_, show_links)[source]

universal iteration through the StructuredDataStore with path_list.

Here are some examples:

>>> d={"key1":1, "key2": {"A":"x","B":"y"}, "key3":[1,2,3,{"float":1.23}]}
>>> p= StructuredDataStore(d)
>>> def test(s,patterns,path_list,only_leaves,sorted_,
...          show_links=False):
...   for l in s.universal_iter(patterns,path_list,only_leaves,
...                             sorted_,show_links):
...     print repr(l)
... 
>>> test(p,"",['key3[0]','key3[3]'],False,False)
('key3[0]', ['key3', 0], 1)
('key3[3]', ['key3', 3], {'float': 1.23})
>>> test(p,"",None,False,False)
('key3', ['key3'], [1, 2, 3, {'float': 1.23}])
('key3[0]', ['key3', 0], 1)
('key3[1]', ['key3', 1], 2)
('key3[2]', ['key3', 2], 3)
('key3[3]', ['key3', 3], {'float': 1.23})
('key3[3].float', ['key3', 3, 'float'], 1.23)
('key2', ['key2'], {'A': 'x', 'B': 'y'})
('key2.A', ['key2', 'A'], 'x')
('key2.B', ['key2', 'B'], 'y')
('key1', ['key1'], 1)
>>> test(p,"key3.**",['key3','key3[0]','key3[3]'],False,False)
('key3[0]', ['key3', 0], 1)
('key3[3]', ['key3', 3], {'float': 1.23})
>>> test(p,"key3.**",[],False,False)
('key3[0]', ['key3', 0], 1)
('key3[1]', ['key3', 1], 2)
('key3[2]', ['key3', 2], 3)
('key3[3]', ['key3', 3], {'float': 1.23})
('key3[3].float', ['key3', 3, 'float'], 1.23)
>>> test(p,["key2.**","key3.**"],[],False,False)
('key2.A', ['key2', 'A'], 'x')
('key2.B', ['key2', 'B'], 'y')
('key3[0]', ['key3', 0], 1)
('key3[1]', ['key3', 1], 2)
('key3[2]', ['key3', 2], 3)
('key3[3]', ['key3', 3], {'float': 1.23})
('key3[3].float', ['key3', 3, 'float'], 1.23)
update(data)[source]

updates the StructuredDataStore from the given dictionary.

This updates the StructuredData object from a given dictionary. Note that existing dictionaries are replaced by the ones in the given data. You usually want to use the “add” method instead of this one.

search all paths for a given i-pattern.

An “i-pattern” is a list of space separated sub-strings. All strings that contain all of these sub-strings in any order (compared case insensitive) match.

Here are some examples:

>>> d={"key1":1, "key2": {"A":1,"B":2}, "key3":[1,2,3,{"float":1.23}]}
>>> p= StructuredDataStore(d)
>>> print  p
StructuredDataStore(
  { 'key1': 1,
    'key2': { 'A': 1, 'B': 2},
    'key3': [1, 2, 3, { 'float': 1.23}]}
)
>>> print p.value_i_search("1")
['key3[0]', 'key3[3].float', 'key2.A', 'key1']
>>> print p.value_i_search("2")
['key3[1]', 'key3[3].float', 'key2.B']
>>> print p.value_i_search("1 2")
['key3[3].float']
>>> print p.value_i_search("1", path_list=["key2.A","key3"])
['key2.A']

search for a value with a regular expression.

This method is used to search the values by a given regular expression. It returns a list of paths or a list of path-value pairs. See the documentation of the python module “re” for regular expressions. If the parameter add_values is True, the values addressed by the paths are included in the result.

Here are some examples:

>>> d={"key1":1, "key2": {"A":1,"B":2}, "key3":[1,2,3,{"float":1.23}]}
>>> p= StructuredDataStore(d)
>>> print  p
StructuredDataStore(
  { 'key1': 1,
    'key2': { 'A': 1, 'B': 2},
    'key3': [1, 2, 3, { 'float': 1.23}]}
)
>>> print p.value_regexp_search("1")
['key3[0]', 'key3[3].float', 'key2.A', 'key1']
>>> print p.value_regexp_search("[23]")
['key3[1]', 'key3[2]', 'key2.B']
>>> print p.value_regexp_search("\.", add_values= True)
[]
>>> print p.value_regexp_search(r"\.", add_values= True)
[]
>>> print p.value_regexp_search(r".*\.", add_values= True)
[('key3[3].float', 1.23)]
>>> print p.value_regexp_search("1", path_list=["key2.A","key3"])
['key2.A']
>>> d={"key1":1, "key2": {"A":1,"B":2}, "key3":[1,2,3,{"float":1.23}]}
>>> d["key2"]["C"]= d["key3"]
>>> p= StructuredDataStore(d)
>>> print p
StructuredDataStore(
  { 'key1': 1,
    'key2': { 'A': 1, 'B': 2, 'C': [1, 2, 3, { 'float': 1.23}]},
    'key3': [1, 2, 3, { 'float': 1.23}]}
)
>>> pprint.pprint(p.value_regexp_search("1", show_links= True))
['key3*[0]',
 'key3*[3].float',
 'key2.A',
 'key2.C*[0]',
 'key2.C*[3].float',
 'key1']
>>> 
>>> pprint.pprint(p.value_regexp_search("[23]", show_links= True))
['key3*[1]', 'key3*[2]', 'key2.C*[1]', 'key2.C*[2]', 'key2.B']

search for an exact value.

This method looks for values that are equal to the given value. It returns a list of paths or a list of path-value pairs.

Here are some examples:

>>> d={"key1":1, "key2": {"A":1,"B":2}, "key3":[1,2,3,{"float":1.23}]}
>>> p= StructuredDataStore(d)
>>> print  p
StructuredDataStore(
  { 'key1': 1,
    'key2': { 'A': 1, 'B': 2},
    'key3': [1, 2, 3, { 'float': 1.23}]}
)
>>> print p.value_search(1)
['key3[0]', 'key2.A', 'key1']
>>> print p.value_search(1, add_values= True)
[('key3[0]', 1), ('key2.A', 1), ('key1', 1)]
>>> print p.value_search(1.23)
['key3[3].float']
>>> print p.value_search(1,path_list=["key2.A","key3"])
['key2.A']
>>> d={"key1":1, "key2": {"A":1,"B":2}, "key3":[1,2,3,{"float":1.23}]}
>>> d["key2"]["C"]= d["key3"]
>>> p= StructuredDataStore(d)
>>> print p
StructuredDataStore(
  { 'key1': 1,
    'key2': { 'A': 1, 'B': 2, 'C': [1, 2, 3, { 'float': 1.23}]},
    'key3': [1, 2, 3, { 'float': 1.23}]}
)
>>> print p.value_search(1, show_links= True)
['key3*[0]', 'key2.A', 'key2.C*[0]', 'key1']
>>> print p.value_search(1, add_values= True, show_links= True)
[('key3*[0]', 1), ('key2.A', 1), ('key2.C*[0]', 1), ('key1', 1)]
>>> print p.value_search(1.23, show_links= True)
['key3*[3].float', 'key2.C*[3].float']
class StructuredData.Classes.StructuredDataTypes(path_type_decl=None)[source]

a collection of type specifications for a number of paths.

This class provides a store for paths and associated type specifications.

It is a derivative of MatchPaths. For each path a typespec is specified. A typespec must be understandable by check_type_scalar.

add(path_type_decl)[source]

add paths and type specifications.

This method adds paths and type specifications from a given dictionary or a given list of pairs.

Here are some examples:

>>> t=StructuredDataTypes({"":"integer","*":"map","a.*":"list"})
>>> t.add({"b":"integer","c.d":"real"})
>>> t.add({"x":"blah"})
Traceback (most recent call last):
    ...
ValueError: unknown typespec: "blah"
as_path_dict()[source]

return the object as a dict.

Here is an example:

>>> import pprint
>>> t=StructuredDataTypes({"#":"integer","*":"map","a.*":"list"})
>>> pprint.pprint(t.as_path_dict())
{'#': 'integer', '*': 'map', 'a.*': 'list'}
check(path, value)[source]

typecheck a value for a given path.

This method takes a path and a value. It then searches the object for a matching path and checks the value against the type specification associated with the found path. If the typecheck fails, it raises an exception.

Here are some examples:

>>> d={ "#": {"optional_struct":["a","b"]},
...     "a": {"typed_map":"integer"},
...     "b": "map",
...     "b.*": {"typed_list":"string"},
...     "n[0]": "string",
...     "n.*": "integer",
...   }
>>> t= StructuredDataTypes(d)
>>> t.check("#", {"a":1})
>>> t.check("#", {"a":1})
>>> t.check("#", {"a":0,"b":1})
>>> t.check("#", {"a":0,"b":1,"c":2})
Traceback (most recent call last):
    ...
TypeError: key c not in list of allowed keys
>>> t.check("a", {1:"x",2:"y"})
>>> t.check("a", {1:"x",2:"y","z":"zz"})
Traceback (most recent call last):
    ...
TypeError: integer expected, got: 'z'
>>> t.check("a", 2)
Traceback (most recent call last):
    ...
TypeError: map expected
>>> t.check("b", {"y":1, 2:"a"})
>>> t.check("b", [1,2])
Traceback (most recent call last):
    ...
TypeError: map expected
>>> t.check("b.x", ["a","b"])
>>> t.check("b.x", ["a","b",3])
Traceback (most recent call last):
    ...
TypeError: string expected, got: 3
>>> t.check("b.x", 2)
Traceback (most recent call last):
    ...
TypeError: list expected
>>> t.check("n[0]", "ab")
>>> t.check("n[0]", 2)
Traceback (most recent call last):
    ...
TypeError: string expected, got: 2
>>> t.check("n[1]", 2)
>>> t.check("n[1]", "a")
Traceback (most recent call last):
    ...
TypeError: integer expected, got: 'a'
iterator_add(iterator)[source]

add paths and type specifications from an iterator.

This method adds paths and type specifications from a iterator. The iterator must provide pairs of a path and a type specification.

Here are some examples:

>>> t=StructuredDataTypes({"":"integer","*":"map","a.*":"list"})
>>> t.iterator_add({"b":"integer","c.d":"real"}.iteritems())
>>> t.iterator_add({"x":"blah"}.iteritems())
Traceback (most recent call last):
    ...
ValueError: unknown typespec: "blah"
StructuredData.Classes.andmatch(st, words)[source]

returns True if st contains all the words in any order.

The comparison is case insensitive. Here are some examples: >>> st=”this is the string that contains some words” >>> andmatch(st,[“this”]) True >>> andmatch(st,[“that”,”this”]) True >>> andmatch(st,[“that”,”this”,”there”]) False >>> andmatch(st,[“THIS”, “There”]) False >>> andmatch(st,[“THIS”, “That”]) True >>> andmatch(st,[“THIS”, “That”, “contains”]) True

StructuredData.Classes.check_type(var, spec, dry_run=False)[source]

implement more complex typechecks.

These are the known types:

SDTypes.boolean
a bool
SDTypes.integer
an int
SDTypes.real
a float
SDTypes.string
a str
SDTypes.optional_struct [<list of items>]
This is a dict where each key must be present in the <list of items>.
SDTypes.open_struct [<list of items>]
This is a dict where each item of <list of items> must be present as a key. Aside from this, the dict may contain an arbitrary set of additional of keys.
SDTypes.struct [<list of items>]
This is a dict where each item of <list of items> must be present as a key. No other keys are allowed than the ones listed in <list of items>.
SDTypes.typed_map <scalar type>
This is a dict where each key must be of the type <scalar type>. <scalar type> may be SDTypes.integer, “float” or SDTypes.string.
SDTypes.map
This is simply a dict.
SDTypes.optional_list [<list of items>]
This is a list where each item must be present in <list of items>.
SDTypes.typed_list <scalar type>
This is a list where each item must be of the type <scalar type>. <scalar type> may be SDTypes.integer, “float” or SDTypes.string.
SDTypes.list
This is simply a list.

Here are some examples:

>>> check_type(True,SDTypes.boolean)
>>> check_type(False,SDTypes.boolean)
>>> check_type("A",SDTypes.boolean)
Traceback (most recent call last):
    ...
TypeError: boolean expected, got: 'A'
>>> check_type(1,SDTypes.integer)
>>> check_type(1.2,SDTypes.integer)
Traceback (most recent call last):
    ...
TypeError: integer expected, got: 1.2
>>> check_type(1.2,SDTypes.real)
>>> check_type(1,SDTypes.real)
>>> check_type("A",SDTypes.real)
Traceback (most recent call last):
    ...
TypeError: real number expected, got: 'A'
>>> check_type("A",SDTypes.string)
>>> check_type(1,SDTypes.string)
Traceback (most recent call last):
    ...
TypeError: string expected, got: 1

Tests with the type SDTypes.optional_struct:

>>> check_type({"a":1,"c":1},{SDTypes.optional_struct:["a","b","c"]})
>>> check_type({"a":1,"d":1},{SDTypes.optional_struct:["a","b","c"]})
Traceback (most recent call last):
        ...
TypeError: key d not in list of allowed keys
>>> check_type(["a","b"],{SDTypes.optional_struct:["a","b","c"]})
Traceback (most recent call last):
        ...
TypeError: structure expected

Tests with the type SDTypes.open_struct:

>>> check_type({"a":1,"b":1,"c":1},{SDTypes.open_struct:["a","b","c"]})
>>> check_type({"a":1,"b":1,"c":1,"d":1},{SDTypes.open_struct:["a","b","c"]})
>>> check_type({"a":1,"b":1,"d":1},{SDTypes.open_struct:["a","b","c"]})
Traceback (most recent call last):
    ...
TypeError: key c is missing

Tests with the type SDTypes.struct:

>>> check_type({"a":1,"b":1,"c":1},{SDTypes.struct:["a","b","c"]})
>>> check_type({"a":1,"b":1},{SDTypes.struct:["a","b","c"]})
Traceback (most recent call last):
    ...
TypeError: mandatory key c is missing
>>> check_type({"a":1,"b":1,"c":1,"d":1},{SDTypes.struct:["a","b","c"]})
Traceback (most recent call last):
    ...
TypeError: key d is not in list of allowed keys

Tests with the type SDTypes.typed_map:

>>> check_type({"a":1,"b":1},{SDTypes.typed_map:SDTypes.string})
>>> check_type({2:1,"b":1},{SDTypes.typed_map:SDTypes.string})
Traceback (most recent call last):
    ...
TypeError: string expected, got: 2

Tests with the type SDTypes.map:

>>> check_type({"a":1,"c":1},SDTypes.map)
>>> check_type([1,2],SDTypes.map)
Traceback (most recent call last):
    ...
TypeError: map expected
>>> check_type(1,SDTypes.map)
Traceback (most recent call last):
    ...
TypeError: map expected

Tests with the type SDTypes.optional_list:

>>> check_type(["a","c"],{SDTypes.optional_list:["a","b","c"]})
>>> check_type(["a","d"],{SDTypes.optional_list:["a","b","c"]})
Traceback (most recent call last):
    ...
TypeError: item d not in list of allowed keys
>>> check_type({"a":1,"b":2},{SDTypes.optional_list:["a","b","c"]})
Traceback (most recent call last):
    ...
TypeError: list expected

Tests with the type SDTypes.typed_list:

>>> check_type(["a","b"],{SDTypes.typed_list:SDTypes.string})
>>> check_type(["a","b",1],{SDTypes.typed_list:SDTypes.string})
Traceback (most recent call last):
    ...
TypeError: string expected, got: 1

Tests with the type SDTypes.list:

>>> check_type([1,2],SDTypes.list)
>>> check_type({"a":1,"c":1},SDTypes.list)
Traceback (most recent call last):
    ...
TypeError: list expected
>>> check_type(1,SDTypes.list)
Traceback (most recent call last):
    ...
TypeError: list expected
StructuredData.Classes.check_type_scalar(var, spec, dry_run=False)[source]

implement a simple typecheck.

Three basic scalar types are implemented here: SDTypes.boolean: a bool SDTypes.integer: an int SDTypes.real : a float SDTypes.string : a str

Here are some examples:

>>> check_type_scalar(1,SDTypes.integer)
>>> check_type_scalar(1.2,SDTypes.integer)
Traceback (most recent call last):
    ...
TypeError: integer expected, got: 1.2
>>> check_type_scalar(1.2,SDTypes.real)
>>> check_type_scalar(1,SDTypes.real)
>>> check_type_scalar("A",SDTypes.real)
Traceback (most recent call last):
    ...
TypeError: real number expected, got: 'A'
>>> check_type_scalar("A",SDTypes.string)
>>> check_type_scalar(1,SDTypes.string)
Traceback (most recent call last):
    ...
TypeError: string expected, got: 1
>>> check_type_scalar(True,SDTypes.boolean)
>>> check_type_scalar(False,SDTypes.boolean)
>>> check_type_scalar("True",SDTypes.boolean)
Traceback (most recent call last):
    ...
TypeError: boolean expected, got: 'True'
>>> check_type_scalar(1,SDTypes.boolean)
Traceback (most recent call last):
    ...
TypeError: boolean expected, got: 1
StructuredData.Classes.escape_in_stringkey(st)[source]

escape special characters with a backslash.

replace ‘.’ with ‘.’ and ‘[number]’ with ‘[number]’ This is needed in order to convert path which contains the characters ‘.’ or ‘[‘ or ‘]’ to a keylist. (see class StructuredDataStore).

Here are some examples:

>>> print escape_in_stringkey("AB")
AB
>>> print escape_in_stringkey("A.B")
A\.B
>>> print escape_in_stringkey("A.B[5]C")
A\.B\[5\]C
>>> print escape_in_stringkey("*")
\*
>>> print escape_in_stringkey("**")
\**
>>> print escape_in_stringkey("#")
\#
>>> print escape_in_stringkey("A#")
A#
>>> print escape_in_stringkey("A*")
A*
>>> print escape_in_stringkey(r"\*")
\\*
>>> print escape_in_stringkey(r"\\*")
\\\*
>>> print escape_in_stringkey(r"\**")
\\**
>>> print escape_in_stringkey(r"\#")
\\#
>>> print escape_in_stringkey(r"\\#")
\\\#
StructuredData.Classes.imatch(st, pattern)[source]

returns True if st contains all the words from pattern in any order. The comparison is case insensitive.

Here are some examples: >>> st=”this is the string that contains some words” >>> imatch(st, “this”) True >>> imatch(st, “that this”) True >>> imatch(st, “this that there”) False >>> imatch(st, “THIS There”) False >>> imatch(st, “THIS That”) True >>> imatch(st, “THIS That contains”) True

StructuredData.Classes.string_to_keyobject(val)[source]

convert a wildcard to be used by the MatchPaths object.

uses ROOTKEY, ANYKEY and ANYKEYS.

StructuredData.Classes.unescape_in_stringkey(st)[source]

unescape special characters.

replace ‘.’ with ‘.’ and ‘[number]’ with ‘[number]’ This is needed in order to convert keylist to a path which contains the characters ‘.’ or ‘[‘ or ‘]’. (see class StructuredDataStore).

Here are some examples:

>>> print unescape_in_stringkey("AB")
AB
>>> print unescape_in_stringkey("A\.B\[2\]C")
A.B[2]C
>>> print unescape_in_stringkey("\*")
*
>>> print unescape_in_stringkey("\**")
**
>>> print unescape_in_stringkey("\#")
#
>>> print unescape_in_stringkey("\*A")
\*A
>>> print unescape_in_stringkey("\#A")
\#A
>>> print unescape_in_stringkey(r"\\*")
\*
>>> print unescape_in_stringkey(r"\\**")
\**
>>> print unescape_in_stringkey(r"\\#")
\#