tracdap.rt.api¶
TRAC model API for Python
Classes¶
Interface that allows model components to interact with the platform at runtime |
|
Base class that model components inherit from to be recognised by the platform |
Functions¶
|
Shorthand alias for |
|
Shorthand alias for |
|
Shorthand alias for |
|
Define an individual model attribute |
|
Define a set of attributes to catalogue and describe a model |
|
Define an individual field for use in a schema |
|
Define a model input with a table schema |
|
Define a model output with a table schema |
|
Define an individual model parameter |
|
Defined the set of parameters used by a model |
|
Create a |
|
Load a |
Attributes¶
Synonym for |
|
Synonym for |
|
Synonym for |
|
Synonym for |
|
Synonym for |
|
Synonym for |
|
Synonym for |
Package Contents¶
- tracdap.rt.api.A(attr_name, attr_value, attr_type=None, categorical=False)¶
Shorthand alias for
define_attribute()
Note
This is an experimental API that is not yet stabilised, expect changes in future versions of TRAC
- tracdap.rt.api.F(field_name, field_type, label, business_key=False, categorical=False, not_null=None, format_code=None, field_order=None)¶
Shorthand alias for
define_field()
- Return type:
- Parameters:
field_name (str)
field_type (
BasicType
)label (str)
business_key (bool)
categorical (bool)
not_null (bool | None)
format_code (str | None)
field_order (int | None)
- tracdap.rt.api.P(param_name, param_type, label, default_value=None, *, param_props=None)¶
Shorthand alias for
define_parameter()
- Return type:
_Named[
ModelParameter
]- Parameters:
param_name (str)
param_type (
BasicType
|TypeDescriptor
)label (str)
default_value (Any | None)
param_props (Dict[str, Any] | None)
- tracdap.rt.api.define_attribute(attr_name, attr_value, attr_type=None, categorical=False)¶
Define an individual model attribute
Note
This is an experimental API that is not yet stabilised, expect changes in future versions of TRAC
Model attributes can be defined using this function or the shorthand alias
A()
. A name and value are always required to define an attribute. Attribute type is required for multivalued attributes but is optional otherwise. The categorical flag can be applied to STRING attributes to mark them as categorical.Model attributes can be passed to
define_attributes()
, either as individual arguments or as a list, to create the set of attributes for a model.- Parameters:
attr_name (str) – The attribute name
attr_value (Any) – The attribute value (as a raw Python value)
attr_type (
BasicType
| None) – The TRAC type for this attribute (optional, except for multivalued attributes)categorical (bool) – A flag to indicate whether this attribute is categorical
- Returns:
A model attribute, in the format understood by the TRAC platform
- Return type:
- tracdap.rt.api.define_attributes(*attributes)¶
Define a set of attributes to catalogue and describe a model
Note
This is an experimental API that is not yet stabilised, expect changes in future versions of TRAC
Model attributes can be defined using
define_attribute()
or the shorthand aliasA()
. This function takes a number of model attributes, either as individual arguments or as a list, and arranges them in the format required byTracModel.define_attributes()
.- Parameters:
attributes (
TagUpdate
| List[TagUpdate
]) – The attributes that will be defined, either as individual arguments or as a list- Returns:
A set of model attributes, in the correct format to return from
TracModel.define_attributes()
- Return type:
List[
TagUpdate
]
- tracdap.rt.api.define_field(field_name, field_type, label, business_key=False, categorical=False, not_null=None, format_code=None, field_order=None)¶
Define an individual field for use in a schema
Individual fields in a schema can be defined using this method or the shorthand alias
F()
. The name, type and label of a field are always required. The business_key and categorical flags are false by default. The not_null flag is false by default unless the field is a business key, in which case it is true by default. Explicitly specifying not_null=False for a business key will cause a validation error. Format code is optional.So long as field order is not specified for any field in a schema, field ordering will be assigned automatically. If field orders are specified explicitly, the fields in a schema must have a contiguous ordering starting at 0. When updating a model it is good practice to leave existing fields in order and add any new fields to the end of the list.
Schema fields can be passed to
define_schema()
, either as individual arguments or as a list, to create aSchemaDefinition
. To define the inputs or outputs of aTracModel
, fields can also be passed directly todefine_input_table()
ordefine_output_table()
.- Parameters:
field_name (str) – The field’s name, used as the field identifier in code and queries (must be a valid identifier)
field_type (
BasicType
) – The data type of the field, only primitive types are allowedlabel (str) – A descriptive label for the field (required)
business_key (bool) – Flag indicating whether this field is a business key for its dataset (default: False)
categorical (bool) – Flag indicating whether this is a categorical field (default: False)
not_null (bool | None) – Whether this field has a not null constraint (default: True for business keys, false otherwise)
format_code (str | None) – A code that can be interpreted by client applications to format the field (optional)
field_order (int | None) – Explicit field ordering (optional)
- Returns:
A field schema, suitable for use in a schema definition
- Return type:
- tracdap.rt.api.define_input_table(*fields, label=None, optional=False, dynamic=False, input_props=None)¶
Define a model input with a table schema
Individual fields can be defined using
define_field()
or the shorthand aliasF()
. This function takes a number of fields, either as individual arguments or as a list, and uses them to create aModelInputSchema
.Use the label property to add a descriptive label to a model input. Inputs can be marked as optional in which case they are not required when running a job, use
TracContext.has_dataset()
to determine whether an optional input has been provided. Inputs can be marked as dynamic in which case the schema is not defined until the model runs, useTracContext.get_schema()
to get the schema of a dynamic input.You can use input_props to associate arbitrary key-value properties with this model input. These properties are not used by the TRAC engine, but are stored in the model metadata for the input and can be used as needed in 3rd-party applications.
- Parameters:
fields (
FieldSchema
| List[FieldSchema
]) – A set of fields to make up aTableSchema
label (str | None) – An optional label (of type str) for a model input schema. Default value: None.
optional (bool) – Mark this input as an optional model input
dynamic (bool) – Mark this input as a dynamic model input (the list of fields must be empty)
input_props (Dict[str, Any] | None) – Associate key-value properties with this input (not used by the TRAC engine)
- Returns:
A model input schema, suitable for returning from
TracModel.define_inputs()
- Return type:
- tracdap.rt.api.define_output_table(*fields, label=None, optional=False, dynamic=False, output_props=None)¶
Define a model output with a table schema
Individual fields can be defined using
define_field()
or the shorthand aliasF()
. This function takes a number of fields, either as individual arguments or as a list, and uses them to create aModelOutputSchema
.Use the label property to add a descriptive label to a model output. Outputs can be marked as optional, a model can decide not to provide an optional output without causing an error. Outputs can be marked as dynamic in which case the schema is not defined until the model runs, use
TracContext.put_schema()
to set the schema of a dynamic output before saving it.You can use output_props to associate arbitrary key-value properties with this model output. These properties are not used by the TRAC engine, but are stored in the model metadata for the output and can be used as needed in 3rd-party applications.
- Parameters:
fields (
FieldSchema
| List[FieldSchema
]) – A set of fields to make up aTableSchema
label (str | None) – An optional label (of type str) for a model output schema. Default value: None.
optional (bool) – Mark this output as an optional model output
dynamic (bool) – Mark this output as a dynamic model output (the list of fields must be empty)
output_props (Dict[str, Any] | None) – Associate key-value properties with this output (not used by the TRAC engine)
- Returns:
A model output schema, suitable for returning from
TracModel.define_outputs()
- Return type:
- tracdap.rt.api.define_parameter(param_name, param_type, label, default_value=None, *, param_props=None)¶
Define an individual model parameter
Model parameters can be defined using this method or the shorthand alias
P()
. Name, type and label are always required to define a parameter. The parameter name is used to set up parameters in a job and to access parameter values at runtime usingTracContext.get_parameter()
.Use the label property to add a descriptive label to a model parameter. If a default value is specified, the model parameter becomes optional. It is ok to omit optional parameters when running models or setting up jobs, in which case the default value will be used. If no default is specified then the model parameter becomes mandatory, a value must always be supplied in order to execute the model. TRAC will apply type coercion where possible to ensure the default value matches the parameter type, if the default value cannot be coerced to match the parameter type then model validation will fail.
You can use param_props to associate arbitrary key-value properties with this model parameter. These properties are not used by the TRAC engine, but are stored in the model metadata for the parameter and can be used as needed in 3rd-party applications.
Model parameters can be passed to
define_parameters()
, either as individual arguments or as a list, to create the set of parameters for a model.- Parameters:
param_name (str) – The parameter name, used to identify the parameter in code (must be a valid identifier)
param_type (
BasicType
|TypeDescriptor
) – The parameter type, expressed in the TRAC type systemlabel (str) – A descriptive label for the parameter (required)
default_value (Any | None) – A default value to use if no explicit value is supplied (optional)
param_props (Dict[str, Any] | None) – Associate key-value properties with this parameter (not used by the TRAC engine)
- Returns:
A named model parameter, suitable for passing to
define_parameters()
- Return type:
_Named[
ModelParameter
]
- tracdap.rt.api.define_parameters(*parameters)¶
Defined the set of parameters used by a model
Model parameters can be defined using
define_parameter()
or the shorthand aliasP()
. This function takes a number of parameters, either as individual arguments or as a list, and arranges them in the format required byTracModel.define_parameters()
- Parameters:
parameters (_Named[
ModelParameter
] | List[_Named[ModelParameter
]]) – The parameters that will be defined, either as individual arguments or as a list- Returns:
A set of model parameters, in the correct format to return from
TracModel.define_parameters()
- Return type:
Dict[str,
ModelParameter
]
- tracdap.rt.api.define_schema(*fields, schema_type=SchemaType.TABLE)¶
Create a
SchemaDefinition
from a list of fieldsIndividual fields can be defined using
define_field()
or the shorthand aliasF()
. This function takes a number of fields, either as individual arguments or as a list, and arranges them into aSchemaDefinition
.A schema type can be specified explicitly using the schema_type parameter, currently only
TABLE
is supported and this is also the default.Note
To define the inputs or outputs of a
TracModel
, usedefine_input_table()
ordefine_output_table()
instead.- Parameters:
fields (
FieldSchema
| List[FieldSchema
]) – The list of fields to include in the schemaschema_type (
SchemaType
) – The type of schema to create (currently only TABLE schemas are supported)
- Returns:
A schema definition built from the supplied fields
- Return type:
- tracdap.rt.api.load_schema(package, schema_file, schema_type=SchemaType.TABLE)¶
Load a
SchemaDefinition
from a CSV file in the model packageThe schema CSV file must contain the following columns:
field_name (string, required)
field_type (
BasicType
, required)label (string, required)
business_key (boolean, optional)
categorical (boolean, optional)
format_code (string, optional)
Field ordering is assigned by the order the fields are listed in the CSV file. A schema type can be specified explicitly using the schema_type parameter, currently only
TABLE
is supported and this is also the default.Note
To define the inputs or outputs of a
TracModel
, a schema can be loaded with this function and used to construct aModelInputSchema
orModelOutputSchema
.- Parameters:
package (ModuleType | str) – Package (or package name) in the model repository that contains the schema file
schema_file (str) – Name of the schema file to load, which must be in the specified package
schema_type (
SchemaType
) – The type of schema to create (currently only TABLE schemas are supported)
- Returns:
A schema definition loaded from the schema file
- Return type:
- tracdap.rt.api.BOOLEAN¶
Synonym for
BasicType.BOOLEAN
- tracdap.rt.api.DATE¶
Synonym for
BasicType.DATE
- tracdap.rt.api.DATETIME¶
Synonym for
BasicType.DATETIME
- tracdap.rt.api.DECIMAL¶
Synonym for
BasicType.DECIMAL
- tracdap.rt.api.FLOAT¶
Synonym for
BasicType.FLOAT
- tracdap.rt.api.INTEGER¶
Synonym for
BasicType.INTEGER
- tracdap.rt.api.STRING¶
Synonym for
BasicType.STRING