feat: class-level listener declarations with setup() protocol

[fgmacedo]

Summary

• Add listeners class attribute to StateChart/StateMachine for declaring listeners at class definition time
• Callable entries (classes, partial, lambdas) act as factories — called per SM instance to produce a fresh listener
• Non-callable entries (pre-built objects) are shared across all SM instances
• Inheritance supported via MRO: child listeners append after parent; listeners_inherit = False replaces entirely
• setup(sm, **kwargs) protocol lets factory-created listeners receive runtime dependencies via SignatureAdapter
• New active_listeners public property to inspect all attached listeners
• Serialization (pickle/deepcopy) correctly preserves all listeners without duplication

Example

from functools import partial
from statemachine import State, StateChart

class AuditListener:
    def __init__(self):
        self.log = []

    def after_transition(self, event, source, target):
        self.log.append(f"{event}: {source.id} -> {target.id}")

class DBListener:
    def setup(self, sm, session=None, **kwargs):
        self.session = session

    def after_transition(self, event, source, target, **kwargs):
        if self.session:
            self.session.add({"event": event, "from": source.id, "to": target.id})

class OrderMachine(StateChart):
    listeners = [AuditListener, DBListener]

    draft = State(initial=True)
    confirmed = State(final=True)
    confirm = draft.to(confirmed)

# Runtime deps injected via kwargs, forwarded to setup()
sm = OrderMachine(session=db.session())
sm.send("confirm")

sm.active_listeners[0].log
# ['confirm: draft -> confirmed']

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.94%. Comparing base (7faf7fa) to head (8eda64a).
⚠️ Report is 1 commits behind head on develop.

Additional details and impacted files

@@           Coverage Diff            @@
##           develop     #570   +/-   ##
========================================
  Coverage    99.94%   99.94%           
========================================
  Files           32       32           
  Lines         3734     3768   +34     
  Branches       575      583    +8     
========================================
+ Hits          3732     3766   +34     
  Misses           1        1           
  Partials         1        1           

Flag	Coverage Δ
unittests	99.94% <100.00%> (+<0.01%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[sonarqubecloud]

Quality Gate passed

Issues
4 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud