tlc.core.object#

Base class for all 3LC objects

Module Contents#

Classes#

Class

Description

Object

The base class for all 3LC objects.

API#

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.

Variables:

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

  • serialization_version – The serialization version of the 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.

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

A helper method for getting the initial value of a property.

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.

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.

ensure_minimal_schema() → None#

Make sure the schema is populated with the minimal properties.

ensure_complete_schema() → None#

Make sure the schema is populated with all properties.

ensure_dependent_properties() → None#

Make sure dependent properties are populated

This method must set all properties required to achieve the ‘fully defined’ state of an object.

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

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.

For Table objects this also means making sure the ‘schema.rows’ sub-schema defines the layout of table rows if and when they will be produced

To ensure that data is ready and dependent properties are populated, call ensure_dependent_properties.

write_to_url(force: bool = False) → tlc.core.url.Url#

Writes this object to its URL.

Parameters:

force – Whether to overwrite the object if it already exists.

Returns:

The URL where the object was written.

static add_object_url_property_to_schema(schema: tlc.core.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.

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

Add the ‘is_url_writable’ property to the provided schema.

Parameters:

schema – The schema to add the property to.

should_include_schema_in_json(_schema: tlc.core.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.

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

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#

Deletes this object from its URL.

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.

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.

absolute_url_from_relative(input_url: tlc.core.url.Url) → tlc.core.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.

relative_url_from_absolute(input_url: tlc.core.url.Url) → tlc.core.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.

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#

Create an Object from a URL.

Parameters:

url – The URL of the object.

Returns:

The object.