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
-
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
-
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
-
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 Pythonlogging
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.
-
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
-
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.
-
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.See also
-
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.See also
-
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.
-
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 agraphcat.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
-
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, withGraph.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 defaultnull()
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 usegraphcat.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), thebuiltins()
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()
orGraph.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