pology.synder.Synder

Package pology :: Module synder :: Class Synder |

# Class Synder

    object --+
             |
            Synder

Derivator objects import sources of derivations and get queried for properties of syntagmas.

Lookup can be done by derivation key and property key, but also by single compound key (serialization of the previous two), to have interface and behavior similar to built-in dictionaries.

Basic usage is rather simple. If there are derivation files `planets.sd` and {moons.sd}, they can be used like this:

       >>> sd = Synder()
       >>> sd.import_file("planets.sd")
       >>> sd.import_file("moons.sd")
       >>>
       >>> # Lookup of properties by derivation and property key.
       >>> sd.get2("Venus", "nom")
       Venera
       >>> sd.get2("Callisto", "nom")
       Kalisto
       >>> sd.get2("Foobar", "nom")
       None
       >>> # Lookup of properties by compound key.
       >>> sd["Venus-nom"]
       Venera
       >>>
       >>> # Iteration through properties by derivation keys.
       >>> for dkey in sd.dkeys(): print sd.get2(dkey, "nom")
       ...
       Venera
       Kalisto
       Merkur
       Jupiter
       …
       >>> # Iteration through properties by compound keys.
       >>> for ckey in sd: print sd[ckey]
       ...
       Venera
       Veneri
       Venerom
       …
       Merkuru
       Merkur
       Merkura
       …
       >>> # Querying for key syntagmas.
       >>> sd.syns("Venus")
       ['Venus']
       >>> sd.syns("Iapetus")
       ['Iapetus', 'Japetus']
       >>> sd.syns("Japetus")
       ['Iapetus', 'Japetus']
       >>>
       >>> # Querying for property keys.
       >>> sd.pkeys("Venus")
       ['gen', 'acc', 'nom', 'dat', 'gender']

Syntax errors in derivations sources will raise SynderError exceptions on import. Unresolvable conflicts in derivation keys will be reported as warning on import, and conflicted derivations will not be imported. Errors in expansions are not reported on import, but when the problematic derivation is queried; warnings are output, and `None` (or default value) is returned for all properties.

Instance Methods
__init__(self, env=`'````'`, ckeysep=`'``-``'`, strictkey=False, dkeytf=None, dkeyitf=None, pkeytf=None, pkeyitf=None, pvaltf=None, ksyntf=None, envtf=None) Constructor of syntagma derivators. |
int |
import_string(self, string, ignhid=False) Import string with derivations. |
int |
import_file(self, filename, ignhid=False) Import file with derivations. |
string |
get2(self, dkey, pkey, defval=None) Get property value by derivation key and property key. |
string |
get(self, ckey, defval=None) Get property value by compound key. |
[string*] |
dkeys(self, single=False) Get list of all derivation keys. |
[string*] |
syns(self, dkey) Get list of key syntagmas by derivation key. |
[string*] |
altdkeys(self, dkey) Get list of all derivation keys pointing to same entry as given key. |
set(string*) |
pkeys(self, dkey) Get set of property keys available for given derivation key. |
{(string, string)*} |
props(self, dkey) Get dictionary of property values by property keys for given derivation key. |
[string*] |
envs(self, dkey) Get list of all explicitly defined environments in given derivation. |
string |
source_name(self, dkey) Get the name of the source in which the derivation is found. |
(string, int, int) |
source_pos(self, dkey) Get the position in the source where the derivation is found. |
[string*] |
keys(self) Get the list of all compound keys. |
[string*] |
values(self) Get the list of all property values. |
[(string, string)*] |
items(self) Get the list of all pairs of compound keys and property values. |
bool |
__contains__(self, ckey) Check if the compound key is present in the derivator. |
string |
__getitem__(self, ckey) Get property value by compound key, in dictionary notation. |
iterator(string) |
__iter__(self) Iterate through all compound keys, in random order. |
iterator(string) |
iterkeys(self) Iterate through all compound keys, in random order. |
iteratorstring) |
itervalues(self) Iterate through all property values, in random order. |
iterator((string, string)) |
iteritems(self) Iterate through all pairs of compound key and property value, in random order. |
empty_pcache(self) |
Inherited from `object`: `__delattr__`, `__format__`, `__getattribute__`, `__hash__`, `__new__`, `__reduce__`, `__reduce_ex__`, `__repr__`, `__setattr__`, `__sizeof__`, `__str__`, `__subclasshook__`

Properties
Inherited from `object`: `__class__`

Method Details

### __init__(self, env=`'````'`, ckeysep=`'``-``'`, strictkey=False, dkeytf=None, dkeyitf=None, pkeytf=None, pkeyitf=None, pvaltf=None, ksyntf=None, envtf=None) (Constructor) |
Constructor of syntagma derivators. The default resolution of derivation key conflicts, as described in module documentation, can be changed to strict resolution through `strictkey` parameter. If `strictkey` is `True`, all key syntagmas must be unique. Parameter `env` is used to specify the environment from which the derivations are taken. In case no non-default environments have been used in derivations, `env` is simply empty string. Otherwise, it can be: a string specifying a non-default environment a tuple specifying an environment fallback chain a tuple of tuples, specifying more than one environment chain (Lists can also be used instead of tuples.) If several environment fallback chains are given, when a property is requrested they are tried in the order of specification, and the first yielded property is returned. It is also possible to combine properties from different environment chains in a custom way, by supplying a property value transformation function (`pvaltf` parameter). Compound keys, for single-key lookups, are built by joining the derivation and property keys with a separator. This separator can be chosen through `ckeysep` parameter. The separator string can be contained inside a derivation key, but it must not be found inside any property key (the compound key is split from the back). A myriad of transformation functions can be applied by derivator object to imported derivations, through `*tf` parameters. They are as follows (stating only default inputs, see below for more possibilities): `dkeytf`: applied to derivation key supplied on lookups (e.g. in get or get2 methods). Takes the derivation key as parameter, returns either the derivation key or a tuple of the derivation key and another object. `dkeyitf`: applied to all derivation keys on import. Same default input-output as `dkey`. `pkeytf`: like `dkeytf`, only working analogously on property key instead of derivation key. `pkeyitf`: like `dkeyitf`, only working analogously on property key instead of derivation key. `pvaltf`: applied to tagged segments of property values. The input to this function is a list of lists by each environment fallback chain; list for one environemnt chain consists of 2-tuples, each tuple having a list of tags as the first element, and a text segment as the second element. For example, if there is only one environment chain (e.g. `evn=""` or `env=("someenv", "")`, and the property value is derived to be `foo ~tag bar` in this environment, then the argument to the function will be `[[([''], "foo "), (['tag'], " bar")]]`. If an environemnt chain yielded no property value, its element will be `None` instead of list of 2-tuples. The return value is the final property value string. Note that simplification will not be applied to this value afterwards, so if desired, simplify() should be manually called inside the function. `ksyntf`: quite similar to `pvaltf`, only applied to tagged segments of key syntagmas. The difference is that there are no multiple environments for key syntagmas, so the input value is just one list of tagged text segments (what would be the first element of input list to `pvaltf`). `envtf`: applied to environment fallback chain on lookups. Takes original environment chain as argument, returns new environment chain (in one of the forms acceptable as `env` parameter). Transformation functions can take more input arguments than the default described above, on demand. If transformation function is supplied directly, e.g. `pvaltf=somefunc`, it is sent default inputs. Extra inputs are requested by supplying instead a tuple, where the first element is the transformation function, and the following elements are predefined keywords of available extra inputs, e.g. `pvalf=(somefunc, "dkey", "pkrest")`. Available extra inputs by transformation function are: `dkeytf`: `"self"` the derivation object. `pkeytf`: `"self"`, `"dkey"` the derivation key (original or that returned by `dkeytf`), `"dkrest"` the second object returned by `dkeytf`. `pvaltf`: `"self"`, `"dkey"`, `"pkey"` the property key (original or that returned by `pkeytf`), `"env"` the tuple of environment chains, `"dkrest"`, `"pkrest"` the second object returned by `pkeytf`. `ksyntf`: `"self"`, `"dkey"`, `"dkrest"`. `envtf`: `"self"`, `"dkey"`, `"dkrest"`. Parameters: `env` (string, (string*), ((string*)*)) - environment for derivations `ckeysep` (string) - derivation-property key separator in compound keys `strictkey` - whether all key syntagmas must be unique to avoid conflicts `dkeytf` - transformation function for lookup derivation keys `dkeyitf` - transformation function for imported derivation keys `pkeytf` - transformation function for lookup property keys `pkeyitf` - transformation function for imported property keys `pvaltf` - transformation fucntion for property values `ksyntf` - transformation fucntion for key syntagamas Overrides: object.__init__

### import_string(self, string, ignhid=False) |
Import string with derivations. Parameters: `string` (string) - the string to parse `ignhid` (bool) - also make hidden derivations visible if `True` Returns: int number of newly imported visible derivations

### import_file(self, filename, ignhid=False) |
Import file with derivations. Parameters: `filename` (string) - the path to file to parse `ignhid` (bool) - also make hidden derivations visible if `True` Returns: int number of newly imported visible derivations

### get2(self, dkey, pkey, defval=None) |
Get property value by derivation key and property key. Parameters: `dkey` (string) - derivation key `pkey` (string) - property key `defval` (string) - the value to return if the property does not exist Returns: string the property value

### get(self, ckey, defval=None) |
Get property value by compound key. Parameters: `ckey` (string) - compound key `defval` (string) - the value to return if the property does not exist Returns: string the property value

### dkeys(self, single=False) |
Get list of all derivation keys. For derivations accessible through more than one derivation key, by default all of them are included in the result. If instead only a single random of those keys is wanted (i.e. strictly one key per derivation), `single` can be set to `True`. Parameters: `single` (param) - whether to return a single key for each derivation Returns: [string*] list of derivation keys

### syns(self, dkey) |
Get list of key syntagmas by derivation key. Key syntagmas are always returned in the order in which they appear in the derivation. If no derivation is found for the given key, an empty list is returned. Parameters: `dkey` (string) - derivation key Returns: [string*] key syntagmas

### altdkeys(self, dkey) |
Get list of all derivation keys pointing to same entry as given key. Parameters: `dkey` (string) - derivation key Returns: [string*] alternative derivation keys

### pkeys(self, dkey) |
Get set of property keys available for given derivation key. If no derivation is found for the given key, an empty set is returned. Parameters: `dkey` (string) - derivation key Returns: set(string*) property keys

### props(self, dkey) |
Get dictionary of property values by property keys for given derivation key. If no derivation is found for the given key, an empty dictionary is returned. Parameters: `dkey` (string) - derivation key Returns: {(string, string)*} property dictionary

### envs(self, dkey) |
Get list of all explicitly defined environments in given derivation. "Explicitly" means environments mentioned in the derivation itself, and not those inherited through expansions. Parameters: `dkey` (string) - derivation key Returns: [string*] explicit environment names

### source_name(self, dkey) |
Get the name of the source in which the derivation is found. If no derivation is found for the given key, `None` is returned. Parameters: `dkey` (string) - derivation key Returns: string name of the source

### source_pos(self, dkey) |
Get the position in the source where the derivation is found. Position is a 3-tuple of file path, line and column numbers. If no derivation is found for the given key, `None` is returned. Parameters: `dkey` (string) - derivation key Returns: (string, int, int) source position

### keys(self) |
Get the list of all compound keys. Returns: [string*] compound keys

### values(self) |
Get the list of all property values. Returns: [string*] property values

### items(self) |
Get the list of all pairs of compound keys and property values. Returns: [(string, string)*] compound keys and property values

### __contains__(self, ckey) (In operator) |
Check if the compound key is present in the derivator. Returns: bool `True` if present, `False` otherwie

### __getitem__(self, ckey) (Indexing operator) |
Get property value by compound key, in dictionary notation. Like get, but raises `KeyError` if key is not found. Returns: string property value

### __iter__(self) |
Iterate through all compound keys, in random order. Returns: iterator(string) iterator through compound keys

### iterkeys(self) |
Iterate through all compound keys, in random order. Returns: iterator(string) iterator through compound keys

### itervalues(self) |
Iterate through all property values, in random order. Returns: iteratorstring) iterator through property values

### iteritems(self) |
Iterate through all pairs of compound key and property value, in random order. Returns: iterator((string, string)) iterator through compound key property value pairs