corelay.plugboard

A module that contains the Plugboard class. Plugboards manage instances of Slot, which describe values. A Slot can be filled using a Plug, which represents a concrete value.

Classes

`EmptyInit`	`EmptyInit` is a class intended to be inherited as a last step down the MRO, to catch any remaining positional and/or keyword arguments and thus raise proper exceptions.
`Plug`	Container class to fill slots associated with a certain instance.
`Plugboard`	Optional Manager class for slots.
`Slot`	Slots are descriptors that contain objects in a container called `Plug`.
`SlotDefaultAccess`	A proxy-object descriptor class to access the default values of the owning class of a `Slot`, since `Slot` instances cannot be returned except by accessing a classes' `__dict__`.

class corelay.plugboard.EmptyInit[source]

Bases: object

EmptyInit is a class intended to be inherited as a last step down the MRO, to catch any remaining positional and/or keyword arguments and thus raise proper exceptions.

__init__() → None[source]

Initializes a new instance of EmptyInit.

Note

This is not intended to be called directly, but rather by the constructor of the next class up in the inheritance hierarchy. The super-delegation is not unnecessary, even if PyLint claims so, since this is causes Python to raise a more informative exception when the user tries to pass more keyword arguments than are accepted by the constructors in the inheritance hierarchy. If the constructor of the penultimate class in inheritance hierarchy calls this constructor and there are still keyword arguments left, Python will raise a TypeError with a message like “TypeError: object.__init__() takes exactly one argument (the instance to initialize)”. This may confuse users, but if the constructor call is delegated to the next class up (i.e., object), the exception will be more informative and say something like: “TypeError: Empty.__init__() takes 0 positional arguments but 1 was given”.

Return type:: None

class corelay.plugboard.Slot[source]

Bases: EmptyInit

Slots are descriptors that contain objects in a container called Plug. Instances of the Slot class have a dtype and a default value, which are enforced to be consistent. When a Slot instance is accessed in a class, it will return the contained object of its Plug container. When accessing or assigning Slot instances in a class that have never been accessed before, a Plug object is stored in the class’ __dict__ under the same name the Slot was assigned to in the class. Slots may have their default value set to None, in which case setting plugs belonging to it must have either a Plug.default value, or an explicit Plug.obj value on their own. Calling a Slot instance creates a corresponding Plug container instance.

Note

See https://docs.python.org/3/howto/descriptor.html for more information on descriptors.

See also

Plugboard
Plug

__init__(dtype: type | tuple[type, ...] = object, default: Any = None, **kwargs: Any) → None[source]

Initializes a new Slot instance. Configures that data type and the default value of the slot. A consistency check is performed to ensure that the default value is of the correct type.

Parameters:

dtype (type | tuple[type, ...]) – The data type of the slot. This can be a single type or a tuple of types. The value of the plug, as well as the default value, must be of this type or one of the types in the tuple. Defaults to object.
default (Any) – The default value of the plug. The default value must be an instance of the specified data type dtype or one of the types in the tuple. If no default value is set, it will be None. When a plug is created without an explicit value, it will use this default value. Defaults to None.
**kwargs (Any) – Additional keyword arguments that are passed to the parent class constructor. This is done for cooperativity’s sake, as the next class one step up in the inheritance hierarchy will be EmptyInit, which does not accept any additional keyword arguments and will raise an exception if any are passed.

Return type:

None

get_plug(instance: Any, obj: Any = None, default: Any = None) → Plug[source]

Gets a corresponding Plug that can be used to access the __dict__ of the Slot instance . In case a new Plug has to be created, the obj and default parameters may be specified.

Parameters:

instance (Any) – An instance of the class the Slot was assigned in.
obj (Any) – The object value to write to newly created Plug instances.
default (Any) – The default value to write to newly created Plug instances.

Returns:

Returns a Plug container. If a Plug instance already exists in the instance’s __dict__ it is returned. Otherwise, a new Plug container is created, which is also appended to the instance’s __dict__. If a new Plug instance is created, the obj and default values are set to the values passed in.

Return type:

Plug

__set_name__(owner: type, name: str) → None[source]

Is invoked, when the Slot is assigned to a class or instance attribute. Sets the name of the slot when assigned under a class. Necessary to write the correct __dict__ entry in the parent class.

Parameters:

owner (type) – The parent class the Slot was assigned in.
name (str) – The name under which the Slot was assigned in the parent class.

Return type:

None

__get__(instance: Any, owner: type) → Slot | Any[source]

Is invoked, when the class or instance attribute the Slot was assigned to is read. When the Slot is accessed from a class, the Slot instance itself is returned. If accessed using an instance, the corresponding Plug container’s value is returned.

Parameters:

instance (Any) – The instance of the parent class the Slot was assigned in.
owner (type) – The parent class the Slot was defined in.

Returns:

Returns the value of the Plug container.

Return type:

Slot | Any

__set__(instance: Any, value: Any) → None[source]

Is invoked, when the class or instance attribute the Slot was assigned to is written. Sets the instance’s Plug container object value.

Parameters:

instance (Any) – The instance of the parent class the Slot was assigned in.
value (Any) – The value to set the Plug container’s object value to.

Return type:

None

__delete__(instance: Any) → None[source]

Is invoked, when the class or instance attribute the Slot was assigned to is deleted. Deletes the instance’s Plug container object value if it exists, enforcing the use of its default value.

Parameters:: instance (Any) – The instance of the parent class the Slot was assigned in.
Return type:: None

__repr__() → str[source]

Returns a str representation of the Slot instance.

Returns:: Returns a str representation of the Slot instance.
Return type:: str

property default: Any

Gets or sets the default value of the Slot.

Returns:: Returns the slot’s default value. If not set, None is returned.
Return type:: Any

property dtype: type | tuple[type, ...]

Gets or sets the slot’s dtype.

Returns:: Returns the slot’s dtype. If not set, None is returned.
Return type:: type | tuple[type, …]

property optional: bool

Gets a value indicating whether the Slot is optional.

Returns:: Returns True if the Slot is optional, i.e., it has a default value, and False otherwise.
Return type:: bool

__call__(obj: Any = None, default: Any = None) → Plug[source]

Create a new corresponding Plug container

Parameters:

obj (Any) – A value to initialize the newly created Plug container’s object value to. Defaults to None.
default (Any) – A value to initialize the newly created Plug container’s default value to. Defaults to None.

Returns:

Returns a newly created Plug container instance, obeying the type and optionality constraints.

Return type:

Plug

class corelay.plugboard.Plug[source]

Bases: EmptyInit

Container class to fill slots associated with a certain instance. The instance is usually of type Plugboard, but may be of any kind of type.

See also

Slot
Plugboard

__init__(slot: Slot, obj: Any = None, default: Any = None, **kwargs: Any) → None[source]

Initializes a new Plug instance and checks for consistency.

Parameters:

slot (Slot) – The Slot instance to associate with this Plug.
obj (Any) – An explicitly defined object held in the Plug container. If not set, default is returned as its value.
default (Any) – A plug-dependent lower-priority object held in the Plug container. If not set, fallback is returned.
**kwargs (Any) – Keyword arguments passed down to the base class constructor, for cooperativity’s sake. In normal cases, this next class will be EmptyInit, which accepts no more keyword arguments and will raise an exception.

Return type:

None

property slot: Slot

Gets or sets the associated Slot.

Returns:: Returns the associated Slot. If not set, None is returned.
Return type:: Slot

property dtype: type | tuple[type, ...]

Gets the Slot.dtype of the associated Slot. The dtype property is non-mutable.

Returns:: Returns the Slot.dtype of the associated Slot.
Return type:: type | tuple[type, …]

property optional: bool

Gets a value indicating whether the Plug container has a default value. The Plug.optional property is non-mutable.

Returns:: Returns True if the Plug container has a default value, and False otherwise.
Return type:: bool

property fallback: Any

Gets the default value of the associated Slot. The fallback property is non-mutable.

Returns:: Returns the default value of the associated Slot.
Return type:: Any

property obj: Any

Gets or sets the value of the object contained in the Plug. If the Plug does not contain an object value, default is retrieved instead.

Returns:: Returns the object value contained in the Plug. If not set, default is returned.
Return type:: Any

property default: Any

Gets or sets the default value of the Plug. If the default value is not set, then the fallback value is retrieved instead.

Returns:: Returns the default value of the Plug. If not set, fallback is returned.
Return type:: Any

class corelay.plugboard.SlotDefaultAccess[source]

Bases: object

A proxy-object descriptor class to access the default values of the owning class of a Slot, since Slot instances cannot be returned except by accessing a classes’ __dict__.

See also

Slot
Plugboard
Plug

__init__(instance: Tracker | Any = None) → None[source]

Initializes a new SlotDefaultAccess instance.

Parameters:: instance (Tracker | Any) – The instance of the class the SlotDefaultAccess is associated with.
Return type:: None

__get__(instance: Any, owner: Any) → SlotDefaultAccess[source]

Is invoked when the property, the SlotDefaultAccess is stored in, is retrieved. Returns a new SlotDefaultAccess instance initialized with the provided instance value, which is the instance of the class that is the owner of the SlotDefaultAccess.

Parameters:

instance (Any) – The instance of the class the SlotDefaultAccess is associated with.
owner (Any) – The class of the instance that owns the SlotDefaultAccess.

Returns:

Returns a new instance of SlotDefaultAccess initialized with the provided instance value.

Return type:

SlotDefaultAccess

__set__(instance: Any, value: dict[str, Any]) → None[source]

Is invoked when the property, the SlotDefaultAccess is stored in, is set. Sets the default values of the associated owner class instance’s slots by assigning a the values of the dict specified in value.

Parameters:

instance (Any) – The instance of the class the SlotDefaultAccess is associated with.
value (dict[str, Any]) – A dict containing the default values to set for the associated owner class instance’s slots.

Raises:

TypeError – The value is not a dict.

Return type:

None

__dir__() → list[str][source]

Returns a list of all slots of the associated owner class instance.

Returns:: Returns a list of all slots of the associated owner class instance.
Return type:: list[str]

class corelay.plugboard.Plugboard[source]

Bases: Tracker, EmptyInit

Optional Manager class for slots. Uses SlotDefaultAccess to access Plug default values. Also initializes Plug container object values during instantiation by keywords.

See also

Slot
SlotDefaultAccess
Plug

__tracked__: collections.OrderedDict[str, Any]

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

default: Contains a proxy object to access the default values of the owning class of a Plug.

__init__(**kwargs: Any) → None[source]

Initializes a new Plugboard instance and initializes the slots via the keyword arguments passed in.

Parameters:: **kwargs (Any) – The keyword arguments that are used to initialize slots. Only keyword arguments which correspond to the slot attribute names of the class are processed. All other keyword arguments are passed to the constructor of the next class in the inheritance hierarchy.
Return type:: None

reset_defaults() → None[source]

Deletes the default values of all plugs of this instance.

Return type:: None

update_defaults(**kwargs: Any) → None[source]

Updates the default values of all plugs of this instance using the keyword arguments.

Parameters:: **kwargs (Any) – The keyword arguments that are used to update the default values of the plugs.
Return type:: None