tlc.core.addressable_object¶

Persistent 3LC object with URL, write-back, and telemetry.

Module Contents¶

Classes¶

Class

Description

AddressableObject

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

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: tlcurl.url.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 | 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.

classmethod type_name() → str¶

The type name of the class, used to resolve factory methods.

AddressableObject itself reports as "Object" for backward compatibility with serialized JSON. Subclasses inherit the default cls.__name__ behavior from BaseObject.

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.