Changes between Version 5 and Version 6 of S3/S3Hierarchy

05/21/14 21:26:31 (8 years ago)
Dominic König



  • S3/S3Hierarchy

    v5 v6  
    57 == Connecting to the Hierarchy ==
    59   - ''tbw''
     57== Subset Definition ==
     59To perform lookups in the hierarchy, you need to define a subset, which is an S3Hierarchy instance.
     61With the tablename as only parameter, the subset would include all records in the hierarchical table (...which are accessible for the user):
     64subset = S3Hierarchy("hierarchical_type_table")
     67To filter the records, a filter query can be specified as keyword parameter:
     70query = (FS("filter_field") == 5)
     71subset = S3Hierarchy("hierarchical_type_table, filter=query)
     74== Performing Lookups ==
     76All lookup attributes or methods of the subset use node IDs.
     78The node IDs are either the record IDs (for simple self-reference) or the super-IDs (for super-entity self-reference) of the records in the subset.
     80All lookup attributes and methods return either a single node ID (long), or a '''set''' of node IDs. The only exception is path() which returns an ordered list of node IDs.
     82=== Root Nodes ===
     84To get all root nodes of the subset, use:
     87# Returns a set of node IDs
     88root_nodes = subset.roots
     91To get the root node for a particular node, use:
     94# Returns the root node ID for node_id (or node_id if it is a root node itself)
     95root = subset.root(node_id)
     98=== Child Nodes ===
     100To get all child nodes of a node, use:
     103# Returns the first generation of child nodes for node_id
     104children = subset.children(node_id)
     107To get all descendants of a node, use:
     110# Returns all descendant nodes (any generation) for node_id
     111children = subset.findall(node_id)
     114It is possible to use findall to get a union set of descendants for multiple parent nodes:
     116# Returns all descendants in all specified nodes
     117children = subset.findall((node_id_1, node_id_2, node_id_3))
     120=== Parent Nodes ===
     122To get the parent node ID for a node, use:
     125# Returns the parent node ID for node_id (or None if node_id is a root node)
     126parent = subset.parent(node_id)
     129=== Sibling Nodes ===
     131To get all sibling node IDs for a node, use:
     134# Returns all sibling node IDs for node_id
     135siblings = subset.siblings(node_id)
     138This does not normally return node_id itself, unless you specify inclusive=True:
     141# Returns all sibling node IDs for node_id - including node_id itself
     142siblings = subset.siblings(node_id, inclusive=True)
     145=== Path ===
     147The path of a node is an ordered list of all generations of parent node IDs from the root node down to the node itself. It can be requested by:
     150# Returns the path of a node (root node first) as ordered list
     151path = subset.path(node_id)
     154== Using categories ==
     156Categories can be used to classify nodes "horizontally", e.g. to indicate a hierarchy "level". To use them with the hierarchy toolkit, an additional category-field must be defined in the hierarchy configuration:
     159    self.configure(tablename, hierarchy=(parent_field, category_field))
     162Categories are neither managed nor inferred by the hierarchy toolkit, but they can be used to filter the lookup axis.
     164=== Filtering the Lookup Axis ===
     166This is useful e.g. to find all descendants of a node of a specific category:
     169# Define a hierarchy of locations with "parent" as parent-reference and "level" as category
     170subset = S3Hierarchy("gis_location", hierarchy=("parent", "level"))
     172# Lookup all descendants of location #3 with category "L3"
     173communes = subset.findall(3, category="L3", inclusive=True)
     176When performing a root lookup, we may be interested in the closest parent of a particular category rather than the absolute root:
     179# Lookup the closest "L1" parent of location #454
     180state = subset.root(454, category="L1")
     183This does also work with path lookups:
     186# Lookup the path of location #378 down from the closest "L1" parent
     187path = subset.path(378, category="L1")
     190The category parameter can be used analogously with the children() and siblings() methods.
     192=== Looking up the Category of a Node ===
     194To lookup the category of a node, use:
     197# Returns the category for node_id (e.g. "L1")
     198category = subset.category(node_id)
     201To get the category of each node in the result of the parent(), root(), path(), children(), findall(), or siblings() methods, use the classify-flag like:
     204# Returns the children of location #328 as set of tuples like: set([(367, "L3"), (368, "L3")])
     205children = subset.children(328, classify=True)