tlc.core.object_reference

Module for managing references to objects with lazy resolution and type safety.

Module Contents

Classes

Class

Description

ObjectReference

Represents a reference to an Object, with optional lazy resolution.

API

class ObjectReference(
create_from: str | Url | Object,
owner_url: Url | None = None,
)

Represents a reference to an Object, with optional lazy resolution.

The ObjectReference class is designed to manage references to objects and resolve them lazily when requested. It can be initialized from an object, a URL, or a string. The class also provides functionalities like type casting and URL management.

The Url will be stored as a relative Url with respect to the owner_url if provided, otherwise it will be stored as given.

Example:

my_url = Url("http://example.com/object")
obj_ref = ObjectReference(my_url)
actual_object = obj_ref.object
Closing Comments:

  • Lazy Resolution: The actual object is only loaded when specifically requested.

  • Type Safety: Allows you to cast the object to a specified type when retrieving it.

Initialize an ObjectReference.

You can initialize the reference with either an object, a URL, or a string.

Parameters:

  • create_from – The initial value to create the reference from.

  • owner_url – The URL of the owning object, if any.

resolve() → bool

Resolve the referenced object.

Loads the actual object if it is not already loaded. Otherwise, it’s a no-op.

Returns:

True if the object was resolved, False if it was already loaded.

Raises:

ValueError – If unable to resolve the reference.

property object: Object

Returns the referenced object

If not already loaded, this method will first instantiate the object from the Url If the resolving fails a ValueError is raised

object_as(
object_type: type[tlc.core.object_reference._T],
) → tlc.core.object_reference._T

Get the referenced object, cast to a specific type.

Example:

my_ref = ObjectReference(some_url)
my_typed_object = my_ref.object_as(SomeType)
Parameters:

object_type – The type to cast the object to.

Returns:

The object, cast to the specified type.

Raises:

AssertionError – If the object’s type doesn’t match the specified type.

property url: Url

Get the URL of the referenced object.

Useful for serialization and debugging.

Returns:

The URL of the referenced object.