feat: invoke callback group — spawn external work from states

[fgmacedo]

Summary

• Adds invoke as a first-class callback group (CallbackGroup.INVOKE), following SCXML <invoke> semantics and UML's do activity (do/) concept
• States can spawn background work on entry (sync: daemon threads, async: thread executor + asyncio.Task) and cancel it on exit
• Supports convention naming (on_invoke_<state>), decorators (@state.invoke), inline callables, IInvoke protocol, and child StateChart invocation
• invoke_group() runs multiple callables concurrently and waits for all results as a single done.invoke event
• done_invoke_<state> factory prefix maps to done.invoke.<state> event family
• Adds visit()/async_visit() visitor pattern and __contains__ to CallbacksRegistry
• Full test suite (39 tests, sync + async) and documentation with practical file I/O examples

Example

import json
from pathlib import Path
from statemachine import State, StateChart

def load_config():
    return json.loads(Path("config.json").read_text())

class ConfigLoader(StateChart):
    loading = State(initial=True, invoke=load_config)
    ready = State(final=True)
    done_invoke_loading = loading.to(ready)

    def on_enter_ready(self, data=None, **kwargs):
        self.config = data

sm = ConfigLoader()
# load_config() runs in a background thread.
# When it returns, done.invoke.loading fires automatically,
# transitioning to "ready" with the parsed config as `data`.

For concurrent work with grouped results:

from statemachine.invoke import invoke_group

class BatchLoader(StateChart):
    loading = State(
        initial=True,
        invoke=invoke_group(
            lambda: Path("file_a.txt").read_text(),
            lambda: Path("file_b.txt").read_text(),
        ),
    )
    ready = State(final=True)
    done_invoke_loading = loading.to(ready)

    def on_enter_ready(self, data=None, **kwargs):
        self.results = data  # ["contents of file_a", "contents of file_b"]

Closes #521

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (3b5ef35) to head (4d29187).
⚠️ Report is 1 commits behind head on develop.

Additional details and impacted files

@@             Coverage Diff              @@
##           develop      #571      +/-   ##
============================================
+ Coverage    99.94%   100.00%   +0.05%     
============================================
  Files           32        33       +1     
  Lines         3768      4044     +276     
  Branches       583       635      +52     
============================================
+ Hits          3766      4044     +278     
+ Misses           1         0       -1     
+ Partials         1         0       -1     

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

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
1 New issue
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

[rodrigobnogueira]

👏👏👏 great