ts_ids_core.annotations module¶

Type hints used throughout ts-ids-core.

Abstract¶

An abstract field is meant to be overridden in a child class which inherits from a base class.

For example, the TetraDataSchema class contains the Abstract field ids_type: each individual IDS which inherits from TetraDataSchema is meant to override ids_type with a constant value specific to that IDS. An UnimplementedAbstractField error will be raised if abstract fields are not implemented before trying to use them.

Abstract fields can be used in an IdsElement class definition like foo: Abstract[str] = IdsField().

alias of Annotated[T, <ts_ids_core.annotations.AbstractAnnotation object at 0x7f8d12fa7f10>]

class AbstractAnnotation[source]¶

Bases: object

Annotation metadata indicating that a field in a Programmatic IDS class is abstract.

This means it is a field which should be overridden in a child class which inherits from the base class where it appears.

DecimalNumber¶

A Decimal type whose JSON schema type is number and whose instance’s field value when serialized to JSON is a float value. This type preserves the standard python decimal.Decimal type when not serializing to JSON. Example:

class Model(IdsElement):
    foo: DecimalNumber

model = Model(foo="1.500")

assert model.model_json_schema() == {
       "additionalProperties": False,
       "properties": {"foo": {"type": "number"}},
       "type": "object",
   }
assert model.model_dump() == {"foo": Decimal("1.500")}
assert model.model_dump_json() == '{"foo":1.5}'

alias of Annotated[Decimal, <ts_ids_core.annotations._DecimalNumber object at 0x7f8d12f680d0>, PlainSerializer(func=~ts_ids_core.annotations., return_type=float, when_used=json)]

DecimalString¶

A Decimal type whose JSON schema type is string and whose instance’s field value when serialized to JSON is a string value. This type preserves the standard python decimal.Decimal type when not serializing to JSON. Example:

class Model(IdsElement):
    foo: DecimalString

model = Model(foo="1.500")

assert model.model_json_schema() == {
       "additionalProperties": False,
       "properties": {"foo": {"type": "string"}},
       "type": "object",
   }
assert model.model_dump() == {"foo": Decimal("1.500")}
assert model.model_dump_json() == '{"foo": "1.500"}'

alias of Annotated[Decimal, <ts_ids_core.annotations._DecimalString object at 0x7f8d12f68940>, PlainSerializer(func=~ts_ids_core.annotations., return_type=str, when_used=json)]

class ForeignKey(ids_field_arg: str = 'primary_key', pk_reference_field: str = '@foreign_key')[source]¶

Bases: object

Class to initialize as metadata in Annotated types to designate the type a foreign key

ids_field_arg: str = 'primary_key'¶

pk_reference_field: str = '@foreign_key'¶

IntStr¶

Copied from pydantic.typing because they are not import-able.

alias of int | str

Nullable = typing.Optional¶: A type annotation to explicitly describe a field as nullable (i.e. the field can be a given type or None). This is equivalent to typing.Optional but does not conflict with required and optional field terminology and is consistent with TetraScience terminology. A field can be optional in the schema but also nullable.

NullableBoolean¶

A type annotation to denote a field can be either a boolean or None.

alias of bool | None

NullableInt¶

NullableInt indicates “the value is likely an integer, but since Athena doesn’t distinguish between integers and floats, we’ll specify the value as the more-permissive float type.”

alias of float | None

NullableNumber¶

A type annotation to denote a field can be either a float or None.

alias of float | None

NullableString¶

A type annotation to denote a field can be either a string or None.

alias of str | None

class PrimaryKey[source]¶

Bases: object

Class to initialize as metadata in Annotated types to designate the type a primary key

pk_metadata_field = '@primary_key'¶

Required¶

Define a field as Required[<type>], for example Required[str] to indicate that this IDS field should be “required” when exported to JSON Schema

alias of Annotated[T, <ts_ids_core.annotations.RequiredAnnotation object at 0x7f8d12fa79a0>]

class RequiredAnnotation[source]¶

Bases: object

Annotation metadata indicating that a field in a Programmatic IDS class is required.

UUIDForeignKey¶

A UUID foreign key.

Example class using this type and UUIDPrimaryKey:

class Method(IdsElement):
    pk: UUIDPrimaryKey

class Result(IdsElement):
    fk_method: UUIDForeignKey = IdsField(
        primary_key="/properties/methods/items/properties/pk"
    )


class Model(TetraDataSchema):
    schema_extra_metadata: ClassVar[SchemaExtraMetadataType] = {
        "$id": "",
        "$schema": "http://json-schema.org/draft-07/schema#",
    }
    ids_type: Required[Literal["demo"]] = IdsField(
        default="demo", alias="@idsType"
    )
    ids_version: Required[Literal["v1.0.0"]] = IdsField(
        default="v1.0.0", alias="@idsVersion"
    )
    ids_namespace: Required[Literal["common"]] = IdsField(
        default="common", alias="@idsNamespace"
    )
    methods: List[Method]
    results: List[Result]

A UUIDForeignKey must be defined with a primary_key passed to IdsField. This is a JSON pointer which points to the location of the primary key in the JSON schema, and this is validated when IdsSchema or TetraDataSchema classes are defined. This validation will only run on classes inheriting from IdsSchema or TetraDataSchema which do not contain any abstract fields (fields annotated with Abstract), i.e. only complete top-level schemas include this validation of foreign keys.

alias of Annotated[str, BeforeValidator(func=validate_uuid, json_schema_input_type=PydanticUndefined), ForeignKey(ids_field_arg=primary_key, pk_reference_field=@foreign_key), <ts_ids_core.annotations.RequiredAnnotation object at 0x7f8d12fa79a0>]

UUIDPrimaryKey¶

A UUID primary key.

See UUIDForeignKey for example usage.

alias of Annotated[str, BeforeValidator(func=validate_uuid, json_schema_input_type=PydanticUndefined), <ts_ids_core.annotations.PrimaryKey object at 0x7f8d12f58f70>, <ts_ids_core.annotations.RequiredAnnotation object at 0x7f8d12fa79a0>]

UUIDStr¶

A string representation of a UUID.

Fields of this type are exported as strings when calling IdsElement.model_dump().

This means these UUID fields are compatible with jsonschema validation in Python, where UUID fields need to validate against the "string" JSON Schema type.

UUID fields could use uuid.UUID as their field type, which has similar Pydantic validation, but those fields are exported as uuid.UUID instances when calling IdsElement.dict which is not compatible with jsonschema validation.

alias of Annotated[str, BeforeValidator(func=validate_uuid, json_schema_input_type=PydanticUndefined)]

UUIDValidator = BeforeValidator(func=<function validate_uuid>, json_schema_input_type=PydanticUndefined)¶

UUIDValidator is a Pydantic BeforeValidator to add as metadata to an Annotated string type. This validator will validate that strings are valid UUIDs and will convert UUID instances to strings.

class Model(IdsElement):
    uuid_field: Annotated[str, UUIDValidator]

uuid_instance = UUID('d7696855-efc7-42eb-ac58-6cc588bf3c5c')
uuid_string = 'd7696855-efc7-42eb-ac58-6cc588bf3c5c'
invalid_uuid_string = "invalid"

assert Model(uuid_field=uuid_instance).uuid_field == 'd7696855-efc7-42eb-ac58-6cc588bf3c5c'
assert Model(uuid_field=uuid_string).uuid_field == 'd7696855-efc7-42eb-ac58-6cc588bf3c5c'

Model(uuid_field=uuid_string)
"""
Value error, badly formed hexadecimal UUID string [type=value_error, input_value='invalid', input_type=str]
"""

fixed_length(length: int) → Len[source]¶

Annotation metadata meaning a sequence has a fixed length.

For example, to define a list of strings of length 2: my_array: Annotated[List[str], fixed_length(2)]

resolve_length_annotation_metadata(annotations: Iterable[Any]) → Len | None[source]¶

Find the min and max length of a sequence from its Annotated metadata

If there is duplication, the later elements take precedence, to match Pydantic. For example, [Len(2, 2), MinLen(1)] returns Len(1, 2), the min_length of 2 in the first element is overwritten by 1 from the second element.

validate_uuid(value: Any) → Annotated[str, BeforeValidator(func=validate_uuid, json_schema_input_type=PydanticUndefined)][source]¶: Validate that the input value is a uuid.UUID or a valid str representation of a UUID.