`tlc.core.schema`¶

Defines Schema, which is a class for describing atomic or (possibly nested) composite structures

Module Contents¶

Classes¶

Class	Description
`MapElement`	Defines a single item in a value map.
`ScalarValue`	Describes a scalar value in a schema
`BoolValue`	Describes a scalar boolean value
`NumericValue`	Describes a scalar numeric value
`Float32Value`	A numeric value with type ‘float32’
`Float64Value`	A numeric value with type ‘float64’
`Uint8Value`	A numeric value with type ‘uint8’
`Int8Value`	A numeric value with type ‘int8’
`Uint16Value`	A numeric value with type ‘uint16’
`Int16Value`	A numeric value with type ‘int16’
`Uint32Value`	A numeric value with type ‘uint32’
`Int32Value`	A numeric value with type ‘int32’
`Uint64Value`	A numeric value with type ‘uint64’
`Int64Value`	A numeric value with type ‘int64’
`TimestampValue`	A timestamp value counting the number of ‘unit’s since epoch
`DimensionNumericValue`	Describes a scalar numeric value which is a dimension size within a property
`StringValue`	Describes a string value
`UrlStringValue`	Describes a generic URL string value
`ImageUrlStringValue`	Describes a Image URL string value
`SegmentationUrlStringValue`	Describes a Segmentation URL string value
`SegmentationMaskUrlStringValue`	Describes a Segmentation Mask URL string value
`DatetimeStringValue`	Describes a date-time string value
`ObjectTypeStringValue`	A string containing an object type
`FolderUrlStringValue`	Describes a generic URL string value
`TensorUrlStringValue`	Describes a URL string value pointing to a tensor
`DictValue`	Describes a value which consists of an anonymous, free-form dictionary
`BytesStringValue`	Describes a binary value utf-8 encoded as a string
`InstanceSegmentationRLEBytesStringValue`	Describes a binary value encoded as a run-length encoding
`Schema`	A schema is a recursive structure which defines the layout of an object. It defines what elements the object consists of, which must be either
`NoneSchema`	A schema that encodes a None value

API¶

class MapElement( internal_name: str = '', display_name: str = '', description: str = '', display_color: str = '', url: str = '', )¶

Bases: dict

Defines a single item in a value map.

Initialize self. See help(type(self)) for accurate signature.

property internal_name: str¶

property display_name: str¶

property description: str¶

property display_color: str¶

property url: str¶

to_minimal_dict( include_all: bool, ) → dict[str, Any]¶: Add a minimal representation of this object to a dictionary for subsequent serialization to JSON

static from_any( any_map_element: Any, ) → MapElement¶: Creates a MapElement object and populates it from an anonymous, possibly sparse object

class ScalarValue( value_type: str = _DEFAULT_SCALAR_VALUE_TYPE, default_value: Any = None, )¶

Describes a scalar value in a schema

to_minimal_dict( include_all: bool, ) → dict[str, Any]¶: Add a minimal representation of this object to a dictionary for subsequent serialization to JSON

static from_any( any_value: Any, ) → ScalarValue¶: Create and populate a ScalarValue (or one of the derived classes) given an anonymous, potentially sparse object

static from_value( value: Any, ) → ScalarValue¶

Create a scalar value from a Python value.

Parameters:: value – The value to create a ScalarValue from
Returns:: A ScalarValue (or one it the derived classes) representing the value

property default_value: Any¶

class BoolValue( default_value: bool | None = None, )¶

Bases: tlc.core.schema.ScalarValue

Describes a scalar boolean value

static from_any( any_value: Any, ) → BoolValue¶: Create and populate a BoolValue object given an anonymous, potentially sparse object

class NumericValue( value_type: str = _DEFAULT_SCALAR_VALUE_TYPE, value_min: float | int | None = None, value_max: float | int | None = None, enforce_min: bool = False, enforce_max: bool = False, value_step: float = 0, number_role: str = '', unit: str = '', value_map: dict[float, MapElement] | None = None, default_value: int | float | None = None, )¶

Bases: tlc.core.schema.ScalarValue

Describes a scalar numeric value

to_minimal_dict( include_all: bool, ) → dict[str, Any]¶: Add a minimal representation of this object to a dictionary for subsequent serialization to JSON

static from_any( any_value: Any, ) → NumericValue¶: Create and populate a NumericValue object given an anonymous, potentially sparse object

static from_value( value: Any, ) → NumericValue¶

Create a numeric value from a Python value.

Parameters:: value – The value to create a NumericValue from
Returns:: A NumericValue (or one it the derived classes) representing the value

class Float32Value( value_min: float | None = None, value_max: float | None = None, enforce_min: bool = False, enforce_max: bool = False, value_step: float = 0, number_role: str = '', unit: str = '', value_map: dict[float, MapElement] | None = None, default_value: float | None = None, )¶

Bases: tlc.core.schema.NumericValue

A numeric value with type ‘float32’

class Float64Value( value_min: float | None = None, value_max: float | None = None, enforce_min: bool = False, enforce_max: bool = False, value_step: float = 0, number_role: str = '', unit: str = '', value_map: dict[float, MapElement] | None = None, default_value: float | None = None, )¶

Bases: tlc.core.schema.NumericValue

A numeric value with type ‘float64’

class Uint8Value( value_min: float | None = None, value_max: float | None = None, enforce_min: bool = False, enforce_max: bool = False, value_step: float = 0, number_role: str = '', unit: str = '', value_map: dict[float, MapElement] | None = None, default_value: int | None = None, )¶

Bases: tlc.core.schema.NumericValue

A numeric value with type ‘uint8’

class Int8Value( value_min: float | None = None, value_max: float | None = None, enforce_min: bool = False, enforce_max: bool = False, value_step: float = 0, number_role: str = '', unit: str = '', value_map: dict[float, MapElement] | None = None, default_value: int | None = None, )¶

Bases: tlc.core.schema.NumericValue

A numeric value with type ‘int8’

class Uint16Value( value_min: float | None = None, value_max: float | None = None, enforce_min: bool = False, enforce_max: bool = False, value_step: float = 0, number_role: str = '', unit: str = '', value_map: dict[float, MapElement] | None = None, default_value: int | None = None, )¶

Bases: tlc.core.schema.NumericValue

A numeric value with type ‘uint16’

class Int16Value( value_min: float | None = None, value_max: float | None = None, enforce_min: bool = False, enforce_max: bool = False, value_step: float = 0, number_role: str = '', unit: str = '', value_map: dict[float, MapElement] | None = None, default_value: int | None = None, )¶

Bases: tlc.core.schema.NumericValue

A numeric value with type ‘int16’

class Uint32Value( value_min: float | None = None, value_max: float | None = None, enforce_min: bool = False, enforce_max: bool = False, value_step: float = 0, number_role: str = '', unit: str = '', value_map: dict[float, MapElement] | None = None, default_value: int | None = None, )¶

Bases: tlc.core.schema.NumericValue

A numeric value with type ‘uint32’

class Int32Value( value_min: int | None = None, value_max: int | None = None, enforce_min: bool = False, enforce_max: bool = False, value_step: float = 0, number_role: str = '', unit: str = '', value_map: dict[float, MapElement] | None = None, default_value: int | None = None, )¶

Bases: tlc.core.schema.NumericValue

A numeric value with type ‘int32’

class Uint64Value( value_min: float | None = None, value_max: float | None = None, enforce_min: bool = False, enforce_max: bool = False, value_step: float = 0, number_role: str = '', unit: str = '', value_map: dict[float, MapElement] | None = None, default_value: int | None = None, )¶

Bases: tlc.core.schema.NumericValue

A numeric value with type ‘uint64’

class Int64Value( value_min: float | None = None, value_max: float | None = None, enforce_min: bool = False, enforce_max: bool = False, value_step: float = 0, number_role: str = '', unit: str = '', value_map: dict[float, MapElement] | None = None, default_value: int | None = None, )¶

Bases: tlc.core.schema.NumericValue

A numeric value with type ‘int64’

class TimestampValue( value_min: float | None = None, value_max: float | None = None, enforce_min: bool = False, enforce_max: bool = False, value_step: float = 0, number_role: str = NUMBER_ROLE_TIMESTAMP, unit: str = 'ms', value_map: dict[float, MapElement] | None = None, default_value: int | None = None, )¶

Bases: tlc.core.schema.Int64Value

A timestamp value counting the number of ‘unit’s since epoch

Stores the value as an ‘int64’

Defaults to milliseconds resolution

class DimensionNumericValue( value_min: int = 0, value_max: int | None = None, enforce_min: bool = True, enforce_max: bool = False, display_name: str = '', description: str = '', number_role: str = '', unit: str = '', value_map: dict[float, MapElement] | None = None, sample_type: str = '', default_value: int | None = None, )¶

Bases: tlc.core.schema.Int32Value

Describes a scalar numeric value which is a dimension size within a property

classmethod fixed_size( size: int, ) → DimensionNumericValue¶: Create a fixed size dimension value

to_minimal_dict( include_all: bool, ) → dict[str, Any]¶: Add a minimal representation of this object to a dictionary for subsequent serialization to JSON

static dimension_numeric_value_from_any( this_property: Any, ) → DimensionNumericValue | None¶: Creates a DimensionNumericValue object and populates it from an anonymous, possibly sparse object

is_fixed_size() → bool¶

class StringValue( string_role: str = '', default_value: str | None = None, )¶

Bases: tlc.core.schema.ScalarValue

Describes a string value

to_minimal_dict( include_all: bool, ) → dict[str, Any]¶: Add a minimal representation of this object to a dictionary for subsequent serialization to JSON

static from_any( any_value: Any, ) → StringValue¶: Create and populate a StringValue object given an anonymous, potentially sparse object

class UrlStringValue( url_string_icon: str = '', default_value: str | None = None, )¶

Bases: tlc.core.schema.StringValue

Describes a generic URL string value

class ImageUrlStringValue( default_value: str | None = None, )¶

Bases: tlc.core.schema.UrlStringValue

Describes a Image URL string value

class SegmentationUrlStringValue( default_value: str | None = None, map: dict[float, MapElement] | dict[float, str] | None = None, )¶

Bases: tlc.core.schema.UrlStringValue

Describes a Segmentation URL string value

to_minimal_dict( include_all: bool, ) → dict[str, Any]¶

static from_any( any_value: Any, ) → SegmentationUrlStringValue¶: Create and populate a SegmentationUrlStringValue object given an anonymous, potentially sparse object

class SegmentationMaskUrlStringValue( default_value: str | None = None, map: dict[float, MapElement] | dict[float, str] | None = None, )¶

Bases: tlc.core.schema.SegmentationUrlStringValue

Describes a Segmentation Mask URL string value

static from_any( any_value: Any, ) → SegmentationMaskUrlStringValue¶: Create and populate a SegmentationMaskUrlStringValue object given an anonymous, potentially sparse object

class DatetimeStringValue( default_value: str | None = None, )¶

Bases: tlc.core.schema.StringValue

Describes a date-time string value

class ObjectTypeStringValue( default_value: str | None = None, )¶

Bases: tlc.core.schema.StringValue

A string containing an object type

class FolderUrlStringValue( default_value: str | None = None, )¶

Bases: tlc.core.schema.StringValue

Describes a generic URL string value

class TensorUrlStringValue( default_value: str | None = None, )¶

Bases: tlc.core.schema.UrlStringValue

Describes a URL string value pointing to a tensor

class DictValue( default_value: dict = {}, )¶

Bases: tlc.core.schema.ScalarValue

Describes a value which consists of an anonymous, free-form dictionary

static from_any( _: Any, ) → DictValue¶

property default_value: dict¶

class BytesStringValue( default_value: str | None = None, )¶

Bases: tlc.core.schema.StringValue

Describes a binary value utf-8 encoded as a string

to_minimal_dict( include_all: bool, ) → dict[str, Any]¶

class InstanceSegmentationRLEBytesStringValue( polygons_are_relative: bool = False, default_value: str | None = None, )¶

Bases: tlc.core.schema.BytesStringValue

Describes a binary value encoded as a run-length encoding

to_minimal_dict( include_all: bool, ) → dict[str, Any]¶

static from_any( any_value: Any, ) → InstanceSegmentationRLEBytesStringValue¶

class Schema( display_name: str = '', description: str = '', writable: bool = True, display_importance: float = 0, value: ScalarValue | None = None, values: dict[str, Schema] | None = None, composite_role: str = '', display_color: str = '', swap_group: str = '', computable: bool = True, sample_type: str | None = None, transient: bool = False, default_visible: bool = True, size0: DimensionNumericValue | None = None, size1: DimensionNumericValue | None = None, size2: DimensionNumericValue | None = None, size3: DimensionNumericValue | None = None, size4: DimensionNumericValue | None = None, size5: DimensionNumericValue | None = None, )¶

A schema is a recursive structure which defines the layout of an object. It defines what elements the object consists of, which must be either

Atomic type (with optional metadata, e.g. value range, unit, etc.) OR
Composite contents (a list of schemas describing the sub-object)

In addition, it defines HOW MANY of these scalar or composite elements exist, in the form of up to six-dimensions which can each be described separately and be of fixed or variable lengths. The default size of dimensions is 1, describing a scalar value.

Schemas are used for

Defining the layout of Objects (as reported by e.g. “MyObject.schema”)
In the case of Tables: defining the common layout of all table rows (as reported by e.g “MyTableObject.schema.values[“rows”])

In the case where a schema defines a “top-level” object, it will always have a ‘values’ attribute (since it is always a composite object, and does not comprise only a single atomic value).

is_empty() → bool¶

last_dimension() → DimensionNumericValue | None¶: Return the last (outermost) dimension of the Schema

to_minimal_dict( include_all: bool, ) → dict[str, Any]¶: Add a minimal representation of this object to a dictionary for subsequent serialization to JSON

add_sub_schema( name: str, schema: Schema, ) → None¶: Adds a Schema as a sub-property within this Schema (i.e. into the ‘values’ collection)

add_sub_value( name: str, value: ScalarValue, writable: bool = True, computable: bool = True, ) → None¶: Adds a scalar value as a sub-property within this Schema (i.e. into the ‘values’ collection)

to_json() → str¶

Writes the contents of this schema to a JSON string. Note that

Defaults values are omitted for brevity
Schemas might be recursive

static from_any( any_object: Any, ) → Schema¶: Returns a Schema object which has been populated from a serialized (possibly sparse) object

static from_json( json_string: str, ) → Schema¶: Returns a Schema object which has been populated from a JSON string

consider_override_from( override_schema: Schema | Mapping[str, object] | None, ) → Schema¶: Selectively overwrites columns within this Schema according to the columns defined in another Schema.

does_object_match( _object: Any, ) → bool¶

Checks whether a schema matches an example object.

This requires exact 1:1 mapping between attributes in the object and the schema (including recursively). This means no attributes can be missing, nor can there be any additional attributes only present in the object.

is_fixed_size() → bool¶

Return whether the schema has fixed size.

This requires all dimensions to be fixed size.

is_scalar() → bool¶

Return whether the schema is a scalar value

Sizes are required to be set in increasing dimensions without gaps and no size is treated like a scalar.

is_atomic() → bool¶

Return whether the schema is atomic, i.e. has a single value.

The opposite of is_composite.

Returns:: Whether the schema is atomic

is_composite() → bool¶

Return whether the schema is composite, i.e. has multiple values.

The opposite of is_atomic.

Returns:: Whether the schema is composite

property sample_type_object: SampleType¶

row_from_sample( sample: Any, ) → Any¶

sample_from_row( row: Any, ) → Any¶

classmethod from_structure( structure: tlc.client.sample_type._SampleTypeStructure, ) → Schema¶

Creates a schema from a structure.

Parameters:: structure – The structure to create a schema from
Returns:: The schema

classmethod from_sample( sample: Any, ) → Schema¶

Creates a schema describing the provided sample.

Parameters:: sample – The sample to create a schema from
Returns:: The schema

push_dim( dim: DimensionNumericValue | None = None, ) → DimensionNumericValue | None¶

Inserts dim as size0 and shifts all other dimensions right. (size1 becomes size0, size2 becomes size1).

Parameters:: dim – The dimension to insert as size0
Returns:: The old size5

pop_dim() → DimensionNumericValue | None¶

Sets size5 to None and shifts all other dimensions left. (size5 becomes size4, size4 becomes size3, etc.).

Returns:: The old size0

add_sample_weight( hidden: bool = True, default_value: float = 1.0, ) → None¶

Adds a sample weight column to the schema.

Parameters:: hidden – Whether the column should be hidden

set_writable_flag_recursively( writable: bool, ) → None¶

Sets the writable flag recursively.

Parameters:: writable – Whether the schema is writable

class NoneSchema¶

Bases: tlc.core.schema.Schema

A schema that encodes a None value

It is not a valid Schema as it has neither value nor values. It is used to encode override schemas that remove sub schemas.

Example:

override_schema = { "values": { "column_to_remove": None }}
# or equivalently
override_schema = { "values": { "column_to_remove": NoneSchema()}}

to_json() → str¶

to_minimal_dict( include_all: bool, ) → dict[str, Any]¶

tlc.core.schema¶

Module Contents¶

Classes¶

API¶

`tlc.core.schema`¶