`tlc.objects`¶

Base classes for the 3LC object hierarchy.

The four-level hierarchy Object → SerializableObject → AddressableObject → MutableObject underpins every persistable 3LC type (tables, runs, configurations, …). While most cases reach for the concrete classes (e.g. tlc.Table, tlc.Run, tlc.configuration.Configuration) directly, this module exposes the bases for completeness and for expert authors of custom serializable types.

Package Contents¶

Classes¶

Class	Description
`AddressableObject`	A 3LC object that lives at a URL and supports persistence, write-back, and telemetry.
`MutableObject`	Base class for objects that can be mutated.
`Object`	Lightweight base for all 3LC objects: type identity and init-parameter assignment.
`SerializableObject`	Adds schema, type identity, serialization versioning, and JSON serialization.
`TableRows`	An immutable access interface to the rows of a Table object

API¶

class AddressableObject( *, url: Url | None = None, created: str | None = None, init_parameters: Any = None, )¶

Bases: tlc._core.serializable_object.SerializableObject

A 3LC object that lives at a URL and supports persistence, write-back, and telemetry.

Variables:

url – The URL which this object instance was deserialized FROM, or should be serialized TO. Note that this value is NOT written to JSON, since the JSON representation could potentially be moved around (as in e.g. a file being moved to another folder).
created – The time when this object was first created.
is_url_writable – Whether the URL where the object is stored is writable.
transaction_id – The transaction associated with this object.

Parameters:

url – The URL of the object.
created – The creation time of the object.
init_parameters – A dictionary containing the initial values of the object’s properties.

absolute_url_from_relative( input_url: Url, ) → Url¶

Convert a relative URL to be absolute, given the URL of this object.

Parameters:: input_url – The relative URL to convert.
Returns:: The absolute URL.

static add_is_url_writable_property_to_schema( schema: Schema, ) → None¶

Add the ‘is_url_writable’ property to the provided schema.

Parameters:: schema – The schema to add the property to.

static add_object_created_property_to_schema( schema: Schema, ) → None¶

Add the ‘created’ property to the provided schema.

Parameters:: schema – The schema to add the property to.

static add_object_url_property_to_schema( schema: Schema, url_string_icon: str = '', ) → None¶

Add the ‘url’ property to the provided schema.

Parameters:

schema – The schema to add the property to.
url_string_icon – The icon to display next to the URL string.

copy( *, destination_url: tlc.Url | None = None, if_exists: typing.Literal[raise, rename, overwrite] = 'raise', ) → AddressableObject¶

Return a copy of this object, with the specified URL.

Parameters:

destination_url – The url to write the copy to. If not provided, a new url will be generated based on the objects own url.
if_exists – How to handle the case where the destination URL already exists.

Returns:

A copy of this object.

delete() → None¶

Delete this object from storage.

This method permanently removes the object from storage by deleting the underlying files or objects that the object’s URL points to. The object’s URL will no longer be valid after this operation.

Example:

table = Table.from_dict({"a": [1, 2, 3]})
table.write_to_url() # persist to storage
...
table.delete() # delete the backing files and objects

To delete an object by URL without loading it first, use:

Url("path/to/object").delete()

Note: This is different from Python’s del operator - del obj only removes the variable name, while obj.delete() removes the object from storage (and keeps the variable name).

ensure_fully_defined() → None¶

Make sure the internal state of the object is fully defined.

Extends SerializableObject.ensure_fully_defined() with write-back: after the schema and dependent properties are resolved, the object is persisted to its URL if appropriate.

classmethod from_url( url: Url | str, ) → AddressableObject¶

Create an AddressableObject from a URL.

Parameters:: url – The URL of the object.
Returns:: The deserialized object.

is_stale( timestamp: str | None, epsilon: float = 0.0, ) → bool¶

Indicate whether this object is stale compared to a given timestamp.

The base implementation never considers an object stale. MutableObject overrides this to compare against the last_modified property.

Parameters:

timestamp – The timestamp against which to check staleness. Can be None.
epsilon – The tolerance in seconds for staleness. If the difference between the object’s timestamp and the provided timestamp exceeds this value, the object is considered stale. Defaults to 0.0s.

Returns:

True if the object is stale, False otherwise.

relative_url_from_absolute( input_url: Url, ) → Url¶

Convert an absolute URL to be relative, given the URL of this object.

Parameters:: input_url – The absolute URL to convert.
Returns:: The relative URL.

property root_url: Url | None¶

The root URL of the object, if set.

This is a transient property that is not serialized.

Returns:: The root URL of the object, or None if not set.

property url: Url¶: The URL which this object instance was deserialized from, or should be serialized to.

write_to_url( force: bool = False, ) → Url¶

Write this object to its URL.

Parameters:: force – Whether to overwrite the object if it already exists.
Returns:: The URL where the object was written.

class MutableObject( *, url: Url | None = None, created: str | None = None, last_modified: str | None = None, init_parameters: Any = None, )¶

Bases: tlc._core.addressable_object.AddressableObject

Base class for objects that can be mutated.

MutableObject properties:

‘last_modified’: The time when this object was last modified.

The MutableObject have designated update_attribute/s methods that are meant to be used to modify the object’s attributes. Using these function to modify objects makes sure that the objects’ internal state are updated correctly, e.g. sets the ‘last_modified’ timestamp.

Directly modifying MutableObject (public) attributes from the outside using mutable_obj.attr = value or setattr(mutable_obj, "attr", value) is not recommended. But, if object attributes have to be set directly, make sure to call the update_internal_state to signal the update.

Parameters:

url – The URL of the object.
created – The creation time of the object.
init_parameters – A dictionary containing the initial values of the object’s properties.

static add_last_modified_property_to_schema( schema: Schema, description: str, ) → None¶: Add the ‘last_modified’ property to this schema

is_stale( timestamp: datetime | str | None, epsilon: float = 0.0, ) → bool¶

Indicates whether this object is stale compared to the given timestamp (using last_modified property).

The function compares the object’s last_modified timestamp with the provided timestamp. If the difference exceeds the provided epsilon value, the object is considered stale.

Parameters:

timestamp – The timestamp against which to check staleness. Can be None.
epsilon – The tolerance in seconds for staleness. If the difference between the object’s timestamp and the provided timestamp exceeds this value, the object is considered stale. Defaults to 0.0s.

Returns:

True if the object is stale, False otherwise.

Raises:

ValueError – if the timestamp is invalid.

to_json( init_level: int = 0, ) → str¶

Returns a JSON representation of this object. This will be sufficient to recreate a fully functioning clone of the object at a later time.

Note that for brevity, properties with default values are not written to the string.

touch_last_modified() → None¶

Updates the last_modified timestamp to the current UTC time.

Guarantees the timestamp strictly advances on each call: Windows clock resolution can otherwise return the same value for back-to-back calls, which would hide a mutation from polling consumers.

update( init_parameters: Mapping[str, object], ) → None¶

update_attribute( attr_name: str, value: Any, ) → None¶

Updates the given attribute with the given value.

This method will only allow modification of attributes that are defined in the object’s schema and are writeable. If the object schema is has not yet been evaluated, this method will do so. If the object does not have a Schema a ValueError will be raised.

If the attribute is modified the object’s ‘last_modified’ timestamp is updated. The internal state of the object is also updated by calling the _update_internal_state method.

Parameters:

attr_name – The name of the attribute to update.
value – The value to set.

Returns:

True if the object was changed, False otherwise.

Raises:

ValueError – if the schema is not set, or attribute name is unknown.

update_attributes( attribute_dict: Mapping[str, object], ) → None¶

Updates the object with the given attribute_name,value pairs.

If the attribute is modified the object’s ‘last_modified’ timestamp is updated. The internal state of the object is also updated by calling the update_internal_state method.

Parameters:: attribute_dict – A mapping of attribute names to values to update.
Raises:: ValueError – if the schema is not set, or attribute name is unknown.

update_internal_state( persist: bool = True, ) → None¶

Updates the internal state of the object.

Override this method to update the internal state of the object whenever attributes have been changed. This method is called by the update_attribute/s

class Object( *, init_parameters: Any = None, )¶

Lightweight base for all 3LC objects: type identity and init-parameter assignment.

This level carries no type/version fields, no schema, no URL, and no persistence logic.

Parameters:: init_parameters – A dictionary containing the initial values of the object’s properties.

initial_value( property_name: str, new_value: Any, default_value: Any = None, ) → Any¶

Return the initial value of a property.

Returns self.<property_name> if it already exists (set via init_parameters), otherwise new_value if not None, otherwise default_value. This lets every object be fully initialized through its constructor.

Parameters:

property_name – The name of the property to get the initial value for.
new_value – The value to return if self.<property_name> is not set.
default_value – The value to return if self.<property_name> is not set and new_value is None.

Returns:

The initial value of the property.

classmethod type_name() → str¶: The type name of the class, used to resolve factory methods.

class SerializableObject( *, init_parameters: Any = None, )¶

Bases: tlc._core.object.Object

Adds schema, type identity, serialization versioning, and JSON serialization.

Extends Object. This level carries no URL and no persistence logic.

Parameters:: init_parameters – A dictionary containing the initial values of the object’s properties.

ensure_complete_schema() → None¶: Make sure the schema is populated with all properties.

ensure_dependent_properties() → None¶

Make sure dependent properties are populated.

Override in subclasses to ensure the required dependent properties are populated.

ensure_fully_defined() → None¶

Make sure the internal state of the object is fully defined.

For most objects, this simply amounts to populating the schema property according to the properties which are directly present within the class.

AddressableObject overrides this with a @final version that adds write-back logic.

ensure_minimal_schema() → None¶: Make sure the schema is populated with the minimal properties.

classmethod from_dict( d: dict[str, Any], ) → SerializableObject¶

Create a SerializableObject from a dictionary containing a type field and init parameters.

This performs a type-registry lookup and calls the constructor with the dictionary as init_parameters. Use this to reconstruct inline (non-URL) objects from their serialized form.

.. note::

If the resolved type is an AddressableObject subclass, calling this method will trigger URL generation and object-registry side effects. Prefer from_url() for URL-backed objects.

Parameters:

d – A dictionary with at least a type key mapping to a registered type name.

Returns:

A fully initialized instance of the registered type.

Raises:

KeyError – If d does not contain a type key.
ValueError – If the type value is not a registered type name.

should_include_schema_in_json( _schema: Schema, ) → bool¶

Indicate whether the schema property of this object should be included when serializing to JSON.

Parameters:: _schema – The schema of the object. This is passed in to allow subclasses to make decisions based on the schema of the object, but it is not used in the base implementation.

to_json( init_level: int = 1, ) → str¶

Return a JSON representation of this object.

This will be sufficient to recreate a fully functioning clone of the object at a later time.

Note that for brevity, properties with default values are not written to the string.

Parameters:: init_level – The level of initialization to use when serializing the object. 1: Minimal schema 2: Complete schema 3: Fully defined object
Returns:: A JSON representation of this object.

class TableRows( table: Table, )¶: An immutable access interface to the rows of a Table object

tlc.objects¶

Package Contents¶

Classes¶

API¶

`tlc.objects`¶