Abstract Encyclopedias

Unindexed Encyclopedia

class encyclopedia.Unindexed(mapping=None, frozen=False)

Bases: collections.abc.MutableMapping

An Unindexed Encyclopedia extends a MutableMapping with the following features:

  • composition: Encyclopedia contents may be altered by functions or Encyclopedias
  • set operation: Encyclopedias may be combined using union, difference and intersection
  • mutability: ability to “freeze” and “melt” an object
__add__(other)

create union with this encyclopedia and another

__mul__(other)

compose encyclopedia with another object

__sub__(other)

perform set difference of this encyclopedia and other

copy()

perform a deep copy

freeze()

make encyclopedia immutable

melt()

make encyclopedia mutable

Indexed Encyclopedia

class encyclopedia.Indexed(mapping=None, frozen=False)

Bases: encyclopedia.templates.Unindexed

An Indexed Encyclopedia may be inverted such that its values map to their keys

__invert__()

invert the Encyclopedia

Signed Encyclopedia

class encyclopedia.Signed(mapping=None, frozen=False)

Bases: encyclopedia.templates.Indexed

A Signed Encyclopedia may contain negative elements, that is, elements which “cancel” similarly keyed elements

__abs__()

remove negative elements for this encyclopedia

__and__(other)

intersect using signed logic

__neg__()

negate this encyclopedia

Concrete Encyclopedias

Dictionary

class encyclopedia.Dictionary(mapping=None, frozen=False)

Bases: dict, encyclopedia.templates.Unindexed

A simple instantiation adding Encyclopedic features to the python dictionary

EAV

class encyclopedia.EAV(data=None, fmt: str = None, fields=('entity', 'attribute', 'value'), vcast=None, acast=<class 'str'>, ecast=<class 'str'>, defaults=None, vcasts=None)

Bases: dict, encyclopedia.templates.Unindexed

Container for storing smallish EAV “triples” (Entity-Attribute-Value). - intent of class is to provide dictionary-like access rather than data analysis functionality - internally, EAV is stored as a dictionary (key:E) of dictionaries (key:A,value:V) - class supports encyclopedic operations e.g. subtraction (difference) and addition (union)

set-ting:

eav[entity, attribute] = value eav[[entity1, …], attribute] = value eav[[entity1, …], attribute] = [value1, …] # len(entities) must equal len(values) eav[:, attribute] = value # assign all entities same value for attribute

get-ting:

eav[entity, attribute] # value for a specific attribute eav[entity] # dictionary of elements referenced by entity

get-ting producing new EAV:

eav[:, attribute] # new EAV with all entities and but only one attribute eav[:, [attribute1, attribute2]] # new EAV with all entities and but only specified attributes eav[entity,:] # new EAV with only one entity eav[[entity1, …],:] # new EAV with only specified entities

Unsupported at this time:

eav[entity, :] = value # ERROR eav[entity, [attribute1, …]] = [value1, …] # ERROR
__delitem__(thing)

Delete self[key].

__getitem__(thing)

x.__getitem__(y) <==> x[y]

__init__(data=None, fmt: str = None, fields=('entity', 'attribute', 'value'), vcast=None, acast=<class 'str'>, ecast=<class 'str'>, defaults=None, vcasts=None)
  • fmt (type may be specified using one of the following strings …)
    • dict: dictionary of dictionaries (auto-detected)
    • triple: list of EAV dictionaries/tuples (defaulted)
    • column: list of records with field names as first row and entities on first column (must force this option)
  • vcast: value cast e.g. int
  • acast: attribute cast e.g. str
  • ecast: entity cast e.g. str
  • defaults: dictionary of defaults for specific attributes
  • vcasts: dictionary of casting for specific attributes
__setitem__(thing, value)

Set self[key] to value.

__str__()

Return str(self).

__weakref__

list of weak references to the object (if defined)

attributes(entities=None)

computationally determine which attributes are used for specified entities

compose(other, entities=None)

perform functional or Encyclopedic composition

copy()

deep copy of EAV. Preserves casting and defaults.

copy_style()

create empty EAV preserving casting and defaults.

rename(renames, entities=None)

rename attributes (… not the entities)

subtract(other)

perform set difference

Record

class encyclopedia.Record(mapping=None, autopopulate=False, restrict=True)

Bases: dict, encyclopedia.templates.Unindexed

A factory creating Encyclopedia-ified Dictionaries with:

  • restricted keys
  • automatic type conversions
  • optional defaults
instance()

create an individual (Record) instance

Relation

class encyclopedia.Relation(init=None, cardinality='M:M', ordered=False, frozen=False)

Bases: encyclopedia.templates.Indexed

General purpose, discrete relation container for all four mapping cardinalities:

  • 1:1 (Isomorphism)
  • 1:M (Immersion)
  • M:1 (Function e.g. Python Dictionary)
  • M:M (General Relation)

Inversion, for all cardinalities, is provided (at the cost of doubled storage)

exception Error

Bases: encyclopedia.templates.Error

label Relation exceptions

__init__(init=None, cardinality='M:M', ordered=False, frozen=False)

create a new Relation using a variety of different inputs

__invert__()

reverse the domain and range

Note: Relation inversion uses references instead of copies

__len__()

number of keys (domain)

__setitem__(domain, target)
  • add key-value pairs for 1:M and M:M cardinalities
  • overwrite key values for 1:1 and M:1 cardinalities
__str__()

display the forward and inverted mappings

compose(other)

compose relation with another relation or a function

subtract(other)

implement set difference

unfrozen()

function decorator to check if object is unfrozen

update(other)

update a Relation with another Relation

values()

the range of the mapping

Forest

class encyclopedia.Forest(offset: int = 0, parent=None)

Bases: encyclopedia.templates.Unindexed

An Encyclopedia of trees <https://en.wikipedia.org/wiki/Tree_(graph_theory)>. There is no specific “Tree” class; instead, a Tree is Forest with a single, connected graph. This is purposeful, as adding two Trees creates a Forest, not another Tree.

Terminology for the Forest class:

  • Tree: single, connected (tree) graph
  • Forest: a (possibly empty) collection of Trees, supporting encyclopedic operations
  • Node: a single node in a graph
  • Twig: a connected pair of nodes
  • Sprout: a new, connected node
class Node(alias, id)

Bases: object

store the non-unique alias and the unique ID for a Node

identified(identified: bool, off: int = 0)

return either an offset Node ID or simply the alias

above(alias, aliased=False)

generate nodes above aliased node(s)

aliased(alias=None)

generate set of nodes referenced by an alias

below(alias, aliased=False)

generate parent below aliased node(ss)

branches(alias)

return branches (e.g. Trees) above the aliased node(s)

climb(alias=None, level: bool = False, twig: bool = False, identified: bool = True, offset: int = 0)

generate tree of nodes reacheable from alias

compose(other)

composition depends on context of “other”:

  • scaled by integers
  • acted upon by functions
  • grafted with Forests
cutting(alias=None, identified: bool = True, offset: int = 0, morph: function = <function Unindexed.identity>)

subforest rooted at alias

graft(forest, alias=None, identified: bool = True)

glue forest onto another forest at aliased node(s)

height()

the maximum height of all nodes in Forest (in all trees)

leaves(alias=None)

leaves reachable from alias

limb(alias, offset: int = 0)

the tree (single line of nodes) below aliased node(s)

prune()

eliminate duplicate trees in a forest

root(alias=None)

tree root of aliased node(s)

sorted(alias=None, level: bool = False, twig: bool = False, offset: int = 0, identified: bool = True, aliased: bool = False)

topologically sorted node list (not iterator)

sprout(alias)

make a unique node identifier (referenced by an alias)

subtract(other)

perform set difference when “other” is a Forest; otherwise, delete element

Note: Encyclopedia mixin

unfrozen()

function decorator to check if object is unfrozen

update(other)

perform set union when “other” is a Forest; otherwise, add a new tree

Note: MutableMapping mixin

values()

implicit by __getitem__ (mixin) but implemented for performance reasons

Arboretum

class encyclopedia.Arboretum(offset: int = 0, parent=None)

Bases: encyclopedia.forest.Forest

A Forest with inhertiable attributes. Note: as attributes are assigned using setitem syntax, tuples cannot be used as node aliases

XML

class encyclopedia.XML

Forest syntax combined with an elementTree XML implementation. To avoid internal confusion, inherits from neither elementTree nor Arboretum directly, thus the tree(forest) is stored in parallel to the elementTree structure

copy()

perform a deep copy

unique(name)

create a unique element name

write(filename=None, doctype=None)

write the XML, adding tabs for pretty-printing

KML

class encyclopedia.KML

An encyclopedia-ified version of the KML (Keyhole Markup Language) GIS format. In addtion to encyclopedia operations, KML supports the following features:

  • a draw function for ease in creating a KML geometries
  • records for managing KML styles and coordinates
Coordinate

alias of encyclopedia.record.Record.instance.<locals>.Internal

Style

alias of encyclopedia.record.Record.instance.<locals>.Internal

static coordinated(record, show_description=None, show_data=None, altitude_in_feet=True)

create a KML coordinate

draw(points, folder, style, geometry='LineString', extrude=False, visibility=True, tesselate=None, altitude='absolute')

create a KML geometry in a specified folder using:

  • collection of KML drawing parameters
  • set of points

points are provided as an iterated list of dictionaries with (at least) the following fields:

  • uid (Unique Identifier)
  • id (KML element label)
  • lat
  • lon
  • alt (in feet)
  • tick (UNIX time)

Points will be plotted in the order they are occur in the stream Meta data (e.g. id) will only be taken from the first point in the stream

if begin/end appears as fields:

  • begin (UNIX time)
  • end (UNIX time)

will create a time block. As with meta data, only the data on the first uid appearance is used

static styled(record)

create a KML style

stylize(record)

create a KML style element

write(filename=None, doctype=None, mlns='http://www.opengis.net/kml/2.2', gxmlns='http://www.google.com/kml/ext/2.2')

write KML to a file