decorators

Decorators for simplified Role, Event and Relationship definition.

This module provides decorators that simplify the syntax for defining Roles, Events and Relationships. They automatically apply @dataclass(slots=True), handle inheritance from Role/Event/Relationship, and manage registration.

Design Notes

The decorators handle three key tasks:

1. Making the class a dataclass with slots

2. Making it inherit from Role/Event/Relationship (if not already)

3. Auto-registration via __init_subclass__

Examples

Role decorator (simplest syntax):

>>> from bamengine import role, Float
>>>
>>> @role
... class Producer:
...     price: Float
...     production: Float
>>> # Automatically inherits from Role, is a dataclass, and is registered!

Role with custom name:

>>> @role(name="MyProducer")
... class Producer:
...     price: Float
...     production: Float

Event decorator:

>>> from bamengine import event
>>>
>>> @event
... class CustomPricingEvent:
...     def execute(self, sim):
...         prod = sim.get_role("Producer")
...         # Apply custom pricing logic

Relationship decorator:

>>> from bamengine import relationship, get_role, Float
>>>
>>> @relationship(source=get_role("Borrower"), target=get_role("Lender"))
... class LoanBook:
...     principal: Float
...     rate: Float
...     debt: Float

Traditional syntax (still works):

>>> from dataclasses import dataclass
>>> from bamengine.core import Role
>>> from bamengine import Float
>>>
>>> @dataclass(slots=True)
... class Producer(Role):
...     price: Float
...     production: Float

See also

Role

Base class for roles (components)

Event

Base class for events (systems)

Relationship

Base class for relationships

Functions

role	Decorator to define a Role with automatic inheritance and dataclass.
event	Decorator to define an Event with automatic inheritance and dataclass.
relationship	Decorator to define a Relationship with automatic inheritance and registration.