Base class for all 3LC objects

Module Contents#





The base class for all 3LC objects.


class tlc.core.object.Object(url: tlc.core.url.Url | None = None, created: str | None = None, init_parameters: Any = None)#

Bases: abc.ABC

The base class for all 3LC objects.

Contains these basic properties:

‘type’: Which class this object is (used by factory method to instantiate the correct class during JSON deserialization)

‘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.

‘schema’: A property describing the layout of this object. Note that this value should NOT be written to JSON, except for objects where recreating the schema would be a “heavy” operation.

       This means, in practice, that the 'schema' is only ever written
       to JSON for Table objects, and only after they have determined the
       immutable schema for their 'rows' property.

       For this last reason, there's an assert that schemas are never written
       unless there's a non-empty 'schema.rows.values' list.

‘serialization_version’: The serialization version of the object.

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

Returns self[property_name] if it exists, or the provided new value if not None else the default_value

This pattern allows all creation of new objects to be done via the constructor

ensure_minimal_schema() None#
ensure_complete_schema() None#
ensure_dependent_properties() None#

Make sure all dependent properties are populated, may be costly

This call can be used to delay expensive operations that are required for the object to be fully defined. But that are not necessary for the object to be serialized. For example a UMAP-table may need to compute a UMAP embedding before it can be be used to reduce an input table, but the UMAP embedding is not required until table rows are actually requested.

Another example: Table.row_count is initially set to UNKNOWN_ROW_COUNT (-1) to indicate that it is not (yet) known, after a call to ensure_dependent_properties it will be set to the correct value.

Override in subclasses to ensure dependent properties are populated

ensure_fully_defined() None#

Makes 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.

However, for Table objects it also means:

  • Making sure the ‘schema.rows’ sub-schema defines the layout of table rows if and when they will be produced

To ensure dependent properties are populated, call ensure_dependent_properties

write_to_url(force: bool = False) tlc.core.url.Url#
static add_object_url_property_to_schema(schema: tlc.core.schema.Schema, url_string_icon: str = '') None#

Adds the ‘url’ property to this schema

static add_is_url_writable_property_to_schema(schema: tlc.core.schema.Schema) None#

Adds the ‘is_url_writable’ property to this schema

should_include_schema_in_json(_schema: tlc.core.schema.Schema) bool#

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

to_json(init_level: int = 1) 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.

copy(*, destination_url: tlc.core.url.Url | None = None, if_exists: typing.Literal[raise, rename, overwrite] = 'raise') tlc.core.object.Object#

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

  • 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.


A copy of this table.

delete() None#

Deletes this object from its URL.

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

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

The base implementation never considers an object stale.

  • 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.


True if the object is stale, False otherwise.


ValueError – if the timestamp is invalid.

absolute_url_from_relative(input_url: tlc.core.url.Url) tlc.core.url.Url#

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

relative_url_from_absolute(input_url: tlc.core.url.Url) tlc.core.url.Url#

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

classmethod type_name() str#

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

classmethod from_url(url: tlc.core.url.Url | str) tlc.core.object.Object#

Creates an Object from a URL.


url – The URL of the object.


The object.