turbograph.core subpackage

turbograph.core subpackage#

Core module for TurboGraph.

This package provides the fundamental abstractions, types, and utilities for constructing and manipulating dependency graphs.

turbograph.core.constant module#

Define core types and constants used in the Turbograph library.

class turbograph.core.constant.NACLS[source]#

Bases: object

Sentinel value representing a missing vertex value.

This singleton is used to distinguish between explicitly set None values and missing values. It helps differentiate uninitialized vertex attributes from those intentionally assigned None.

turbograph.core.constant.NA: NACLS = <NA>#

A sentinel value representing a missing vertex ‘value’.

This singleton is used to indicate that a vertex does not yet have a computed or assigned value. It prevents ambiguity when None is a valid assigned value.

class turbograph.core.constant.V#

Generic vertex type.

Vertices in a dependency graph must be hashable, as they are used as keys in internal mappings such as dictionaries for storing attributes.

alias of TypeVar(‘V’, bound=Hashable)

turbograph.core.constant.VertexFunc#

Type alias for a vertex’s computation function.

A vertex function determines how a vertex’s value is computed from its predecessors. If None, no function is assigned to the vertex.

alias of Callable[[…], Any] | None

turbograph.core.constant.VertexPredecessors#

Type alias for the predecessors of a vertex.

Predecessors are the vertices that provide input values for a given vertex’s computation.

alias of Sequence[V]

turbograph.core.constant.VertexValue#

Type alias for the value of a vertex.

A vertex value can be: - Any computed or assigned value. - The sentinel NA, indicating that the value is missing.

alias of Any | NACLS

turbograph.core.exception module#

Define custom exceptions used in the Turbograph library.

exception turbograph.core.exception.NotFoundError(element_name, element, valid_elements, elements_name=None)[source]#

Bases: Exception

Error raised when an element is not found in a collection.

Parameters:

element_name (str)
element (object)
valid_elements (Iterable[object])
elements_name (str | None)

Return type:

None

element#: The element that was not found.

valid_elements#: The valid elements that could have been found.

turbograph.core.funccall module#

Define and handle function call modes.

A module that defines call modes and utility functions for invoking functions with different input-passing strategies. Call modes determine how input values are passed to a function:

"args": Positional arguments (e.g., func(a, b, c)).
"kwargs": Keyword arguments (e.g., func(a=a, b=b, c=c)).
"arg": A single dictionary argument (e.g., func({"a": a, "b": b, "c": c})).

turbograph.core.funccall.CallMode#

Enumeration of valid call modes for function execution.

alias of Literal[‘args’, ‘kwargs’, ‘arg’]

turbograph.core.funccall.CALL_MODES: set[Literal['args', 'kwargs', 'arg']] = {'arg', 'args', 'kwargs'}#: Tuple of valid function call modes.

turbograph.core.funccall.DEFAULT_CALL_MODE: Literal['args'] = 'args'#: The default function call mode.

class turbograph.core.funccall.Out#

Generic output type for function return values.

alias of TypeVar(‘Out’)

exception turbograph.core.funccall.CallModeError(call_mode)[source]#

Bases: Exception

An error raised when an invalid call mode is provided.

Parameters:: call_mode (object)
Return type:: None

turbograph.core.funccall.call_func(func, inputs, call_mode='args')[source]#

Invoke a function with dynamically passed inputs based on a call mode.

Return type:

TypeVar(Out)

Parameters:

func (Callable[[...], Out]) – The function to invoke.
inputs (dict[Any, Any]) – A dictionary mapping input names to their values.
call_mode (Literal['args', 'kwargs', 'arg']) –
The input passing strategy.
- ”args” (default): Pass input values as positional arguments.
- ”kwargs”: Pass input values as keyword arguments.
- ”arg”: Pass all inputs as a single dictionary argument.

Returns:

The output of the function.

Raises:

ValueError – If an invalid call mode is provided.

Example

Using different call modes with the same function:

>>> def example_func(a, b, c):
...     return a + b + c
>>> inputs = {"a": 1, "b": 2, "c": 3}

Call with positional arguments: >>> call_func(example_func, inputs, call_mode=”args”) 6

Call with keyword arguments: >>> call_func(example_func, inputs, call_mode=”kwargs”) 6

Call with a single dictionary argument: >>> def dict_func(data): … return sum(data.values()) >>> call_func(dict_func, inputs, call_mode=”arg”) 6

turbograph.core.specification module#

Define vertex specifications used to construct a dependency graph.

class turbograph.core.specification.VertexSpecification(func=None, predecessors=(), value=<NA>)[source]#

Bases: Generic[V]

Defines the specification for a vertex in a dependency graph.

Parameters:

func (Callable[[...], Any] | None)
predecessors (Sequence[V])
value (Any | NACLS)

func: Optional[Callable[..., Any]] = None#

An optional function to compute the vertex value.

If None, the vertex does not have an associated computation function.

predecessors: Sequence[TypeVar(V, bound= Hashable)] = ()#: A sequence of predecessor vertices providing inputs for computation.

value: Union[Any, NACLS] = <NA>#

The value of the vertex.

The sentinel NA is used to indicate that the value is missing or uncomputed.

classmethod from_mapping(value)[source]#

Create a vertex specification from a mapping.

Return type:

VertexSpecification[TypeVar(V, bound= Hashable)]

Parameters:

value (Mapping[str, Any]) – A mapping containing the "func", "predecessors",
keys. (and "value")

Returns:

A VertexSpecification instance.

classmethod from_sequence(value)[source]#

Create a vertex specification from a sequence.

The sequence should follow the order: (func, predecessors, value).

Return type:: VertexSpecification[TypeVar(V, bound= Hashable)]
Parameters:: value (Sequence[Any]) – A sequence containing function, predecessors, and value.
Returns:: A VertexSpecification instance.

classmethod from_func(func, *, kinds=())[source]#

Create a vertex specification from a function.

The function’s parameter names are used as its predecessor vertices.

Return type:

VertexSpecification[TypeVar(V, bound= Hashable)]

Parameters:

func (Callable[[...], Any]) – The function defining the vertex computation.
kinds (Iterable[_ParameterKind]) – The types of parameters to consider as predecessors.

Returns:

A VertexSpecification with inferred predecessors.

classmethod from_value(value)[source]#

Create a vertex specification from a raw value.

Return type:: VertexSpecification[TypeVar(V, bound= Hashable)]
Parameters:: value (object) – A precomputed value.
Returns:: A VertexSpecification with the value set.

classmethod from_any(value, *, kinds=())[source]#

Create a vertex specification from a raw input of any supported type.

Return type:

VertexSpecification[TypeVar(V, bound= Hashable)]

Parameters:

value (VertexSpecification[Any] | Mapping[str, Any] | Sequence[Any] | Callable[[...], Any] | Any) – The raw input, which can be a dictionary, sequence, function, or value.
kinds (Iterable[_ParameterKind]) – The types of parameters to consider when inferring predecessors.

Returns:

A VertexSpecification instance.

to_dict()[source]#

Convert the vertex specification into a dictionary of vertex attributes.

Return type:: VertexAttributes[TypeVar(V, bound= Hashable)]
Returns:: A dictionary containing the "func", "predecessors", and "value" keys.

turbograph.core.specification.RawVertexSpecification#

A raw vertex specification that can be converted into a VertexSpecification.

It can be one of the following types:

A VertexSpecification (already structured).
A mapping (dictionary), processed with VertexSpecification.from_mapping().
A sequence (list, tuple), processed with VertexSpecification.from_sequence().
A callable function, processed with VertexSpecification.from_func().
Any other value, processed with VertexSpecification.from_value().

alias of VertexSpecification[V] | Mapping[str, Any] | Sequence[Any] | Callable[[…], Any] | Any

turbograph.core.attribute module#

Define the attributes associated with vertices in a dependency graph.

class turbograph.core.attribute.VertexAttributes[source]#

Bases: TypedDict, Generic[V]

Attributes associated with a vertex in the dependency graph.

func: Callable[..., Any] | None#

An optional function that computes the vertex value.

If None, the vertex must have a predefined value at the computation stage.

value: VertexValue#

The value of the vertex.

If the vertex has been computed or assigned a value, it is stored here.
If the value is missing, the sentinel turbograph.NA is used.

predecessors: VertexPredecessors[V]#

A sequence of predecessor vertices.

Predecessors are the input vertices whose values are used to compute the current vertex’s value. The order of predecessors matters for positional argument-based function calls.

turbograph.core.attribute.VertexAttributeName#

Enumeration of valid attribute names for a vertex.

alias of Literal[‘func’, ‘value’, ‘predecessors’]

turbograph.core.graphwrapper module#

Define the graph wrapper base class.

This module defines the abstract base class GraphWrapper and related exceptions for managing and manipulating graph structures.

The GraphWrapper class provides a common interface for graph operations used in the TurboGraph library. It allows defining various backends for different graph libraries, implemented in the turbograph.backend package.

class turbograph.core.graphwrapper.G#

Type representing a graph (e.g., a networkx graph).

alias of TypeVar(‘G’)

exception turbograph.core.graphwrapper.VertexError(vertex, valid_vertices)[source]#

Bases: NotFoundError

Exception raised for a missing vertex.

Parameters:

vertex (object)
valid_vertices (Iterable[object])

Return type:

None

exception turbograph.core.graphwrapper.EdgeError(edge, valid_edges)[source]#

Bases: NotFoundError

Exception raised for a missing edge.

Parameters:

edge (object)
valid_edges (Iterable[object])

Return type:

None

turbograph.core.graphwrapper.EdgeDirection#

Represents the direction of an edge in the graph.

alias of Literal[‘in’, ‘out’, ‘all’]

turbograph.core.graphwrapper.EDGE_DIRECTIONS: tuple[Literal['in', 'out', 'all'], ...] = ('in', 'out', 'all')#: Tuple of all possible edge directions in the graph.

turbograph.core.graphwrapper.DEFAULT_EDGE_DIRECTION: Literal['all'] = 'all'#: Default edge direction used in graph wrapper methods.

exception turbograph.core.graphwrapper.EdgeDirectionError(direction, valid_directions=None)[source]#

Bases: NotFoundError

Exception raised for an invalid edge direction.

Parameters:

direction (object)
valid_directions (Iterable[str] | None)

Return type:

None

class turbograph.core.graphwrapper.GraphWrapper(graph=None)[source]#

Bases: ABC, Generic[G, V]

Abstract base class for graph operations in TurboGraph.

This class defines the essential methods for interacting with graph data structures, used to construct and manipulate dependency graphs in TurboGraph.

Parameters:: graph (G | None)

graph#: The actual graph instance.

abstract classmethod initialize_empty()[source]#

Initialize and return an empty graph.

Return type:: TypeVar(G)

abstract get_graph_copy()[source]#

Return a copy of the internal graph.

Return type:: TypeVar(G)

abstract add_vertex(vertex, **attributes)[source]#

Add a vertex with specified attributes to the graph.

Return type:

None

Parameters:

vertex (V) – The vertex to add.
**attributes (Unpack[VertexAttributes[V]]) – Keyword arguments representing the vertex attributes.

abstract add_edge(source, target)[source]#

Add an edge between the source and target vertices.

Return type:

None

Parameters:

source (V) – The source vertex.
target (V) – The target vertex.

abstract delete_vertex(*vertices)[source]#

Delete specified vertices from the graph.

Return type:: None
Parameters:: *vertices (V) – The vertices to delete.
Raises:: VertexError – If a vertex is not found in the graph.

abstract delete_edge(source, target)[source]#

Delete an edge between the source and target vertices.

Return type:

None

Parameters:

source (V) – The source vertex.
target (V) – The target vertex.

Raises:

EdgeError – If the edge is not found in the graph.

abstract get_vertex_attribute(vertex, key)[source]#

Get the value of a specific attribute of a vertex.

Return type:

object

Parameters:

vertex (V) – The vertex whose attribute is to be retrieved.
key (Literal['func', 'value', 'predecessors']) – The attribute key.

Raises:

VertexError – If the vertex is not found in the graph.

abstract get_vertex_attributes(vertex)[source]#

Get all attributes of a vertex.

Return type:: VertexAttributes[TypeVar(V, bound= Hashable)]
Parameters:: vertex (V) – The vertex whose attributes are to be retrieved.
Raises:: VertexError – If the vertex is not found in the graph.

abstract set_vertex_attribute(vertex, key, value)[source]#

Set the value of a specific attribute of a vertex.

Return type:

None

Parameters:

vertex (V) – The vertex whose attribute is to be set.
key (Literal['func', 'value', 'predecessors']) – The attribute key.
value (object) – The value to set.

Raises:

VertexError – If the vertex is not found in the graph.

abstract update_vertex_attributes(vertex, attributes)[source]#

Update multiple attributes of a vertex.

Return type:

None

Parameters:

vertex (V) – The vertex whose attributes are to be updated.
attributes (Mapping[Literal['func', 'value', 'predecessors'], ~typing.Any]) – A mapping of attribute keys to values.

Raises:

VertexError – If the vertex is not found in the graph.

abstract get_neighbors(vertex, direction='all')[source]#

Get the neighbors of a vertex in the specified direction.

Return type:

Iterable[TypeVar(V, bound= Hashable)]

Parameters:

vertex (V) – The vertex whose neighbors are to be retrieved.
direction (Literal['in', 'out', 'all']) – The direction of the edges to consider.

Raises:

VertexError – If the vertex is not found in the graph.

abstract get_degree(vertex, direction='all')[source]#

Get the degree of a vertex in the specified direction.

Return type:

int

Parameters:

vertex (V) – The vertex whose degree is to be retrieved.
direction (Literal['in', 'out', 'all']) – The direction of the edges to consider.

Raises:

VertexError – If the vertex is not found in the graph.

abstract get_subcomponent(vertex, direction='all')[source]#

Get the subcomponent of a vertex in the specified direction.

Return type:

Iterable[TypeVar(V, bound= Hashable)]

Parameters:

vertex (V) – The vertex whose subcomponent is to be retrieved.
direction (Literal['in', 'out', 'all']) – The direction of the edges to consider

Raises:

VertexError – If the vertex is not found in the graph.

abstract property call_mode: Literal['args', 'kwargs', 'arg'] | None#: Return the current call mode of the graph.

abstract is_dag()[source]#

Check if the graph is a directed acyclic graph (DAG).

Return type:: bool

abstract get_sorted_vertices(direction)[source]#

Get the vertices sorted topologically in the specified direction.

Return type:: Iterable[TypeVar(V, bound= Hashable)]
Parameters:: direction (Literal['in', 'out']) – The direction of the edges to consider.

property vertices: set[V]#: Return a set of all vertices in the graph.

property edges: set[tuple[V, V]]#: Return a set of all edges in the graph.

has_vertex(vertex)[source]#

Check if the vertex exists in the graph.

Return type:: bool
Parameters:: vertex (V) – The vertex to check.

has_edge(source, target)[source]#

Check if the edge exists in the graph.

Return type:

bool

Parameters:

source (V) – The source vertex of the edge.
target (V) – The target vertex of the edge.

get_vertices_with_known_value()[source]#

Return vertices that have a known value (i.e., not NA).

Return type:: set[TypeVar(V, bound= Hashable)]

set_attribute_to_vertices(key, vertex_to_value)[source]#

Set a specific attribute for multiple vertices.

Return type:

None

Parameters:

key (Literal['func', 'value', 'predecessors']) – The attribute key.
vertex_to_value (Mapping[V, Any]) – A mapping of vertices to values.

Raises:

KeyError – If a vertex is not found in the graph.

get_all_vertex_attributes()[source]#

Return a dictionary of all vertex attributes.

Return type:: dict[TypeVar(V, bound= Hashable), VertexAttributes[TypeVar(V, bound= Hashable)]]

copy()[source]#

Return a copy of the graph wrapper, including the graph instance.

Return type:: Self

subgraph(vertices)[source]#

Create and return a subgraph containing the specified vertices.

Return type:: Self
Parameters:: vertices (Iterable[V]) – The vertices to include in the subgraph.

reset()[source]#

Reset the graph while preserving its structure.

This method clears the stored functions and values from all vertices while preserving the graph’s structure and dependencies.

Return type:: None

rebuild(vertices=None, values=None, funcs=None, *, reduce=False, call_mode=None)[source]#

Alias for turbograph.rebuild_graph().

This method is a direct alias for turbograph.rebuild_graph(), forwarding all arguments to it. Refer to its documentation for usage details.

Return type:

Self

Parameters:

vertices (Iterable[V] | None)
values (Mapping[V, Any | NACLS] | None)
funcs (Mapping[V, Callable[[...], Any] | None] | None)
reduce (bool)
call_mode (Literal['args', 'kwargs', 'arg'] | None)

compute(vertices=None, values=None, funcs=None, *, call_mode=None, auto_prune=True)[source]#

Alias for turbograph.compute_from_graph().

This method is a direct alias for turbograph.compute_from_graph(), forwarding all arguments to it. Refer to its documentation for usage details.

Return type:

dict[TypeVar(V, bound= Hashable), Any]

Parameters:

vertices (Iterable[V] | None)
values (Mapping[V, Any | NACLS] | None)
funcs (Mapping[V, Callable[[...], Any] | None] | None)
call_mode (Literal['args', 'kwargs', 'arg'] | None)
auto_prune (bool)

class turbograph.core.graphwrapper.GW#

Type of the graph wrapper.

alias of TypeVar(‘GW’, bound=GraphWrapper[Any, Any])

turbograph.core.adapter module#

Format raw vertex specifications into VertexSpecification objects.

It provides utilities to:

Convert raw vertex specifications into structured VertexSpecification objects.
Map function call modes to their corresponding parameter kinds.

turbograph.core.adapter.CALL_MODE_TO_PARAMETER_KINDS: dict[CallMode, Iterable[_ParameterKind]] = {'arg': {}, 'args': {_ParameterKind.POSITIONAL_ONLY, _ParameterKind.POSITIONAL_OR_KEYWORD}, 'kwargs': {_ParameterKind.POSITIONAL_OR_KEYWORD, _ParameterKind.KEYWORD_ONLY}}#

Mapping of function call modes to the corresponding parameter kinds.

This dictionary defines which function parameter kinds are used for each call mode:

"args": Includes positional-only and positional-or-keyword arguments.
"kwargs": Includes positional-or-keyword and keyword-only arguments.
"arg": Does not consider any specific argument types.

turbograph.core.adapter.get_parameter_kinds(call_mode)[source]#

Retrieve the parameter kinds with proper error handling.

Retrieve the parameter kinds associated with a given function call mode, with proper error handling. The parameter kinds are defined in the CALL_MODE_TO_PARAMETER_KINDS dictionary.

Return type:: Iterable[_ParameterKind]
Parameters:: call_mode (CallMode)

turbograph.core.adapter.format_specifications(raw_specifications, call_mode)[source]#

Convert raw vertex specifications into VertexSpecification objects.

This functions formats raw vertex specifications into structured VertexSpecification objects, based on the provided call mode. This function ensures that the correct parameter kinds are considered when formatting vertex specifications, based on the provided call mode.

Return type:

dict[TypeVar(V, bound= Hashable), VertexSpecification[TypeVar(V, bound= Hashable)]]

Parameters:

raw_specifications (Mapping[V, VertexSpecification[V] | Mapping[str, Any] | Sequence[Any] | Callable[[...], Any] | Any]) – A mapping of vertex identifiers to raw vertex specifications.
call_mode (Literal['args', 'kwargs', 'arg']) – The function call mode which determines how function arguments are interpreted.

Returns:

A dictionary mapping vertex identifiers to VertexSpecification objects.

turbograph.core subpackage

Contents

turbograph.core subpackage#

turbograph.core.constant module#

turbograph.core.exception module#

turbograph.core.funccall module#

turbograph.core.specification module#

turbograph.core.attribute module#

turbograph.core.graphwrapper module#

turbograph.core.adapter module#