tracdap.rt.metadata.type

Module Contents

Classes

ArrayValue

An array value holds an array of other Values.

BasicType

Basic types provide the set of core types available in the TRAC type system.

DateValue

Represent a date value.

DatetimeValue

Represent a date-time value.

DecimalValue

Represent a decimal value.

MapValue

A map value holds a map of string keys to other Values.

TypeDescriptor

A type descriptor describes a data type used in the TRAC platform.

Value

A value expressed in the TRAC type system.

class tracdap.rt.metadata.type.ArrayValue

An array value holds an array of other Values.

All items in an array must have the same type.

See also

ARRAY

items

items

Type

List[Value]

class tracdap.rt.metadata.type.BasicType

Bases: enum.Enum

Basic types provide the set of core types available in the TRAC type system.

ARRAY = [8, 'An array of values, which may be primitive or composite values.\n    \n    All items in an...
BASIC_TYPE_NOT_SET = [0]
BOOLEAN = [1, 'A true/false value']
DATE = [6, 'A date value.\n    \n    Dates do not take any account of time zones or offsets from UTC.\n    ']
DATETIME = [7, 'A date-time value.\n    \n    Date-time values may be expressed with an offset from UTC, as...
DECIMAL = [5, 'A fixed-point decimal value with known precision and scale.\n    \n    The available...
FLOAT = [3, "64 bit signed floating point number (referred to as 'double' in many languages)"]
INTEGER = [2, '64 bit signed integer']
MAP = [9, 'An key-value map with string keys, values may be primitive or composite values.\n    \n   ...
STRING = [4, 'UTF encoded string value of arbitrary length.\n    \n    The encoding used (e.g. UTF-8,...
class tracdap.rt.metadata.type.DateValue

Represent a date value.

Dates are represented as strings in ISO 8601 format.

See also

DATE

isoDate

isoDate

Type

str

class tracdap.rt.metadata.type.DatetimeValue

Represent a date-time value.

Date-times are represented as strings in ISO 8601 format.

See also

DATETIME

isoDatetime

isoDatetime

Type

str

class tracdap.rt.metadata.type.DecimalValue

Represent a decimal value.

See also

DECIMAL

decimal

decimal

Type

str

class tracdap.rt.metadata.type.MapValue

A map value holds a map of string keys to other Values.

Maps may be uniform (holding all the same value type) or non-uniform (holding mixed value types) depending on the type descriptor of the Value that contains them.

See also

MAP, TypeDescriptor

entries

entries

Type

Dict[str, Value]

class tracdap.rt.metadata.type.TypeDescriptor

A type descriptor describes a data type used in the TRAC platform.

For complex types, the descriptor holds a full type description. E.g. for array types, the type being held in the array is described. At a later point, precision fields may be introduced for decimals, or field types for structs.

arrayType

For array types only, describe the type contained in the array.

Type

Optional[TypeDescriptor]

basicType

The basic type being described.

Type

BasicType

mapType

For map types only, describe the type contained in the map.

To describe a uniform map the mapType descriptor must be set to a valid type descriptor, in this case all values in the map must match the type of the descriptor. If mapType is not set or is present but has basicType = BASIC_TYPE_NOT_SET then the map is non-uniform, values must be inspected individually to determine their type.

Type

Optional[TypeDescriptor]

class tracdap.rt.metadata.type.Value

A value expressed in the TRAC type system.

A value can express a primitive value, or a composite value such as an array. Arbitrary nesting of composite types is permitted, although most functions will limit the set of acceptable types during validation.

Values include a type descriptor field. For primitive values the type descriptor is optional. For composite types the root value must include a full valid type descriptor, i.e. a descriptor that goes down to the leaf types. Sub-values in a composite type are free to omit the type descriptor, even if there are multiple levels of nesting, however any extra descriptors that are provided must also be full and valid.

TRAC will always provide values with the type descriptors “normalised”. This means that a root value will always have a type descriptor (even if it is a primitive type) and sub-values will never have a type descriptor. It is not necessary or preferred for application code to send values to TRAC with normalised type descriptors, TRAC will always perform normalisation.

See also

TypeDescriptor

arrayValue

An array of Values.

All items in an array must have the same type.

See also

ARRAY

Type

Optional[ArrayValue]

booleanValue

A boolean value.

Represented natively in both protobuf and JSON.

Type

Optional[bool]

dateValue

A date value.

See also

DATE, DateValue

Type

Optional[DateValue]

datetimeValue

A date-time value.

Date-times are represented as strings in ISO 8601 format.

Date-time values support nanosecond precision, however in practice the available precision may be less than this. In particular, tag attributes are always stored at microsecond precision. Values passed into models or used in application code will be limited to the precision supported by date-time types in their own coding language.

Time zone offsets are supported as described in ISO 8601. Date-time values should always include a zone offset to guarantee behaviour. If a zone offset is not supplied TRAC will normalized incoming values by applying a zone offset, currently the applied offset will be UTC.

Type

Optional[DatetimeValue]

decimalValue

A decimal value with fixed precision and scale.

See also

DECIMAL

Type

Optional[DecimalValue]

floatValue

A 64-bit signed floating point value.

Represented natively in both protobuf and JSON.

Type

Optional[float]

integerValue

A 64-bit signed integer value.

Represented natively in both protobuf and JSON.

In JavaScript and JSON, native integers may be limited to less than full range of a 64 bit integer. This is because JavaScript has a single Number type that represents both integers and floats. The safe limit for integers that can be expressed without a risk of rounding in JavaScript is Number.MAX_SAFE_INTEGER.

Type

Optional[int]

mapValue

A map of string keys to Values.

Maps may be uniform (holding all the same value type) or non-uniform (holding mixed value types) depending on the type descriptor of this Value.

See also

MAP, TypeDescriptor

Type

Optional[MapValue]

stringValue

A string value.

Protobuf encodes strings as UTF-8 on the wire. String values in JSON requests are also be encoded as UTF-8 on the wire, as per RFC 8259. When reading or writing string values in application code, they will be presented in the normal encoding scheme of application’s coding language.

Type

Optional[str]

type

Type descriptor for the current value.

A type descriptor is always required for values that are the root of a composite type, otherwise it is optional.

Type

TypeDescriptor