feat: add task methods, effect, demo and test suite

[Fatumayattani]

This PR introduces the core task system and test suite for py-actress, establishing the foundation for building actor-based asynchronous workflows in Python. It includes the full task API, scheduler, effect model, and a working demo.

---

What’s Included

• task_methods.py: Core Task implementation (fork, join, wait, suspend, effects, etc.)
• scheduler.py: Lightweight cooperative scheduler
• effect.py: Effect base and helper implementations
• types.py: Fork and Controller types
• examples/demo.py: Working actor messaging example
• test/test_task.py: Test suite covering the main task methods and actor loop

---

Testing

All core task methods and messaging flows are tested using pytest.
To run the tests with verbose output:

pytest -v

This confirms:

• Task scheduling and actor message loops work as expected
• Task methods like fork, send, wait, and effects behave correctly
• Scheduler and effect execution are reliable under basic scenarios

---

Next Steps

• Expand test coverage to include more advanced task flows
• Extend actor scenarios beyond single loop processing

[0-th]

Great work here @Fatumayattani ! Appreciate the effort.

Firstly, It took some effort to look through the PR because of the sheer amount of things it seems to be doing, it would be helpful to make the PRs smaller and broken into meaningful commits next time.

Secondly, the library doesn't seem to align with the implementation in the canonical actor library, I can't find the functionalities for Effects tagging, group, Stack etc.
It's hard to compare if the PR maintains feature-parity with the actor library.

I'd recommend we work on the issues as listed and continue questions, discussions and review for each component on there.

Thanks for your assistance!

[Fatumayattani]

Thanks @0-th .. I appreciate the feedback and the review.

This PR was intentionally focused on laying down the core building blocks: task methods, scheduler, and effect primitives. Some of the features you mentioned (like tagging and grouping) are part of the next iteration, not because I wasn’t aware of them, but because I wanted a solid foundation to build on top of.

I’m confident the direction is sound, and the missing pieces are very much planned and straightforward to layer in. Your input helps sharpen that path, so thank you for taking the time.

[Fatumayattani]

Hi @0-th

I’ve completed the TypeScript-to-Python typing translation for Issue #2.
The updated types.py now mirrors task.ts using Protocols, TypeAliases, generics, and docstrings, while keeping all existing runtime behavior untouched. This aligns the library with the canonical actor implementation at the type level and improves IDE and type-checker support without expanding runtime scope.

Let me know if you'd like deeper integration tests or additional doc coverage.

Resolves #2

[0-th]

Hi @Fatumayattani great effort here. I'd review this in a bit and give my feedback.

[0-th]

hi @Fatumayattani , apologies for just getting back to you on this.

in case you're still interested in contributing to the typing and lint issues in the implementation (it'd be easier to do now that the implementation is complete), see the comment I made here on a similar PR