latch.registry package

Subpackages

• latch.registry.upstream_types package
  • Submodules
  • latch.registry.upstream_types.types module
    • PrimitiveTypeBasic
      • PrimitiveTypeBasic.primitive
      • PrimitiveTypeBasic.metadata
    • PrimitiveTypeLink
      • PrimitiveTypeLink.primitive
      • PrimitiveTypeLink.experimentId
      • PrimitiveTypeLink.metadata
    • PrimitiveTypeEnum
      • PrimitiveTypeEnum.primitive
      • PrimitiveTypeEnum.members
      • PrimitiveTypeEnum.metadata
    • UnionType
      • UnionType.union
    • ArrayType
      • ArrayType.array
    • DBType
      • DBType.type
      • DBType.allowEmpty
  • latch.registry.upstream_types.values module
    • InvalidValue
      • InvalidValue.rawValue
      • InvalidValue.valid
    • PrimitiveStringValueValid
      • PrimitiveStringValueValid.value
      • PrimitiveStringValueValid.valid
    • PrimitiveNumberValueValid
      • PrimitiveNumberValueValid.value
      • PrimitiveNumberValueValid.valid
    • PrimitiveNullValueValid
      • PrimitiveNullValueValid.value
      • PrimitiveNullValueValid.valid
    • PrimitiveBooleanValueValid
      • PrimitiveBooleanValueValid.value
      • PrimitiveBooleanValueValid.valid
    • BlobValue
      • BlobValue.ldataNodeId
    • PrimitiveBlobValueValid
      • PrimitiveBlobValueValid.value
      • PrimitiveBlobValueValid.valid
    • LinkValue
      • LinkValue.sampleId
    • PrimitiveLinkValueValid
      • PrimitiveLinkValueValid.value
      • PrimitiveLinkValueValid.valid
    • PrimitiveEnumValueValid
      • PrimitiveEnumValueValid.value
      • PrimitiveEnumValueValid.valid
    • UnionValue
      • UnionValue.tag
      • UnionValue.value
    • EmptyCell
  • Module contents

Submodules

latch.registry.project module

class latch.registry.project.Project(id: str)

Bases: object

Registry project (folder containing tables).

list_registry_projects() is the typical way to get a Project.

id: str

Unique identifier.

load() → None

(Re-)populate this project instance’s cache.

Future calls to most getters will return immediately without making a network request.

Always makes a network request.

get_display_name(*, load_if_missing: Literal[True] = True) → str

get_display_name(*, load_if_missing: bool) → str | None

Get the display name of this project.

This is an opaque string that can contain any valid Unicode data.

Display names are not unique and must never be used as identifiers. Use id instead.

Parameters:

load_if_missing – If true, load() the display name if not in cache. If false, return None if not in cache.

Returns:

Display name.

list_tables(*, load_if_missing: Literal[True] = True) → List[Table]

list_tables(*, load_if_missing: bool) → List[Table] | None

List Registry tables contained in this project.

Parameters:

load_if_missing – If true, load() the table list if not in cache. If false, return None if not in cache.

Returns:

Tables in this project.

update(*, reload_on_commit: bool = True) → Iterator[ProjectUpdate]

Start an update transaction.

The transaction will commit when the context manager closes unless an error occurs.

No changes will occur until the transaction commits.

The transaction can be cancelled by running ProjectUpdate.clear() before closing the context manager.

Parameters:

reload_on_commit – If true, load() this project after the transaction commits.

Returns:

Context manager for the new transaction.

class latch.registry.project.ProjectUpdate(project: latch.registry.project.Project)

Bases: object

project: Project

upsert_table(display_name: str)

Creates a table.

Not idempotent. Two calls with the same args will create two tables.

Parameters:

display_name – The display name of the new table.

delete_table(id: str)

Deletes a table.

Parameters:

id – The ID of the target table.

commit() → None

Commit this project update transaction.

May be called multiple times.

All pending updates are committed with one network request.

Atomic. The entire transaction either commits or fails with an exception.

clear()

Remove pending updates.

May be called to cancel any pending updates that have not been committed.

latch.registry.record module

exception latch.registry.record.NoSuchColumnError(key: str)

Bases: KeyError

Unknown column referenced by Registry method.

Reloading the containing table might help.

key

The unknown column key.

class latch.registry.record.Record(id: str)

Bases: object

Registry record.

list_records() is the typical way to get a Record.

id: str

Unique identifier.

load() → None

(Re-)populate this record instance’s cache.

Future calls to most getters will return immediately without making a network request.

Always makes a network request.

get_table_id(*, load_if_missing: Literal[True] = True) → str

get_table_id(*, load_if_missing: bool) → str | None

Get the ID of the table that contains this record.

Parameters:

load_if_missing – If true, load() the table ID if not in cache. If false, return None if not in cache.

Returns:

ID of the Table containing this record.

get_name(*, load_if_missing: Literal[True] = True) → str

get_name(*, load_if_missing: bool) → str | None

Get the name of this record.

Names are unique within a table. Names are not globally unique. Use id if a globally unique identifier is required.

Parameters:

load_if_missing – If true, load() the name if not in cache. If false, return None if not in cache.

Returns:

Name of this record.

get_columns(*, load_if_missing: Literal[True] = True) → Dict[str, Column]

get_columns(*, load_if_missing: bool) → Dict[str, Column] | None

Get the columns of this record’s table.

Parameters:

load_if_missing – If true, load() the column list if not in cache. If false, return None if not in cache.

Returns:

Mapping between column keys and columns.

get_values(*, load_if_missing: Literal[True] = True) → Dict[str, RecordValue]

get_values(*, load_if_missing: bool) → Dict[str, RecordValue] | None

Get this record’s values.

The resulting dictionary is shared between all calls to get_values(). Make deep copies if independent mutation is desired.

Parameters:

load_if_missing – If true, load() the values if not in cache. If false, return None if not in cache.

Returns:

Mapping between column keys and the corresponding value.

latch.registry.table module

class latch.registry.table.Table(id: str)

Bases: object

Registry table. Contains records.

list_tables() is the typical way to get a Table.

id: str

Unique identifier.

load() → None

(Re-)populate this table instance’s cache.

Future calls to most getters will return immediately without making a network request.

Always makes a network request.

get_project_id(*, load_if_missing: Literal[True] = True) → str

get_project_id(*, load_if_missing: bool) → str | None

Get the ID of the project that contains this table.

Parameters:

load_if_missing – If true, load() the project ID if not in cache. If false, return None if not in cache.

Returns:

ID of the Project containing this table.

get_display_name(*, load_if_missing: Literal[True] = True) → str

get_display_name(*, load_if_missing: bool) → str | None

Get the display name of this table.

This is an opaque string that can contain any valid Unicode data.

Display names are not unique and must never be used as identifiers. Use id instead.

Parameters:

load_if_missing – If true, load() the display name if not in cache. If false, return None if not in cache.

Returns:

Display name.

get_columns(*, load_if_missing: Literal[True] = True) → Dict[str, Column]

get_columns(*, load_if_missing: bool) → Dict[str, Column] | None

Get the columns of this table.

Parameters:

load_if_missing – If true, load() the column list if not in cache. If false, return None if not in cache.

Returns:

Mapping between column keys and columns.

list_records(*, page_size: int = 100) → Iterator[Dict[str, Record]]

List Registry records contained in this table.

Parameters:

page_size – Maximum size of a page of records. The last page may be shorter than this value.

Yields:

Pages of records. Each page is a mapping between record IDs and records.

get_dataframe()

Get a pandas DataFrame of all records in this table.

Returns:

DataFrame representing all records in this table.

update(*, reload_on_commit: bool = True) → Iterator[TableUpdate]

Start an update transaction.

The transaction will commit when the context manager closes unless an error occurs.

No changes will occur until the transaction commits.

The transaction can be cancelled by running TableUpdate.clear() before closing the context manager.

Parameters:

reload_on_commit – If true, load() this table after the transaction commits.

Returns:

Context manager for the new transaction.

exception latch.registry.table.InvalidColumnTypeError(key: str, invalid_type: Type[object] | Type[str] | Type[int] | Type[float] | Type[date] | Type[datetime] | Type[bool] | Type[LatchFile] | Type[LatchDir] | Type[StrEnum] | Type[RegistryEnumDefinition] | Type[LinkedRecordType] | Type[List[LatchFile]] | Type[List[LatchDir]] | Type[List[LinkedRecordType]], msg: str)

Bases: ValueError

Failure to use an invalid column type.

key

Identifier of the invalid column.

invalid_type

Requested column type.

class latch.registry.table.TableUpdate(table: Table)

Bases: object

Ongoing Table update transaction.

Groups requested updates to commit everything together in one network request.

Transactions are atomic. The entire transaction either commits or fails with an exception.

table: Table

upsert_record_raw_unsafe(*, name: str, values: Dict[str, PrimitiveStringValueValid | InvalidValue | PrimitiveNumberValueValid | PrimitiveNullValueValid | PrimitiveBlobValueValid | PrimitiveLinkValueValid | PrimitiveEnumValueValid | PrimitiveBooleanValueValid | List[PrimitiveStringValueValid | InvalidValue | PrimitiveNumberValueValid | PrimitiveNullValueValid | PrimitiveBlobValueValid | PrimitiveLinkValueValid | PrimitiveEnumValueValid | PrimitiveBooleanValueValid | List[DBValue] | UnionValue] | UnionValue]) → None

DANGEROUSLY Update or create a record using raw values.

Values are not checked against the existing columns.

A transport error will be thrown if non-existent columns are updated.

The update will succeed if values do not match column types and future reads will produce invalid values.

Unsafe:

The value dictionary is not validated in any way. It is possible to create completely invalid record values that are not a valid Registry value of any type. Future reads will fail catastrophically when trying to parse these values.

Parameters:

• name – Target record name.

• values – Column values that to set.

upsert_record(name: str, **values: str | datetime | date | int | float | LatchFile | LatchDir | None | bool | Record | List[str | datetime | date | int | float | LatchFile | LatchDir | None | bool | Record | List[RegistryPythonValue]]) → None

Update or create a record.

A transport error will be thrown if non-existent columns are updated.

It is possible that the column definitions changed since the table was last loaded and the update will be issued with values that do not match current column types. This will succeed with no error and future reads will produce invalid values.

Parameters:

• name – Target record name.

• values – Column values to set.

delete_record(name: str) → None

Delete a record.

Parameters:

name – Target record name.

upsert_column(key: str, type: Type[str] | Type[int] | Type[float] | Type[date] | Type[datetime] | Type[bool] | Type[LatchFile] | Type[LatchDir] | Type[StrEnum] | Type[RegistryEnumDefinition] | Type[LinkedRecordType] | Type[List[LatchFile]] | Type[List[LatchDir]] | Type[List[LinkedRecordType]], *, required: bool = False)

Create a column. Support for updating columns is planned.

Parameters:

• key – Identifier of the new column.

• type –

  Type of the new column.

  Only a limited set of Python types is currently supported and will be expanded over time.

  latch.registry.types.RegistryPythonType represents the currently supported types.

• required –

  If true, records without a value for this column are considered invalid.

  Note that an explicit None value is different from a missing/empty value. None is a valid value for an Optional (nullable) column marked as required.

commit() → None

Commit this table update transaction.

May be called multiple times.

All pending updates are committed with one network request.

Atomic. The entire transaction either commits or fails with an exception.

clear()

Remove pending updates.

May be called to cancel any pending updates that have not been committed.

latch.registry.types module

class latch.registry.types.InvalidValue(raw_value: str)

Bases: object

Registry Record value that failed validation.

raw_value: str

User-provided string representation of the invalid value.

May be “” (the empty string) if the value is missing but the column is required.

class latch.registry.types.Column(key: str, type: Type[str | datetime | date | int | float | LatchFile | LatchDir | None | bool | Record | List[str | datetime | date | int | float | LatchFile | LatchDir | None | bool | Record | List[RegistryPythonValue]]] | Type[str | datetime | date | int | float | LatchFile | LatchDir | None | bool | Record | List[str | datetime | date | int | float | LatchFile | LatchDir | None | bool | Record | List[RegistryPythonValue]] | EmptyCell], upstream_type: DBType)

Bases: object

Registry Table column definition.

Table.get_columns() is the typical way to get a Column.

key: str

Unique identifier within the table. Not globally unique.

type: Type[str | datetime | date | int | float | LatchFile | LatchDir | None | bool | Record | List[str | datetime | date | int | float | LatchFile | LatchDir | None | bool | Record | List[RegistryPythonValue]]] | Type[str | datetime | date | int | float | LatchFile | LatchDir | None | bool | Record | List[str | datetime | date | int | float | LatchFile | LatchDir | None | bool | Record | List[RegistryPythonValue]] | EmptyCell]

Python equivalent of the stored column type.

upstream_type: DBType

Raw column type.

Used to convert between Python values and Registry values.

class latch.registry.types.RegistryEnumDefinition(*values: str)

Bases: Generic[RegistryEnumDefinitionArg]

class latch.registry.types.LinkedRecordType(id: str)

Bases: Generic[LinkedRecordTypeArg]

latch.registry.utils module

exception latch.registry.utils.RegistryTransformerException

Bases: ValueError

latch.registry.utils.to_python_type(registry_type: PrimitiveTypeBasic | PrimitiveTypeLink | PrimitiveTypeEnum | UnionType | ArrayType) → Type[str | datetime | date | int | float | LatchFile | LatchDir | None | bool | Record | List[str | datetime | date | int | float | LatchFile | LatchDir | None | bool | Record | List[RegistryPythonValue]]]

latch.registry.utils.to_python_literal(registry_literal: PrimitiveStringValueValid | InvalidValue | PrimitiveNumberValueValid | PrimitiveNullValueValid | PrimitiveBlobValueValid | PrimitiveLinkValueValid | PrimitiveEnumValueValid | PrimitiveBooleanValueValid | List[PrimitiveStringValueValid | InvalidValue | PrimitiveNumberValueValid | PrimitiveNullValueValid | PrimitiveBlobValueValid | PrimitiveLinkValueValid | PrimitiveEnumValueValid | PrimitiveBooleanValueValid | List[DBValue] | UnionValue] | UnionValue, registry_type: PrimitiveTypeBasic | PrimitiveTypeLink | PrimitiveTypeEnum | UnionType | ArrayType)

latch.registry.utils.to_registry_literal(python_literal, registry_type: PrimitiveTypeBasic | PrimitiveTypeLink | PrimitiveTypeEnum | UnionType | ArrayType) → PrimitiveStringValueValid | InvalidValue | PrimitiveNumberValueValid | PrimitiveNullValueValid | PrimitiveBlobValueValid | PrimitiveLinkValueValid | PrimitiveEnumValueValid | PrimitiveBooleanValueValid | List[PrimitiveStringValueValid | InvalidValue | PrimitiveNumberValueValid | PrimitiveNullValueValid | PrimitiveBlobValueValid | PrimitiveLinkValueValid | PrimitiveEnumValueValid | PrimitiveBooleanValueValid | List[DBValue] | UnionValue] | UnionValue

latch.registry.utils.get_blob_nodetype(registry_type: PrimitiveTypeBasic | PrimitiveTypeLink | PrimitiveTypeEnum | UnionType | ArrayType) → Type[LatchFile] | Type[LatchDir]

Module contents