buildingmotif.dataclasses.template

buildingmotif.dataclasses.template#

Classes

`Dependency`(_template_id, args)
`Template`(_id, _name, body, optional_args, _bm)	This class mirrors :py:class`database.tables.DBTemplate`.

class Template(_id: int, _name: str, body: Graph, optional_args: List[str], _bm: BuildingMOTIF)[source]#

This class mirrors :py:class`database.tables.DBTemplate`.

body: Graph#

optional_args: List[str]#

classmethod load(id: int) → Template[source]#

Load template from database.

Parameters:: id (int) – id of template
Returns:: loaded template
Return type:: Template

in_memory_copy() → Template[source]#

Copy this template.

Returns:: copy of this template
Return type:: Template

property id#

property name#

get_dependencies() → Tuple[Dependency, ...][source]#

Get the template’s dependencies.

Returns:: a tuple of dependencies
Return type:: Tuple

add_dependency(dependency: Template, args: Dict[str, str]) → None[source]#

Add dependency to template.

Parameters:

dependency (Template) – dependency to add
args (Dict[str, str]) – dictionary of dependency arguments

check_dependencies()[source]#

Verifies that all dependencies have valid references to the parameters in the dependency or (recursively) its dependencies. Raises an exception if any issues are found.

It is recommended to call this after all templates in a library have been loaded in to the DB, else this might falsely raise an error.

remove_dependency(dependency: Template) → None[source]#

Remove dependency from template.

Parameters:: dependency (Template) – dependency to remove

property all_parameters: Set[str]#

The set of all parameters used in this template including its dependencies. Includes optional parameters.

Returns:: set of parameters with dependencies
Return type:: Set[str]

property parameters: Set[str]#

The set of all parameters used in this template excluding its dependencies. Includes optional parameters.

Returns:: set of parameters without dependencies
Return type:: Set[str]

property dependency_parameters: Set[str]#

The set of all parameters used in this template’s dependencies, including optional parameters.

Returns:: set of parameters used in dependencies
Return type:: Set[str]

property parameter_counts: Counter#

An addressable histogram of the parameter name counts in this template and all of its transitive dependencies.

Returns:: count of parameters
Return type:: Counter

dependency_for_parameter(param: str) → Optional[Template][source]#

Returns the dependency that uses the given parameter if one exists.

Parameters:: param (str) – parameter to search for
Returns:: dependency that uses the given parameter
Return type:: Optional[Template]

to_inline(preserve_args: Optional[List[str]] = None) → Template[source]#

Return an inline-able copy of this template.

Suffixes all parameters with a unique identifier that will avoid parameter name collisions when templates are combined with one another. Any argument names in the preserve_args list will not be adjusted.

Parameters:: preserve_args (Optional[List[str]], optional) – parameters whose names will be preserved, defaults to None
Returns:: a template with globally unique parameters
Return type:: Template

property transitive_parameters: Set[str]#

Get all parameters used in this template and its dependencies.

Returns:: set of all parameters
Return type:: Set[str]

inline_dependencies() → Template[source]#

Copies this template with all dependencies recursively inlined.

Parameters of dependencies will be renamed to avoid confusion.

Returns:: copy of this template with all dependencies inlined
Return type:: Template

evaluate(bindings: Dict[str, Node], namespaces: Optional[Dict[str, Namespace]] = None, require_optional_args: bool = False, warn_unused: bool = True) → Union[Template, Graph][source]#

Evaluate the template with the provided bindings.

If all parameters in the template have a provided binding, then a graph will be returned. Otherwise, a new Template will be returned that incorporates the provided bindings and preserves unbound parameters. If require_optional_args is True, then the template evaluation will not return a graph unless all optional arguments are bound. If require_optional_args is False, then the template evaluation will return a graph even if some optional arguments are unbound.

Parameters:

bindings (Dict[str, Node]) – map of parameter {name: RDF term} to substitute
namespaces (Optional[Dict[str, rdflib.Namespace]], optional) – namespace bindings to add to the graph, defaults to None
require_optional_args (bool) – whether to require all optional arguments to be bound, defaults to False
warn_unused (bool) – if True, print a warning if there were any parameters left unbound during evaluation. If ‘require_optional_args’ is True, then this will consider optional parameters when producing the warning; otherwise, optional paramters will be ignored; defaults to True

Returns:

either a template or a graph, depending on whether all parameters were provided

Return type:

Union[Template, rdflib.Graph]

fill(ns: Namespace, include_optional: bool = False) → Tuple[Dict[str, Node], Graph][source]#

Evaluates the template with autogenerated bindings within the given namespace.

Parameters:

ns (rdflib.Namespace) – namespace to contain the autogenerated entities
include_optional (bool) – if True, invent URIs for optional parameters; ignore if False

Returns:

a tuple of the bindings used and the resulting graph

Return type:

Tuple[Dict[str, Node], rdflib.Graph]

property defining_library: Library#

The library defining this template.

Returns:: library
Return type:: Library

library_dependencies() → List[Library][source]#

Get library dependencies for this template.

Returns:: list of libraries
Return type:: List[Library]

find_subgraphs(model: Model, *ontologies: Graph) → Generator[Tuple[Dict[Node, Node], Graph, Optional[Template]], None, None][source]#

Produces an iterable of subgraphs in the model that are partially or entirely covered by the provided template.

Yield:: iterable of subgraphs in the model
Return type:: Generator[Tuple[Mapping, rdflib.Graph, Optional[Template]], None, None]

generate_csv(path: Optional[PathLike] = None) → Optional[StringIO][source]#

Generate a CSV for this template which contains a column for each template parameter. Once filled out, the resulting CSV file can be passed to a Template Ingress to populate a model. Returns a ‘io.BytesIO’ object which can be written to a file or sent to another program/function.

Parameters:: path (PathLike, optional) – if not None, writes the CSV to the indicated file
Returns:: String buffer containing the resulting CSV file
Return type:: StringIO

generate_spreadsheet(path: Optional[PathLike] = None) → Optional[BytesIO][source]#

Generate a spreadsheet for this template which contains a column for each template parameter. Once filled out, the resulting spreadsheet can be passed to a Template Ingress to populate a model. Returns a ‘io.BytesIO’ object which can be written to a file or sent to another program/function.

Parameters:: path (PathLike, optional) – if not None, writes the CSV to the indicated file
Returns:: Byte buffer containing the resulting spreadsheet file
Return type:: BytesIO

class Dependency(_template_id: int, args: Dict[str, str])[source]#

args: Dict[str, str]#

property template_id#

property template: Template#