tracdap.rt.api¶

TRAC model API for Python

Classes¶

`CommonFileTypes`	A collection of common `FileTypes` to use as model inputs and outputs
`RuntimeMetadata`	The metadata associated with a TRAC object, made available for models at runtime
`TracContext`	Interface that allows model components to interact with the platform at runtime
`TracModel`	Base class that model components inherit from to be recognised by the platform

Functions¶

`A`(attr_name, attr_value[, attr_type, categorical])	Shorthand alias for `define_attribute()`
`F`(field_name, field_type, label[, business_key, ...])	Shorthand alias for `define_field()`
`P`(param_name, param_type, label[, default_value, ...])	Shorthand alias for `define_parameter()`
`define_attribute`(attr_name, attr_value[, attr_type, ...])	Define an individual model attribute
`define_attributes`(*attributes)	Define a set of attributes to catalogue and describe a model
`define_field`(field_name, field_type, label[, ...])	Define an individual field for use in a schema
`define_file_type`(extension, mime_type)	Define a `FileType` for a given extension and mime type.
`define_input`(requirement, *[, label, optional, ...])	Define a model input, which can be any type of dataset or file
`define_input_file`(extension, mime_type, *[, label, ...])	Define a model input for a `FileType`
`define_input_struct`(struct_type, *[, label, optional, ...])	Define a model input for a `STRUCT_SCHEMA`.
`define_input_table`(*fields[, label, optional, ...])	Define a model input for a `TABLE_SCHEMA`.
`define_output`(requirement, *[, label, optional, ...])	Define a model output, which can be any type of dataset or file
`define_output_file`(extension, mime_type, *[, label, ...])	Define a model output for a `FileType`
`define_output_struct`(struct_type, *[, label, ...])	Define a model output for a `STRUCT_SCHEMA`.
`define_output_table`(*fields[, label, optional, ...])	Define a model output for a `TABLE_SCHEMA`.
`define_parameter`(param_name, param_type, label[, ...])	Define an individual model parameter
`define_parameters`(*parameters)	Defined the set of parameters used by a model
`define_schema`(*fields[, schema_type, dynamic])	Create a `SchemaDefinition` from a list of fields
`define_struct`(struct_type)	Define a `STRUCT_SCHEMA` from a Python
`define_table`(*fields)	Define a :py:attr:`TABLE_SCHEMA <tracdap.rt.metadata.SchemaType.TABLE_SCHEMA>`from a list of fields
`load_resource`(package, resource_file)	Load a binary resource from the model repository
`load_resource_stream`(package, resource_file)	Load a binary resource from the model repository as a readable stream
`load_schema`(package, schema_file[, schema_type])	Load a `SchemaDefinition` from a CSV file in the model package
`load_text_resource`(package, resource_file[, encoding])	Load a text resource from the model repository
`load_text_resource_stream`(package, resource_file[, ...])	Load a text resource from the model repository as a text stream

Attributes¶

`BOOLEAN`	Synonym for `BasicType.BOOLEAN`
`DATE`	Synonym for `BasicType.DATE`
`DATETIME`	Synonym for `BasicType.DATETIME`
`DECIMAL`	Synonym for `BasicType.DECIMAL`
`FLOAT`	Synonym for `BasicType.FLOAT`
`INTEGER`	Synonym for `BasicType.INTEGER`
`STRING`	Synonym for `BasicType.STRING`
`STRUCT_TYPE`	Template type for use with STRUCT data objects, which can be either Python dataclasses or Pydantic models

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

Return type:

TagUpdate

Parameters:

attr_name (str)
attr_value (Any)
attr_type (BasicType | None)
categorical (bool)

tracdap.rt.api.F(field_name, field_type, label, business_key=False, categorical=False, not_null=False, format_code=None, field_order=None)¶

Shorthand alias for define_field()

Return type:

FieldSchema

Parameters:

field_name (str)
field_type (BasicType)
label (str)
business_key (bool)
categorical (bool)
not_null (bool)
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:

TagUpdate

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 alias A(). This function takes a number of model attributes, either as individual arguments or as a list, and arranges them in the format required by TracModel.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=False, 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, categorical and not_null flags are false by default. TRAC will always set not_null = True for business keys, even if not_null = False is passed explicitly. 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 a SchemaDefinition. To define the inputs or outputs of a TracModel, fields can also be passed directly to define_input_table() or define_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 allowed
label (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) – Whether this field has a not null constraint (default: False)
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:

FieldSchema

tracdap.rt.api.define_file_type(extension, mime_type)¶

Define a FileType for a given extension and mime type.

Return type:

FileType

Parameters:

extension (str)
mime_type (str)

tracdap.rt.api.define_input(requirement, *, label=None, optional=False, dynamic=False, input_props=None)¶

Define a model input, which can be any type of dataset or file

Return type:

ModelInputSchema

Parameters:

requirement (SchemaDefinition | FileType)
label (str | None)
optional (bool)
dynamic (bool)
input_props (dict[str, Value)

tracdap.rt.api.define_input_file(extension, mime_type, *, label=None, optional=False, input_props=None)¶

Define a model input for a FileType

:type extension str :type mime_type: sr :type label: str | None :type optional: bool :type input_props: dict[str, Any] | None :rtype: ModelInputSchema

Parameters:

extension (str)
mime_type (str)
label (Optional[str])
optional (bool)
input_props (Optional[Dict[str, Any]])

Return type:

ModelInputSchema

tracdap.rt.api.define_input_struct(struct_type, *, label=None, optional=False, input_props=None)¶

Define a model input for a STRUCT_SCHEMA. Validation is performed and the result is a ModelInputSchema suitable to return from define_inputs().

This method is equivalent to calling define_struct() and then define_input().

Parameters:

struct_type (type) – The dataclass or Pydantic model type to build a struct schema for
label (str | None) – Human readable label for the model input
optional (bool) – Whether this model input is optional (default = False)
input_props (dict[str, any] | None) – An optional set of user-defined properties to set on the model input

Returns:

A valid input schema suitable to return from define_inputs()

Return type:

ModelInputSchema

tracdap.rt.api.define_input_table(*fields, label=None, optional=False, dynamic=False, input_props=None)¶

Define a model input for a TABLE_SCHEMA.

Individual fields can be defined using define_field() or the shorthand alias F(). This function takes a number of fields, either as individual arguments or as a list, and uses them to create a ModelInputSchema.

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, use TracContext.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 a table schema
label (str | None) – Human readable label for the model input
optional (bool) – Whether this model input is optional (default = False)
dynamic (bool) – Whether this model input has a dynamic schema (the list of fields must be empty)
input_props (Dict[str, Any] | None) – An optional set of user-defined properties to set on the model input

Returns:

A valid output schema suitable to return from define_outputs()

Return type:

ModelInputSchema

tracdap.rt.api.define_output(requirement, *, label=None, optional=False, dynamic=False, output_props=None)¶

Define a model output, which can be any type of dataset or file

Return type:

ModelOutputSchema

Parameters:

requirement (SchemaDefinition | FileType)
label (str | None)
optional (bool)
dynamic (bool)
output_props (dict[str, Value)

tracdap.rt.api.define_output_file(extension, mime_type, *, label=None, optional=False, output_props=None)¶

Define a model output for a FileType

:type extension str :type mime_type: sr :type label: str | None :type optional: bool :type output_props: dict[str, Any] | None :rtype: ModelOutputSchema

Parameters:

extension (str)
mime_type (str)
label (Optional[str])
optional (bool)
output_props (Optional[Dict[str, Any]])

Return type:

ModelOutputSchema

tracdap.rt.api.define_output_struct(struct_type, *, label=None, optional=False, output_props=None)¶

Define a model output for a STRUCT_SCHEMA. Validation is performed and the result is a ModelOutputSchema suitable to return from define_outputs().

This method is equivalent to calling define_struct() and then define_output().

Parameters:

struct_type (type) – The dataclass or Pydantic model type to build a struct schema for
label (str | None) – Human readable label for the model output
optional (bool) – Whether this model output is optional (default = False)
output_props (dict[str, any] | None) – An optional set of user-defined properties to set on the model output

Returns:

A valid output schema suitable to return from define_outputs()

Return type:

ModelOutputSchema

tracdap.rt.api.define_output_table(*fields, label=None, optional=False, dynamic=False, output_props=None)¶

Define a model output for a TABLE_SCHEMA.

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 a table schema
label (str | None) – Human readable label for the model output
optional (bool) – Whether this model output is optional (default = False)
dynamic (bool) – Whether this model output has a dynamic schema (the list of fields must be empty)
output_props (Dict[str, Any] | None) – An optional set of user-defined properties to set on the model output

Returns:

A valid output schema suitable to return from define_outputs()

Return type:

ModelOutputSchema

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 using TracContext.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 system
label (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 alias P(). This function takes a number of parameters, either as individual arguments or as a list, and arranges them in the format required by TracModel.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_SCHEMA, dynamic=False)¶

Create a SchemaDefinition from a list of fields

Individual fields can be defined using define_field() or the shorthand alias F(). This function takes a number of fields, either as individual arguments or as a list, and arranges them into a SchemaDefinition.

A schema type can be specified explicitly using the schema_type parameter, if unspecified the default is TABLE_SCHEMA.

If the schema is not known in advance, setting dynamic = True will create a schema that is resolved at runtime. Dynamic schemas still have a SchemaType, so e.g. STRUCT_SCHEMA and TABLE_SCHEMA and cannot be used interchangeably at runtime. A schema marked as dynamic must not include any fields.

Parameters:

fields (FieldSchema | List[FieldSchema]) – The list of fields to include in the schema
schema_type (SchemaType) – The type of schema to create (currently only TABLE schemas are supported)
dynamic (bool) – Define a dynamic schema (fields list should be empty)

Returns:

A schema definition built from the supplied fields

Return type:

SchemaDefinition

tracdap.rt.api.define_struct(struct_type)¶

Define a STRUCT_SCHEMA from a Python class, which can be either a dataclass or a Pydantic model.

TRAC performs validation on the supplied type and then creates a matching SchemaDefinition. To create model inputs and outputs for this schema, use define_input() and define_output(). To access these inputs and outputs at runtime, use get_struct() and put_struct().

Parameters:: struct_type (type) – The dataclass or Pydantic model type to build a schema for
Returns:: A schema definition built from the supplied Python type
Return type:: SchemaDefinition

tracdap.rt.api.define_table(*fields)¶

Define a :py:attr:`TABLE_SCHEMA <tracdap.rt.metadata.SchemaType.TABLE_SCHEMA>`from a list of fields

TRAC performs validation on the supplied fields and then creates a matching SchemaDefinition. To create model inputs and outputs for this schema, use define_input() and define_output().

Parameters:: fields (FieldSchema | List[FieldSchema]) – The list of fields to include in the schema
Returns:: A schema definition built from the supplied fields
Return type:: SchemaDefinition

tracdap.rt.api.load_resource(package, resource_file)¶

Load a binary resource from the model repository

Resources are files included in the Python package structure of the model repository. This method loads a binary resource file into memory as a bytes object.

Note

Checking large resource files into the model repository has a significant performance impact. For this reason, TRAC enforces a limit on the size of resource files. In production deployments of TRAC the resource size limit is set by the system administrator. The default limit is 256 KB. Larger files can be passed into a model as model inputs.

Parameters:

package (ModuleType | str) – The package to load resources from (either a module object or the package name)
resource_file (str) – The name of the resource file to load

Returns:

The loaded resource as a bytes object

Return type:

bytes

tracdap.rt.api.load_resource_stream(package, resource_file)¶

Load a binary resource from the model repository as a readable stream

Resources are files included in the Python package structure of the model repository. This method makes a binary resource available as a readable byte stream. The stream can only be used in a Python with block.

Note

Parameters:

package (ModuleType | str) – The package to load resources from (either a module object or the package name)
resource_file (str) – The name of the resource file to load

Returns:

A readable binary stream for the resource

Return type:

BinaryIO

tracdap.rt.api.load_schema(package, schema_file, schema_type=SchemaType.TABLE)¶

Load a SchemaDefinition from a CSV file in the model package

The 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 a ModelInputSchema or ModelOutputSchema.

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:

SchemaDefinition

tracdap.rt.api.load_text_resource(package, resource_file, encoding='utf-8')¶

Load a text resource from the model repository

Resources are files included in the Python package structure of the model repository. This method loads a text resource file into memory as a str object. The resource is loaded with utf-8 encoding by default, different encodings can be specified using the encoding parameter.

Note

Parameters:

package (ModuleType | str) – The package to load resources from (either a module object or the package name)
resource_file (str) – The name of the resource file to load
encoding (str) – Resource encoding (default: utf-8)

Returns:

The loaded resource, as a string if text = True, otherwise as bytes

Return type:

bytes

tracdap.rt.api.load_text_resource_stream(package, resource_file, encoding='utf-8')¶

Load a text resource from the model repository as a text stream

Resources are files included in the Python package structure of the model repository. This method makes a binary resource available as a readable text stream. The resource is loaded with utf-8 encoding by default, different encodings can be specified using the encoding parameter. The stream can only be used in a Python with block.

Note

Parameters:

package (ModuleType | str) – The package to load resources from (either a module object or the package name)
resource_file (str) – The name of the resource file to load
encoding (str) – Resource encoding (default: utf-8)

Returns:

A readable text stream for the resource

Return type:

TextIO

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

tracdap.rt.api.STRUCT_TYPE¶: Template type for use with STRUCT data objects, which can be either Python dataclasses or Pydantic models