corelay.tracker

A module that contains the Tracker, which is used to track Slot definitions in classes that inherit from Plugboard.

Classes

`MetaTracker`	A meta class to track attributes of a type.
`Tracker`	Tracks all public class attributes, i.e., all class attributes not enclosed in double underscores.

class corelay.tracker.MetaTracker[source]

Bases: ABCMeta

A meta class to track attributes of a type.

Note

This is used to track the slots of a class. In CoRelAy, slots are declared as class attributes, and during instantiation, the class attributes are converted to respective instance attributes of the data type declared in the slot. For example, a Param slot is used to declare parameters of processors. When a processor has a class attribute that is a Param with a data type of int, then when the processor is instantiated, an instance attribute of the same name is created with the data type of int.

There are two ways a slot can be declared:

The old way of declaring a slot, which is to declare it as a class attribute and assign it a Slot instance, e.g., param = Param(int, 0). This is not the recommended way of declaring a slot anymore, because it causes problems with static type checkers, like MyPy. In Python, class attributes can be accessed using the class or using the instance. For example, if a class Test has a class attribute a = 5, then Test.a and Test().a will both return 5. Static type checkers, like MyPy, do not know that we are converting the class attribute a to an instance attribute of type int during instantiation, so they will assume that when a slot is accessed using the instance, it will have the same type as the class attribute. This means that the static type checker will show an error when the slot is accessed using the instance, because the type of the class attribute is Slot and not int.
The new way of declaring a slot, which is to declare it as a class attribute of type typing.Annotated. The typing.Annotated type is a special type that allows us to add metadata to a type hint. The first argument of typing.Annotated is the actual type of the attribute, and then any number of additional arguments can be passed, which are used as metadata. So, for example, a parameter slot can be declared as param: Annotated[float, Param(float, 0.0)]. Since the static type checker knows that the actual type of the attribute is float, it will not show an error when the slot is accessed using the instance. The metadata is used to store the instance of the slot, which contains the information about the data type, the default value, etc. Unfortunately, this is only a declaration, which has no effect on the runtime. This means, that no actual class attribute is created. But typing.Annotated will add a special __annotations__ attribute to the class, which contains a dict with the names of the declared class attributes and their metadata.

The MetaTracker meta class is used to track the class attributes of a class that are not special “dunder” attributes like __class__, as well as the declared class attributes from the __annotations__ attribute. The tracked class attributes are stored in an collections.OrderedDict called Tracker.__tracked__. The Tracker class uses the MetaTracker meta class and allows users to access the tracked class attributes. The class attributes are tracked in the order they were declared in the class, with the caveat that first, all class attributes come in the order of declaration, and then all declared class attributes come in the order of declaration. As long as only one method of declaring a slot is used, the order of declaration will be preserved.

For more information on meta classes, please refer to PEP 3115.

Example

>>> class OrderedInts(metaclass=MetaTracker):
...     a = 14
...     b = 21
...     c = 42
... OrderedInts(a=0).__tracked__
collections.OrderedDict([('a', 0), ('b', 21), ('c', 42)])

classmethod __prepare__(class_name: str, base_classes: tuple[type, ...], /, **kwargs: Any) → OrderedDict[str, Any][source]

Prepare the class dict to be an collections.OrderedDict. This is done to preserve the order of declaration of the class attributes.

Parameters:

class_name (str) – The name of the class.
base_classes (tuple[type, ...]) – The base classes of the class.
**kwargs (Any) – Additional keyword arguments.

Returns:

Returns a collections.OrderedDict, which will be used as the dictionary for the class attributes.

Return type:

collections.OrderedDict[str, Any]

static __new__(mcs, class_name: str, base_classes: tuple[type, ...], class_attributes: OrderedDict[str, Any]) → MetaTracker[source]

Is called when a new class is created with the MetaTracker as its metaclass. Attaches a new Tracker.__tracked__ attribute to the class, which is a dict with all public attributes of the class, i.e., those not enclosed in double underscores. If the class that is being created already has a Tracker.__tracked__ attribute, the new attributes are appended to it.

Parameters:

class_name (str) – The name of the class.
base_classes (tuple[type, ...]) – The base classes of the class.
class_attributes (collections.OrderedDict[str, Any]) – A dict with the attributes of the class. In this case, with the addition of tracker attributes.

Returns:

Returns the new class with the Tracker.__tracked__ attribute.

Return type:

MetaTracker

class corelay.tracker.Tracker[source]

Bases: object

Tracks all public class attributes, i.e., all class attributes not enclosed in double underscores. This makes them available in a class attribute Tracker.__tracked__ using the meta class MetaTracker.

__tracked__: OrderedDict[str, Any]

An collections.OrderedDict with all public class attributes, i.e., all class attributes not enclosed with double underscores.

classmethod collect(dtype: type | tuple[type, ...]) → OrderedDict[str, Any][source]

Retrieves all tracked class attributes of a certain type.

Parameters:: dtype (type | tuple[type, ...]) – The type or types of the class attributes to retrieve.
Returns:: Returns an collections.OrderedDict that contains the public class attributes, i.e., all class attributes not enclosed in double underscores, of the given type or types. The keys are the attribute names and the values are the attribute values.
Return type:: collections.OrderedDict[str, Any]

classmethod get(attribute_name: str) → Any[source]

Retrieves a tracked class attribute by name.

Parameters:: attribute_name (str) – The name of the class attribute to retrieve.
Raises:: AttributeError – The class attribute does not exist.
Returns:: Returns the value of the class attribute with the given name. If the class attribute does not exist None is returned.
Return type:: Any

collect_attr(dtype: type | tuple[type, ...]) → OrderedDict[str, Any][source]

Retrieves all instance attributes, corresponding to tracked class attributes of a certain type.

Parameters:: dtype (type | tuple[type, ...]) – The type or types of the instance attributes to retrieve.
Returns:: Returns an collections.OrderedDict that contains the instance attributes, corresponding to tracked class attributes, of the given type or types. The keys are the attribute names and the values are the attribute values.
Return type:: collections.OrderedDict[str, Any]

get_attr(attribute_name: str) → Any[source]

Retrieves an instance attribute, corresponding to a tracked class attribute, by name.

Parameters:: attribute_name (str) – The name of the class attribute to retrieve.
Raises:: AttributeError – The instance attribute does not exist.
Returns:: Returns the value of the instance attribute with the given name. If the instance attribute does not exist None is returned.
Return type:: Any