graphcat.common module

Helper classes and functions that can be used with more than one graph type.

class graphcat.common.Array(value)[source]

Bases: object

Task function callable that returns a caller-supplied array.

Parameters:value (numpy.ndarray convertable object, required) – The array to use as the output for this callable.

See also

array()

class graphcat.common.ArrayExtent[source]

Bases: object

Helper for creating Array compatible streaming extents.

To generate extents, use any numpy-compatible indexing notation:

extent = ArrayExtent[0:4096]
extent = ArrayExtent[::2]
extent = ArrayExtent[:, 0]
...

These extents are compatible with Array.

class graphcat.common.Constant(value)[source]

Bases: object

Task function callable that returns a caller-supplied value.

Parameters:value (any Python object, required) – The value to use as the output for this callable.

See also

constant()

class graphcat.common.Delay(seconds)[source]

Bases: object

Task function callable that sleeps for a fixed time.

This is mainly useful for testing and debugging.

Parameters:seconds (number, required) – The number of seconds to sleep when executed.

See also

delay()

exception graphcat.common.DeprecationWarning[source]

Bases: Warning

Warning category for deprecated code.

class graphcat.common.Input[source]

Bases: enum.Enum

Enumerates special graphcat.graph.Graph named inputs.

IMPLICIT = 1

Named input for links that are generated automatically for use as implicit dependencies, not data sources.

class graphcat.common.Logger(graph, log_exceptions=True, log_inputs=True, log_outputs=True, log_extents=True, log=<Logger graphcat.common (WARNING)>)[source]

Bases: object

Log graph events.

Create a Logger object to see the behavior of the graph during updates, using the Python logging module:

logger = graphcat.Logger(graph)

This is useful for debugging and pedagogy. The logger will generate output for five types of event:

  • cycle - a cycle is detected during updating.
  • executed - a task is executed.
  • failed - a task raises an exception during execution.
  • finished - a task executes successfully.
  • updated - a task is updated.

Update events happen regardless of the state of a task. Execute events only happen if the task isn’t already finished. Failed and finished events only happen if a task is executed.

Parameters:graph (class:graphcat.graph.Graph, required) – The graph whose events will be logged.
on_cycle(graph, name)[source]

Called when a cycle is detected.

on_execute(graph, name, inputs, extent=None)[source]

Called when a task is executed.

on_failed(graph, name, exception)[source]

Called when a task raises an exception during execution.

on_finished(graph, name, output)[source]

Called when a task has executed sucessfully.

on_update(graph, name)[source]

Called when a task is updated.

class graphcat.common.Passthrough(input)[source]

Bases: object

Task function callable that always returns an upstream input.

Parameters:input (hashable object, required) – Name of the input to be returned when this task is executed. Note that there must be exactly one connection to the named input, or an exception will be raised.

See also

passthrough()

class graphcat.common.PerformanceMonitor(graph)[source]

Bases: object

Tracks the performance of graph tasks as they’re executed.

Parameters:graph (graphcat.graph.Graph, required) – Graph whose performance will be monitored.
reset()[source]

Clear performance data.

tasks

Graph task execution times since this object was created / reset.

Returns:tasks – Maps the name of every task that has been updated to an array containing execution times.
Return type:dict containing list values.
class graphcat.common.RaiseException(exception)[source]

Bases: object

Task function callable that raises an exception when executed.

This is mainly useful for testing and debugging.

Parameters:exception (Exception, required) – The exception to be raised when the task is executed.
class graphcat.common.TaskState[source]

Bases: enum.Enum

Enumerates graphcat.graph.Graph task states.

Every task within a graphcat.graph.Graph will always be in one of the following states.

FAILED = 2

The task or one of it’s dependencies failed during the last update.

FINISHED = 3

The task executed successfully during the last update.

UNFINISHED = 1

The task is out-of-date and will be executed during the next update.

class graphcat.common.UpdatedTasks(graph)[source]

Bases: object

Maintains a list of graph tasks that have been updated.

Parameters:graph (graphcat.graph.Graph, required) – Graph to watch for task updates.
tasks

Graph tasks that have received updates since this object was created.

Returns:tasks – Python set containing the name of every task that has been updated.
Return type:set
graphcat.common.array(value)[source]

Factory for task functions that return array values when executed.

Note

This callable is designed to be compatible with ArrayExtent extents when used in a graphcat.streaming.StreamingGraph.

Parameters:value (numpy.ndarray-convertable value, required) – The array to return when the task is executed.
Returns:fn – Task function that will always return value when executed.
Return type:Array
graphcat.common.automatic_dependencies(fn)[source]

Function decorator that automatically tracks dependencies.

Use this to decorate task functions that need dependency tracking, such as evaluate().

See also

graphcat.graph.Graph.set_expression()
Convenience method that configures a task to evaluate expressions and automatically track dependencies.
graphcat.common.builtins(graph, name, inputs, extent=None)[source]

Returns standard builtin symbols for expression tasks.

See also

evaluate()

graphcat.common.constant(value)[source]

Factory for task functions that return constant values when executed.

This is useful when creating a task that will act as a parameter for a downstream task:

graph.add_task("theta", constant(math.pi))

To change the parameter later, use constant() again, with Graph.set_task_fn() to specify a new function:

graph.set_task_fn("theta", constant(math.pi / 2))
Parameters:value (any value, required) – The value to return when the task is executed.
Returns:fn – Task function that will always return value when executed.
Return type:Constant
graphcat.common.consume(graph, name, inputs, extent=None)[source]

Task function that retrieves all its inputs, but otherwise does nothing.

This is mainly useful for debugging dynamic graphs, since the default null() task function won’t execute upstream nodes.

graphcat.common.delay(seconds)[source]

Factory for task functions that sleep for a fixed time.

This is mainly useful for testing and debugging.

Parameters:seconds (number, required) – Number of seconds to sleep when executed.
Returns:fn – Task function that will always sleep for seconds when executed.
Return type:function
graphcat.common.evaluate(code, symbols=None)[source]

Factory for task functions that evaluate Python expressions.

If your expressions can access the output from other tasks in the graph, you will want to use this function with the automatic_dependencies() decorator, or use graphcat.graph.Graph.set_expression() which sets up dependency tracking for you.

See also

graphcat.graph.Graph.set_expression()
Convenience method that configures a task to evaluate expressions and automatically track dependencies.
Parameters:
  • code (string, required) – Python code to be executed when the task is executed.
  • symbols (callable, optional) – Function that returns a Python dict containing symbols that will be available to the expression when it’s executed. If None (the default), the builtins() function will be used, which gives the expression access to the same graph, name, inputs, and extent objects as a normal task function.
Returns:

fn – Task function that will execute Python code when the task is executed.

Return type:

function

graphcat.common.null(graph, name, inputs, extent=None)[source]

Task function that does nothing.

This is the default if you don’t specify a function for Graph.add_task() or Graph.set_task_fn(), and is useful in debugging and pedagogy.

graphcat.common.passthrough(input=None)[source]

Factory for task functions that pass-through incoming data.

Callers can use this function to temporarily bypass tasks in the graph.

Parameters:input (hashable object, required) – The named input that will pass-through to the task output.
Returns:fn – Task function that will pass the input value named input to its output.
Return type:function
graphcat.common.raise_exception(exception)[source]

Factory for task functions that raise an exception when executed.

This is mainly useful for testing and debugging.

Parameters:exception (BaseException derivative, required) – The exception to raise when the task is executed.
Returns:fn – Task function that will always raise exception when executed.
Return type:function