tracdap-runtime 0.6.1.dev3__py3-none-any.whl → 0.6.2__py3-none-any.whl

tracdap/rt/metadata/flow.py

@@ -13,20 +13,48 @@ from .tag_update import *  # noqa
 
 class FlowNodeType(_enum.Enum):
 
-    NODE_TYPE_NOT_SET = 0, 
+    """
+    Specify the type of an individual flow node
+    
+    .. seealso::
+        :class:`FlowNode <FlowNode>`
+    """
 
-    INPUT_NODE = 1, 
+    NODE_TYPE_NOT_SET = 0
 
-    OUTPUT_NODE = 2, 
+    INPUT_NODE = 1
 
-    MODEL_NODE = 3, 
+    """Input nodes described inputs to the flow, such as a files or datasets"""
+
+    OUTPUT_NODE = 2
+
+    """Output nodes describe outputs the flow produces, such as a files or datasets"""
+
+    MODEL_NODE = 3
+
+    """Model nodes are placeholders for TRAC models that will be supplied at runtime"""
+
+    PARAMETER_NODE = 4
+
+    """Parameter nodes allow explicit mapping of parameters into models
+    (TRAC can infer parameters by name if they are not defined explicitly)
+    """
 
 
 @_dc.dataclass
 class FlowNode:
 
+    """
+    Describes an individual node in a flow
+    
+    .. seealso::
+        :class:`FlowDefinition <FlowDefinition>`
+    """
+
     nodeType: FlowNodeType = FlowNodeType.NODE_TYPE_NOT_SET
 
+    parameters: _tp.List[str] = _dc.field(default_factory=list)
+
     inputs: _tp.List[str] = _dc.field(default_factory=list)
 
     outputs: _tp.List[str] = _dc.field(default_factory=list)
@@ -35,12 +63,28 @@ class FlowNode:
 
     nodeAttrs: _tp.List[TagUpdate] = _dc.field(default_factory=list)
 
+    nodeProps: _tp.Dict[str, Value] = _dc.field(default_factory=dict)
+
     label: str = None
 
 
 @_dc.dataclass
 class FlowSocket:
 
+    """
+    A socket is a point of connection for wiring up the edges in a flow
+    
+    For parameter, input and output nodes the socket is just the node name and the socket field will be blank.
+    For models, the node name refers to a model node and the socket is the name of the parameter, input or output
+    being connected. E.g. these two sockets could be used to connect a flow input to a model, using an edge::
+    
+      flow_input_socket = { "node": "my_input_dataset", socket: "" }
+      model_input_socket = { "node": "my_model", "socket": "input_1" }.
+    
+    .. seealso::
+        :class:`FlowEdge <FlowEdge>`
+    """
+
     node: str = None
 
     socket: str = None
@@ -49,6 +93,13 @@ class FlowSocket:
 @_dc.dataclass
 class FlowEdge:
 
+    """
+    A connection between two nodes in a flow
+    
+    .. seealso::
+        :class:`FlowSocket <FlowSocket>`
+    """
+
     source: FlowSocket = None
 
     target: FlowSocket = None
@@ -57,6 +108,17 @@ class FlowEdge:
 @_dc.dataclass
 class FlowDefinition:
 
+    """
+    A flow defines an execution graph as a set of connections between models and data
+    
+    A flow describes the shape of the execution graph, it does not fix in advance the set
+    of models and datasets that will go into it. When a RUN_FLOW job is created, the job
+    matches the flow with a set of models, inputs, outputs and parameters.
+    
+    .. seealso::
+        :class:`JobDefinition <JobDefinition>`
+    """
+
     nodes: _tp.Dict[str, FlowNode] = _dc.field(default_factory=dict)
 
     edges: _tp.List[FlowEdge] = _dc.field(default_factory=list)

tracdap/rt/metadata/job.py

@@ -12,45 +12,79 @@ from .tag_update import *  # noqa
 
 class JobType(_enum.Enum):
 
-    JOB_TYPE_NOT_SET = 0, 
+    """Specify the type of an individual TRAC job"""
 
-    RUN_MODEL = 1, 
+    JOB_TYPE_NOT_SET = 0
 
-    RUN_FLOW = 2, 
+    RUN_MODEL = 1
 
-    IMPORT_MODEL = 3, 
+    """Run a single model, with parameters and inputs"""
 
-    IMPORT_DATA = 4, 
+    RUN_FLOW = 2
+
+    """Run a flow with all its models, parameters and inputs"""
+
+    IMPORT_MODEL = 3
+
+    """Import a model into the platform"""
+
+    IMPORT_DATA = 4
+
+    """Import data into the platform"""
 
 
 class JobStatusCode(_enum.Enum):
 
-    JOB_STATUS_CODE_NOT_SET = 0, 
+    """Indicate the status of a job in the TRAC platform"""
+
+    JOB_STATUS_CODE_NOT_SET = 0
+
+    PREPARING = 1
+
+    """The job is being set up"""
+
+    VALIDATED = 2
+
+    """The job has passed validation and is ok to run (dry-run operations may return this status)"""
 
-    PREPARING = 1, 
+    PENDING = 3
 
-    VALIDATED = 2, 
+    """The job is being set up"""
 
-    PENDING = 3, 
+    QUEUED = 4
 
-    QUEUED = 4, 
+    """The job is queued in TRAC, waiting for available resources"""
 
-    SUBMITTED = 5, 
+    SUBMITTED = 5
 
-    RUNNING = 6, 
+    """The job has been submitted for execution but has not yet started"""
 
-    FINISHING = 7, 
+    RUNNING = 6
 
-    SUCCEEDED = 8, 
+    """The job is currently running"""
 
-    FAILED = 9, 
+    FINISHING = 7
 
-    CANCELLED = 10, 
+    """Job execution completed, the platform is cleaning up and validating the outputs"""
+
+    SUCCEEDED = 8
+
+    """The job completed successfully and the results are available"""
+
+    FAILED = 9
+
+    """The job failed and has been terminated or rejected"""
+
+    CANCELLED = 10
+
+    """The job was cancelled by a user of the platform"""
 
 
 @_dc.dataclass
 class JobDefinition:
 
+    """Define a job to run on the TRAC platform"""
+
     jobType: JobType = JobType.JOB_TYPE_NOT_SET
 
     runModel: _tp.Optional[RunModelJob] = None
@@ -63,6 +97,8 @@ class JobDefinition:
 @_dc.dataclass
 class RunModelJob:
 
+    """Specification for a RuN_MODEL job"""
+
     model: TagSelector = None
 
     parameters: _tp.Dict[str, Value] = _dc.field(default_factory=dict)
@@ -79,6 +115,8 @@ class RunModelJob:
 @_dc.dataclass
 class RunFlowJob:
 
+    """Specification for a RUN_FLOW job"""
+
     flow: TagSelector = None
 
     parameters: _tp.Dict[str, Value] = _dc.field(default_factory=dict)
@@ -97,6 +135,8 @@ class RunFlowJob:
 @_dc.dataclass
 class ImportModelJob:
 
+    """Specification for an IMPORT_MODEL job"""
+
     language: str = None
 
     repository: str = None

tracdap/rt/metadata/model.py

@@ -41,6 +41,8 @@ class ModelInputSchema:
 
     label: _tp.Optional[str] = None
 
+    optional: bool = None
+
 
 @_dc.dataclass
 class ModelOutputSchema:
@@ -62,6 +64,8 @@ class ModelOutputSchema:
 
     label: _tp.Optional[str] = None
 
+    optional: bool = None
+
 
 @_dc.dataclass
 class ModelDefinition:

tracdap/rt/metadata/object_id.py

@@ -17,23 +17,23 @@ class ObjectType(_enum.Enum):
         :class:`ObjectDefinition <ObjectDefinition>`
     """
 
-    OBJECT_TYPE_NOT_SET = 0, 
+    OBJECT_TYPE_NOT_SET = 0
 
-    DATA = 1, 
+    DATA = 1
 
-    MODEL = 2, 
+    MODEL = 2
 
-    FLOW = 3, 
+    FLOW = 3
 
-    JOB = 4, 
+    JOB = 4
 
-    FILE = 5, 
+    FILE = 5
 
-    CUSTOM = 6, 
+    CUSTOM = 6
 
-    STORAGE = 7, 
+    STORAGE = 7
 
-    SCHEMA = 8, 
+    SCHEMA = 8
 
 
 @_dc.dataclass

tracdap/rt/metadata/search.py

@@ -18,9 +18,11 @@ class SearchOperator(_enum.Enum):
         :class:`SearchTerm <SearchTerm>`
     """
 
-    SEARCH_OPERATOR_NOT_SET = 0, 
+    SEARCH_OPERATOR_NOT_SET = 0
 
-    EQ = 1, """EQUALS
+    EQ = 1
+
+    """EQUALS
     
     The EQ operator matches a tag when the tag has an attribute that matches the
     search term exactly, i.e. attribute name, type and value all match. For
@@ -32,7 +34,9 @@ class SearchOperator(_enum.Enum):
     for this reason it is not recommended to use the EQ operator with FLOAT values.
     """
 
-    NE = 2, """DOES NOT EQUAL
+    NE = 2
+
+    """DOES NOT EQUAL
     
     The NE operator matches a tag precisely when the EQ operator does not match it.
     This could be because the tag attribute does not match the search term, or because
@@ -48,7 +52,9 @@ class SearchOperator(_enum.Enum):
     for this reason it is not recommended to use the NE operator with FLOAT values.
     """
 
-    LT = 3, """LESS THAN
+    LT = 3
+
+    """LESS THAN
     
     The LT operator matches a tag when the tag has an attribute with a value less than
     the search parameter. The LT operator will only match single-valued attributes.
@@ -58,7 +64,9 @@ class SearchOperator(_enum.Enum):
     even if one or more of the individual values matches the search term.
     """
 
-    LE = 4, """LESS THAN OR EQUAL TO
+    LE = 4
+
+    """LESS THAN OR EQUAL TO
     
     The LE operator matches a tag when the tag has an attribute with a value less than
     or equal to the search parameter. The LE operator will only match single-valued
@@ -69,7 +77,9 @@ class SearchOperator(_enum.Enum):
     even if one or more of the individual values matches the search term.
     """
 
-    GT = 5, """GREATER THAN
+    GT = 5
+
+    """GREATER THAN
     
     The GT operator matches a tag when the tag has an attribute with a value greater than
     the search parameter. The GT operator will only match single-valued attributes.
@@ -79,7 +89,9 @@ class SearchOperator(_enum.Enum):
     even if one or more of the individual values matches the search term.
     """
 
-    GE = 6, """GREATER THAN OR EQUAL TO
+    GE = 6
+
+    """GREATER THAN OR EQUAL TO
     
     The GE operator matches a tag when the tag has an attribute with a value greater than
     or equal to the search parameter. The GE operator will only match single-valued
@@ -90,7 +102,9 @@ class SearchOperator(_enum.Enum):
     even if one or more of the individual values matches the search term.
     """
 
-    IN = 7, """IN
+    IN = 7
+
+    """IN
     
     The IN operator matches a tag when the tag has an attribute whose value is matched
     exactly by an item in the list of values provided. For multi-valued attributes, the
@@ -103,7 +117,9 @@ class SearchOperator(_enum.Enum):
     for this reason it is not recommended to use the IN operator with FLOAT values.
     """
 
-    EXISTS = 8, """EXISTS
+    EXISTS = 8
+
+    """EXISTS
     
     If an attribute type is provided the EXISTS operator matches a tag of specified
     name when the tag has an attribute whose type is matched with type provided attribute
@@ -121,23 +137,29 @@ class LogicalOperator(_enum.Enum):
         :class:`LogicalExpression <LogicalExpression>`
     """
 
-    LOGICAL_OPERATOR_NOT_SET = 0, 
+    LOGICAL_OPERATOR_NOT_SET = 0
+
+    AND = 1
 
-    AND = 1, """LOGICAL AND
+    """LOGICAL AND
     
     The AND operator combines two or more search expressions, the logical expression
     will match only when all sub-expressions match. The order of sub-expressions is
     not important.
     """
 
-    OR = 2, """LOGICAL OR
+    OR = 2
+
+    """LOGICAL OR
     
     The OR operator combines two or more search expressions, the logical expression
     will match when any of the sub-expressions match. The order of sub-expressions
     is not important.
     """
 
-    NOT = 3, """LOGICAL NOT
+    NOT = 3
+
+    """LOGICAL NOT
     
     The NOT operator applies to a single sub-expression, the logical expression will
     match precisely when the sub-expression does not match.

tracdap/rt/metadata/stoarge.py

@@ -10,25 +10,56 @@ from .type import *  # noqa
 
 class CopyStatus(_enum.Enum):
 
-    COPY_STATUS_NOT_SET = 0, 
+    """
+    Status of an individual copy of a data storage item
+    
+    .. seealso::
+        :class:`StorageDefinition <StorageDefinition>`,
+        :class:`StorageCopy <StorageCopy>`
+    """
 
-    COPY_AVAILABLE = 1, 
+    COPY_STATUS_NOT_SET = 0
 
-    COPY_EXPUNGED = 2, 
+    COPY_AVAILABLE = 1
+
+    """The copy of the data item is available in storage to access"""
+
+    COPY_EXPUNGED = 2
+
+    """The copy of the data item has been expunged and is no longer available"""
 
 
 class IncarnationStatus(_enum.Enum):
 
-    INCARNATION_STATUS_NOT_SET = 0, 
+    """
+    Status of an individual incarnation of a data storage item
+    
+    .. seealso::
+        :class:`StorageDefinition <StorageDefinition>`,
+        :class:`StorageIncarnation <StorageIncarnation>`
+    """
+
+    INCARNATION_STATUS_NOT_SET = 0
+
+    INCARNATION_AVAILABLE = 1
 
-    INCARNATION_AVAILABLE = 1, 
+    """The incarnation of the data item has at least one copy available in storage"""
 
-    INCARNATION_EXPUNGED = 2, 
+    INCARNATION_EXPUNGED = 2
+
+    """This incarnation of the data item is no longer available in storage, all copies have been expunged"""
 
 
 @_dc.dataclass
 class StorageCopy:
 
+    """
+    Define physical storage for an individual copy of a data item
+    
+    .. seealso::
+        :class:`StorageDefinition <StorageDefinition>`
+    """
+
     storageKey: str = None
 
     storagePath: str = None
@@ -45,6 +76,13 @@ class StorageCopy:
 @_dc.dataclass
 class StorageIncarnation:
 
+    """
+    Define physical storage for an individual incarnation of a data item
+    
+    .. seealso::
+        :class:`StorageDefinition <StorageDefinition>`
+    """
+
     copies: _tp.List[StorageCopy] = _dc.field(default_factory=list)
 
     incarnationIndex: int = None
@@ -57,12 +95,32 @@ class StorageIncarnation:
 @_dc.dataclass
 class StorageItem:
 
+    """
+    Define physical storage for an individual data item
+    
+    .. seealso::
+        :class:`StorageDefinition <StorageDefinition>`
+    """
+
     incarnations: _tp.List[StorageIncarnation] = _dc.field(default_factory=list)
 
 
 @_dc.dataclass
 class StorageDefinition:
 
+    """
+    Defines the physical storage for a file or dataset object
+    
+    Each storage item corresponds to one logical data item, such as a version of
+    a file or a snapshot of a data partition. Storage for each item is broken down
+    into incarnations (data that has been expunged and recomputed) and copies
+    (physical file-level copies for resilience, locality etc).
+    
+    .. seealso::
+        :class:`DataDefinition <DataDefinition>`,
+        :class:`FileDefinition <FileDefinition>`
+    """
+
     dataItems: _tp.Dict[str, StorageItem] = _dc.field(default_factory=dict)
 
     storageOptions: _tp.Dict[str, Value] = _dc.field(default_factory=dict)

tracdap/rt/metadata/tag_update.py

@@ -17,7 +17,9 @@ class TagOperation(_enum.Enum):
         :class:`TagUpdate <TagUpdate>`
     """
 
-    CREATE_OR_REPLACE_ATTR = 0, """Add an attribute to a tag or replace it if it already exists.
+    CREATE_OR_REPLACE_ATTR = 0
+
+    """Add an attribute to a tag or replace it if it already exists.
     
     This is the default operation if no operation is specified. If the
     attribute does not exist it will be created using CREATE_ATTR, otherwise
@@ -28,7 +30,9 @@ class TagOperation(_enum.Enum):
         :class:`REPLACE_ATTR <TagOperation.REPLACE_ATTR>`
     """
 
-    CREATE_OR_APPEND_ATTR = 1, """Add an attribute to a tag or append to it if it already exists.
+    CREATE_OR_APPEND_ATTR = 1
+
+    """Add an attribute to a tag or append to it if it already exists.
     
     If the attribute does not exist it will be created using CREATE_ATTR,
     otherwise it will appended to using APPEND_ATTR.
@@ -38,9 +42,13 @@ class TagOperation(_enum.Enum):
         :class:`APPEND_ATTR <TagOperation.APPEND_ATTR>`
     """
 
-    CREATE_ATTR = 2, """Add an attribute to a tag, fail if the attribute already exists."""
+    CREATE_ATTR = 2
+
+    """Add an attribute to a tag, fail if the attribute already exists."""
+
+    REPLACE_ATTR = 3
 
-    REPLACE_ATTR = 3, """Replace an attribute on a tag, fail if the attribute does not exist.
+    """Replace an attribute on a tag, fail if the attribute does not exist.
     
     When replacing an attribute, the new attribute must be of the same basic
     type as the old one. It is allowed to replace a single-valued attribute
@@ -53,7 +61,9 @@ class TagOperation(_enum.Enum):
     DELETE_ATTR followed by CREATE_ATTR.
     """
 
-    APPEND_ATTR = 4, """Append one or more values to an existing attribute, fail if the attribute
+    APPEND_ATTR = 4
+
+    """Append one or more values to an existing attribute, fail if the attribute
     does not exist.
     
     The existing attribute may be single- or multi-valued and the append
@@ -62,9 +72,13 @@ class TagOperation(_enum.Enum):
     existing value(s).
     """
 
-    DELETE_ATTR = 5, """Remove an attribute from a tag, fail if the attribute does not exist."""
+    DELETE_ATTR = 5
+
+    """Remove an attribute from a tag, fail if the attribute does not exist."""
+
+    CLEAR_ALL_ATTR = 6
 
-    CLEAR_ALL_ATTR = 6, """Remove all the attributes from a tag.
+    """Remove all the attributes from a tag.
     
     This operation does not affect controlled attributes, which are still
     managed by TRAC according to its normal rules.

tracdap/rt/metadata/type.py

@@ -5,29 +5,36 @@ import typing as _tp  # noqa
 import dataclasses as _dc  # noqa
 import enum as _enum  # noqa
 
-from .common import *  # noqa
-
-
 class BasicType(_enum.Enum):
 
     """Basic types provide the set of core types available in the TRAC type system."""
 
-    BASIC_TYPE_NOT_SET = 0, 
+    BASIC_TYPE_NOT_SET = 0
+
+    BOOLEAN = 1
+
+    """A true/false value"""
+
+    INTEGER = 2
+
+    """64 bit signed integer"""
 
-    BOOLEAN = 1, """A true/false value"""
+    FLOAT = 3
 
-    INTEGER = 2, """64 bit signed integer"""
+    """64 bit signed floating point number (referred to as 'double' in many languages)"""
 
-    FLOAT = 3, """64 bit signed floating point number (referred to as 'double' in many languages)"""
+    STRING = 4
 
-    STRING = 4, """UTF encoded string value of arbitrary length.
+    """UTF encoded string value of arbitrary length.
     
     The encoding used (e.g. UTF-8, UTF-16, UCS-16) varies between languages / platforms,
     generally TRAC will present strings using the standard encoding for a given language or
     protocol.
     """
 
-    DECIMAL = 5, """A fixed-point decimal value with known precision and scale.
+    DECIMAL = 5
+
+    """A fixed-point decimal value with known precision and scale.
     
     The available precision and scale may vary between languages / platforms.
     
@@ -37,12 +44,16 @@ class BasicType(_enum.Enum):
          precision - scale >= 21
     """
 
-    DATE = 6, """A date value.
+    DATE = 6
+
+    """A date value.
     
     Dates do not take any account of time zones or offsets from UTC.
     """
 
-    DATETIME = 7, """A date-time value.
+    DATETIME = 7
+
+    """A date-time value.
     
     Date-time values may be expressed with an offset from UTC, as per ISO 8601.
     The available sub-second precision may vary depending on language / platform.
@@ -52,12 +63,16 @@ class BasicType(_enum.Enum):
     supplied with an offset.
     """
 
-    ARRAY = 8, """An array of values, which may be primitive or composite values.
+    ARRAY = 8
+
+    """An array of values, which may be primitive or composite values.
     
     All items in an array must have the same type (i.e. the same type descriptor).
     """
 
-    MAP = 9, """An key-value map with string keys, values may be primitive or composite values.
+    MAP = 9
+
+    """An key-value map with string keys, values may be primitive or composite values.
     
     Maps may be uniform, in which case all the values are of the same type, or non-
     uniform in which case values can be of any type. For uniform maps the type