tlc.core.objects.mutable_object

Base class for objects that can be mutated.

Module Contents

Classes

Class	Description
MutableObject	Base class for objects that can be mutated.

API

class tlc.core.objects.mutable_object.MutableObject(url: tlc.core.url.Url | None = None, created: str | None = None, last_modified: str | None = None, init_parameters: Any = None)

Bases: tlc.core.object.Object

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.

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

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.

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(init_parameters: Mapping[str, object]) → None

static add_last_modified_property_to_schema(schema: tlc.core.schema.Schema, description: str) → None

Add the ‘last_modified’ property to this schema

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

is_stale(timestamp: datetime.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 parses the timestamps and computes the difference in seconds. If this 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.