actio 0.0.2__tar.gz

actio-0.0.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Semenets V. Pavel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

actio-0.0.2/PKG-INFO

@@ -0,0 +1,67 @@
+Metadata-Version: 2.4
+Name: actio
+Version: 0.0.2
+Summary: Pure Python actor system for building concurrent and distributed applications with async/await support for Python 3.11+
+License: MIT
+License-File: LICENSE
+Author: Semenets V. Pavel
+Author-email: p.semenets@gmail.com
+Requires-Python: >=3.11
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Communications
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Hardware
+Project-URL: Documentation, https://github.com/xDarkmanx/actio#readme
+Project-URL: Homepage, https://github.com/xDarkmanx/actio
+Project-URL: Repository, https://github.com/xDarkmanx/actio
+Description-Content-Type: text/markdown
+
+### Actio Project
+
+Pure Python actor system for building concurrent and distributed applications with async/await support.
+
+### Features
+
+**Async/await native** - Built on Python 3.11+ asyncio
+
+**Hierarchical actors** - Parent-child relationships with supervision
+
+**Message routing** - Path-based message delivery between actors
+
+**Lifecycle management** - Started/receive/stopped hooks with error handling
+
+**Type safe** - Full type annotations with Pylance/MyPy support
+
+### Quick Start
+
+```python
+import asyncio
+from actio import Actor, ActorSystem, actio
+
+@actio()
+class MyActor(Actor):
+    async def receive(self, sender, message):
+        print(f"Received: {message}")
+
+async def main():
+    system = ActorSystem()
+    actor_ref = system.create(MyActor())
+    
+    system.tell(actor_ref, "Hello World!")
+    await asyncio.sleep(0.1)
+    system.shutdown()
+
+asyncio.run(main())
+```
+
+### License
+MIT License - see LICENSE file for details.
+

actio-0.0.2/README.md

@@ -0,0 +1,40 @@
+### Actio Project
+
+Pure Python actor system for building concurrent and distributed applications with async/await support.
+
+### Features
+
+**Async/await native** - Built on Python 3.11+ asyncio
+
+**Hierarchical actors** - Parent-child relationships with supervision
+
+**Message routing** - Path-based message delivery between actors
+
+**Lifecycle management** - Started/receive/stopped hooks with error handling
+
+**Type safe** - Full type annotations with Pylance/MyPy support
+
+### Quick Start
+
+```python
+import asyncio
+from actio import Actor, ActorSystem, actio
+
+@actio()
+class MyActor(Actor):
+    async def receive(self, sender, message):
+        print(f"Received: {message}")
+
+async def main():
+    system = ActorSystem()
+    actor_ref = system.create(MyActor())
+    
+    system.tell(actor_ref, "Hello World!")
+    await asyncio.sleep(0.1)
+    system.shutdown()
+
+asyncio.run(main())
+```
+
+### License
+MIT License - see LICENSE file for details.

actio-0.0.2/pyproject.toml

@@ -0,0 +1,52 @@
+[tool.poetry]
+name = "actio"
+version = "0.0.2"
+description = "Pure Python actor system for building concurrent and distributed applications with async/await support for Python 3.11+"
+authors = ["Semenets V. Pavel <p.semenets@gmail.com>"]
+license = "MIT"
+readme = "README.md"
+
+packages = [{ include = "actio", from = "src" }]
+homepage = "https://github.com/xDarkmanx/actio"
+repository = "https://github.com/xDarkmanx/actio"
+documentation = "https://github.com/xDarkmanx/actio#readme"
+
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: System :: Hardware",
+    "Topic :: Communications",
+]
+
+[tool.poetry.dependencies]
+python = ">=3.11"
+
+[tool.poetry.group.lint.dependencies]
+flake8 = "^7.3.0"
+
+[tool.poetry.group.security.dependencies]
+bandit = "^1.8.6"
+
+[tool.poetry.group.test.dependencies]
+pytest = ">=8.4.2"
+pytest-asyncio = ">=1.2.0"
+pytest-cov = ">=4.1.0"
+pytest-mock = ">=3.11.0"
+anyio = ">=3.7.0"
+
+[tool.flake8]
+max-line-length = 127
+max-complexity = 25
+ignore = "E203,W503"
+exclude = [".git", "__pycache__", ".venv", "build", "dist"]
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"

actio-0.0.2/src/actio/__init__.py

@@ -0,0 +1,40 @@
+# actio/__init__.py
+# -*- coding: utf-8 -*-
+
+from .ref import ActorRef
+from .ref import ActorDefinition
+
+from .messages import PoisonPill
+from .messages import DeadLetter
+from .messages import Terminated
+
+from .actor import Actor
+from .actor import ActorSystem
+
+from .registry import ActorRegistry
+from .registry import registry
+from .registry import actio
+
+__version__ = "0.0.2"
+__author__ = "Semenets V. Pavel"
+__license__ = "MIT"
+
+__all__ = [
+    # from ref.py
+    'ActorRef',
+    'ActorDefinition',
+
+    # from messages.py
+    'PoisonPill',
+    'DeadLetter',
+    'Terminated',
+
+    # from actor.py
+    'Actor',
+    'ActorSystem',
+
+    # from registry.py
+    'ActorRegistry',
+    'registry',
+    'actio'
+]

actio-0.0.2/src/actio/actor.py

@@ -0,0 +1,522 @@
+# actio/actor.py
+# -*- coding: utf-8 -*-
+
+from typing import Union
+from typing import Set
+from typing import Dict
+from typing import List
+from typing import Any
+from typing import Optional
+
+import asyncio
+import logging
+
+from uuid import uuid4
+
+from . import PoisonPill
+from . import DeadLetter
+from . import Terminated
+
+from . import ActorRef
+
+log = logging.getLogger('actio.actor')
+
+
+class Actor:
+    def __init__(self):
+        self._context: Optional['_ActorContext'] = None
+
+    async def receive(self, sender: ActorRef, message: Any) -> None:
+        """
+        Обрабатывает входящие сообщения.
+
+        Этот метод должен быть переопределён в подклассах.
+        """
+        raise NotImplementedError
+
+    # --- Вспомогательные методы для работы с детьми и системой ---
+
+    def create(self, actor: 'Actor', name: Optional[str] = None) -> ActorRef:
+        """Создаёт дочерний актор."""
+        child_actor_ref = self.system._create(actor=actor, parent=self.actor_ref, name=name)
+        self.watch(child_actor_ref)
+        return child_actor_ref
+
+    def tell(self, actor: Union['Actor', ActorRef], message: Any) -> None:
+        """Отправляет сообщение другому актору."""
+        self.system._tell(actor=actor, message=message, sender=self.actor_ref)
+
+    def schedule_tell(
+        self,
+        actor: Union['Actor', ActorRef],
+        message: Any,
+        *,
+        delay: Union[None, int, float] = None,
+        period: Union[None, int, float] = None,
+    ) -> asyncio.Task:
+        """Отправляет сообщение с задержкой или периодически."""
+        return self.system._schedule_tell(
+            actor=actor,
+            message=message,
+            sender=self.actor_ref,
+            delay=delay,
+            period=period
+        )
+
+    def watch(self, actor: ActorRef) -> None:
+        """Наблюдает за другим актором."""
+        self.system._watch(actor=self.actor_ref, other=actor)
+
+    def unwatch(self, actor: ActorRef) -> None:
+        """Прекращает наблюдение за другим актором."""
+        self.system._unwatch(actor=self.actor_ref, other=actor)
+
+    def stop(self) -> None:
+        """Останавливает этот актор."""
+        self.system.stop(actor=self.actor_ref)
+
+    # --- Хуки жизненного цикла ---
+    async def started(self) -> None:
+        """Вызывается при запуске актора."""
+        pass
+
+    async def restarted(self, sender: ActorRef, message: Any, error: Exception) -> None:
+        """Вызывается при ошибке в `receive`."""
+        log.exception(
+            '%s failed to receive message %s from %s',
+            self.actor_ref, message, sender, exc_info=error
+        )
+
+    async def stopped(self) -> None:
+        """Вызывается при остановке актора."""
+        pass
+
+    # --- Свойства для доступа к контексту ---
+    @property
+    def actor_ref(self) -> ActorRef:
+        assert self._context is not None, "Actor context not initialized"
+        return self._context.actor_ref
+
+    @property
+    def system(self) -> 'ActorSystem':
+        assert self._context is not None, "Actor context not initialized"
+        return self._context.system
+
+    @property
+    def parent(self) -> Optional[ActorRef]:
+        assert self._context is not None, "Actor context not initialized"
+        return self._context.parent
+
+    @property
+    def name(self) -> str:
+        return self.actor_ref.name
+
+    @property
+    def path(self) -> str:
+        return self.actor_ref.path
+
+    def __str__(self):
+        return self.path
+
+    def __repr__(self):
+        return self.path
+
+    # --- Вспомогательные методы для маршрутизации ---
+
+    async def _route_message_logic(self, sender: ActorRef, message: Dict[str, Any]) -> bool:
+        """
+        Встроенная логика маршрутизации для сообщений с действием 'route_message'.
+
+        :param sender: Отправитель сообщения.
+        :param message: Сообщение.
+        :return: True, если сообщение было обработано как маршрутное, иначе False.
+        """
+        action = message.get('action')
+        if action != 'route_message':
+            return False
+
+        destination: str = message.get('destination', '')
+        data = message.get('data')
+
+        # 1. Если destination пустой, это сообщение для текущего актора
+        if not destination:
+            # Передаём данные для обработки
+            # Создаём новое сообщение, чтобы не мутировать оригинальное
+            final_message = data if isinstance(data, dict) else {'data': data}
+            # Добавляем информацию о маршруте в финальное сообщение, если нужно
+            final_message['source'] = message.get('source')
+            await self.receive(sender, final_message)
+            return True
+
+        # 2. Разбираем путь
+        path_parts = [p for p in destination.split('/') if p]
+        if not path_parts:
+            # destination был "/", что тоже означает "этот актор"
+            final_message = data if isinstance(data, dict) else {'data': data}
+            await self.receive(sender, final_message)
+            return True
+
+        first_part = path_parts[0]
+        remaining_path = "/".join(path_parts[1:]) if len(path_parts) > 1 else None
+
+        # 3. Проверяем, является ли первая часть именем нашего прямого потомка
+        # Предполагаем, что у актора есть словарь потомков self.actors (как в примерах)
+        # Если такого атрибута нет, ищем в _context.children
+        target_child_ref: Optional[ActorRef] = None
+        child_actors_dict = getattr(self, 'actors', None)
+        if child_actors_dict and isinstance(child_actors_dict, dict):
+            target_child_ref = child_actors_dict.get(first_part)
+        else:
+            # Поиск по имени в списке детей из контекста
+            assert self._context is not None, "Actor context not initialized"
+            for child_ref in self._context.children:
+                if child_ref.name == first_part:
+                    target_child_ref = child_ref
+                    break
+
+        if target_child_ref:
+            # Нашли потомка, пересылаем ему.
+            # Формируем новое сообщение с обновлённым destination
+            forwarded_message = message.copy()
+            forwarded_message['destination'] = remaining_path
+            # Обновляем source: добавляем себя
+            current_source = forwarded_message.get('source', '')
+            # forwarded_message['source'] = f"{self.actor_ref.name}/{current_source}".strip('/')
+
+            log.debug(
+                f"[{self.actor_ref.path}] Routing to child '{first_part}' "
+                f"with new destination '{remaining_path}' and updated source "
+                f"'{forwarded_message['source']}'.")
+            self.tell(target_child_ref, forwarded_message)
+        else:
+            # Не нашли потомка, пересылаем родителю.
+            if self.parent:
+                # Формируем новое сообщение с обновлённым source
+                forwarded_message = message.copy()
+                # Обновляем source: добавляем себя
+                current_source = forwarded_message.get('source', '')
+                forwarded_message['source'] = f"{self.actor_ref.name}/{current_source}".strip('/')
+
+                log.debug(
+                    f"[{self.actor_ref.path}] Forwarding to parent with "
+                    f"updated source '{forwarded_message['source']}'.")
+                self.tell(self.parent, forwarded_message)
+            else:
+                # Мы корневой актор и не можем маршрутизировать дальше
+                log.warning(
+                    f"[{self.actor_ref.path}] Cannot route message, "
+                    f"no parent and '{first_part}' not found among children. Message: {message}"
+                )
+                # Можно отправить DeadLetter отправителю или в специальный актор
+                # self.tell(sender, DeadLetter(...))
+
+        return True  # Сообщение было обработано как маршрутное
+
+
+class ActorSystem:
+    """Система акторов."""
+
+    def __init__(self):
+        self._actors: Dict[ActorRef, '_ActorContext'] = {}
+        self._is_stopped = asyncio.Event()
+        self.children: List[ActorRef] = []  # Корневые акторы
+
+    def create(self, actor: Actor, name: Optional[str] = None) -> ActorRef:
+        """Создаёт корневой актор."""
+        return self._create(actor=actor, parent=None, name=name)
+
+    def tell(self, actor: Union[Actor, ActorRef], message: Any) -> None:
+        """Отправляет сообщение актору."""
+        self._tell(actor=actor, message=message, sender=None)
+
+    def schedule_tell(
+        self,
+        actor: Union[Actor, ActorRef],
+        message: Any,
+        *,
+        delay: Union[None, int, float] = None,
+        period: Union[None, int, float] = None
+    ) -> asyncio.Task:
+        """Отправляет сообщение с задержкой или периодически."""
+        return self._schedule_tell(actor=actor, message=message, sender=None, delay=delay, period=period)
+
+    def stop(self, actor: Union[Actor, ActorRef]) -> None:
+        """Останавливает актор."""
+        self._tell(actor=actor, message=PoisonPill(), sender=None)
+
+    def shutdown(self, timeout: Union[None, int, float] = None) -> None:
+        """Завершает работу всей системы акторов."""
+        asyncio.create_task(self._shutdown(timeout=timeout))
+
+    def stopped(self):
+        """Ожидает завершения работы системы."""
+        return self._is_stopped.wait()
+
+    # --- Внутренние методы ---
+    def _create(self, actor: Actor, *, parent: Union[None, Actor, ActorRef], name: Optional[str] = None) -> ActorRef:
+        """Внутренний метод создания актора."""
+        if not isinstance(actor, Actor):
+            raise ValueError(f'Not an actor: {actor}')
+
+        parent_ctx: Optional[_ActorContext] = None
+        if parent:
+            parent = self._validate_actor_ref(parent)
+            parent_ctx = self._actors[parent]
+            child_idx = len(parent_ctx.children) + 1
+        else:
+            child_idx = len(self.children) + 1
+
+        if not name:
+            name = f'{type(actor).__name__}-{child_idx}'
+
+        if parent:
+            path = f'{parent.path}/{name}'
+        else:
+            path = name
+
+        actor_id = str(uuid4().hex)
+        actor_ref = ActorRef(actor_id=actor_id, path=path, name=name)
+        actor_ctx = _ActorContext(self, actor_ref, parent)
+
+        actor_ctx.lifecycle = asyncio.get_event_loop().create_task(
+            self._actor_lifecycle_loop(actor, actor_ref, actor_ctx)
+        )
+
+        actor._context = actor_ctx
+        self._actors[actor_ref] = actor_ctx
+
+        if parent and parent_ctx:
+            parent_ctx.children.append(actor_ref)
+
+        else:
+            self.children.append(actor_ref)
+
+        return actor_ref
+
+    def _tell(self, actor: Union[Actor, ActorRef], message: Any, *, sender: Union[None, Actor, ActorRef]) -> None:
+        """Внутренний метод отправки сообщения."""
+        actor = self._validate_actor_ref(actor)
+
+        if sender:
+            sender = self._validate_actor_ref(sender)
+
+            if sender not in self._actors:
+                raise ValueError(f'Sender does not exist: {sender}')
+
+        if actor in self._actors:
+            actor_ctx = self._actors[actor]
+            actor_ctx.letterbox.put_nowait((sender, message))
+
+        elif sender:
+            deadletter = DeadLetter(actor=actor, message=message)
+            self._tell(sender, deadletter, sender=None)
+
+        else:
+            log.warning(f'Failed to deliver message {message} to {actor}')
+
+    def _schedule_tell(
+        self,
+        actor: Union[Actor, ActorRef],
+        message: Any,
+        *,
+        sender: Union[None, Actor, ActorRef],
+        delay: Union[None, int, float] = None,
+        period: Union[None, int, float] = None
+    ) -> asyncio.Task:
+        """Внутренний метод планирования отправки сообщения."""
+        if not delay:
+            if not period:
+                raise ValueError('Cannot schedule message without delay and period')
+            self._tell(actor=actor, message=message, sender=sender)
+            delay = period
+
+        ts = asyncio.get_event_loop().time() + delay
+        return asyncio.create_task(self._schedule_tell_loop(actor=actor, message=message, sender=sender, ts=ts, period=period))
+
+    async def _schedule_tell_loop(
+            self,
+            actor: Union[Actor, ActorRef],
+            message: Any,
+            *,
+            sender: Union[None, Actor, ActorRef],
+            ts: Union[None, int, float] = None,
+            period: Union[None, int, float] = None
+    ) -> None:
+        """Цикл для периодической отправки сообщения."""
+        actor = self._validate_actor_ref(actor)
+        delay = (ts - asyncio.get_event_loop().time()) if ts else 0
+        while True:
+            if delay > 0:
+                await asyncio.sleep(delay)
+
+            self._tell(actor=actor, message=message, sender=sender)
+            if not period:
+                break
+
+            delay = period
+
+    def _watch(self, actor: Union[Actor, ActorRef], other: Union[Actor, ActorRef]) -> None:
+        """Внутренний метод для наблюдения за актором."""
+        actor = self._validate_actor_ref(actor)
+
+        if actor not in self._actors:
+            raise ValueError(f'Actor does not exist: {actor}')
+
+        other = self._validate_actor_ref(other)
+        if other not in self._actors:
+            raise ValueError(f'Actor does not exist: {other}')
+
+        if actor == other:
+            raise ValueError(f'Actor cannot watch themselves: {actor}')
+
+        actor_ctx = self._actors[actor]
+        other_ctx = self._actors[other]
+        actor_ctx.watching.add(other)
+        other_ctx.watched_by.add(actor)
+
+    def _unwatch(self, actor: Union[Actor, ActorRef], other: Union[Actor, ActorRef]) -> None:
+        """Внутренний метод для прекращения наблюдения за актором."""
+        actor = self._validate_actor_ref(actor)
+        if actor not in self._actors:
+            raise ValueError(f'Actor does not exist: {actor}')
+
+        other = self._validate_actor_ref(other)
+        if actor == other:
+            raise ValueError(f'Actor cannot unwatch themselves: {actor}')
+
+        actor_ctx = self._actors[actor]
+        if other in actor_ctx.watching:
+            actor_ctx.watching.remove(other)
+
+        if other in self._actors:
+            other_ctx = self._actors[other]
+            if actor in other_ctx.watched_by:
+                other_ctx.watched_by.remove(actor)
+
+    async def _shutdown(self, timeout: Union[None, int, float] = None) -> None:
+        """Внутренний метод завершения работы системы."""
+        if self._actors:
+            for actor_ref in self.children:  # children propagate stop messages
+                self.stop(actor_ref)
+
+            lifecycle_tasks = [
+                task for task
+                in (actor_ctx.lifecycle for actor_ctx in self._actors.values())
+                if task is not None
+            ]
+
+            done, pending = await asyncio.wait(lifecycle_tasks, timeout=timeout)
+            for lifecycle_task in pending:
+                lifecycle_task.cancel()
+
+        self._is_stopped.set()
+
+    async def _actor_lifecycle_loop(self, actor: Actor, actor_ref: ActorRef, actor_ctx: '_ActorContext') -> None:
+        """Основной цикл жизни актора."""
+        try:
+            await actor.started()
+            actor_ctx.receiving_messages = True
+
+        except Exception as e:
+            log.exception('Exception raised while awaiting start of %s', actor_ref, exc_info=e)
+
+        while actor_ctx.receiving_messages:
+            sender, message = await actor_ctx.letterbox.get()
+            if isinstance(message, PoisonPill):
+                break
+
+            # --- Логика маршрутизации ---
+            # Проверяем, является ли сообщение маршрутизируемым.
+            # Это делается до вызова пользовательского `receive`.
+            message_handled_by_routing = False
+            if isinstance(message, dict) and message.get('action') == 'route_message':
+                try:
+                    # Даем актору возможность обработать маршрутизацию самостоятельно
+                    # (например, если у него своя логика для 'route_message')
+                    # Если метод _route_message_logic возвращает True, значит он обработал.
+                    # Мы предполагаем, что базовый Actor имеет этот метод.
+
+                    if hasattr(actor, '_route_message_logic'):
+                        # Вызываем напрямую, так как это вспомогательный метод
+                        message_handled_by_routing = await actor._route_message_logic(sender, message)
+                except Exception as e:
+                    log.error(f"Error in _route_message_logic for {actor_ref.path}: {e}")
+
+            # Если маршрутизация не обработала сообщение, передаём его в receive актора
+            if not message_handled_by_routing:
+                try:
+                    await actor.receive(sender, message)
+                except Exception as e:
+                    try:
+                        await actor.restarted(sender, message, e)
+                    except Exception as e:
+                        log.exception(f'Exception raised while awaiting restart of {actor_ref}', exc_info=e)
+            # --- Конец логики маршрутизации ---
+
+        actor_ctx.receiving_messages = False
+
+        children_stopping = []
+        for child in actor_ctx.children:
+            child_ctx = self._actors[child]
+            children_stopping.append(child_ctx.is_stopped.wait())
+            self.stop(child)
+
+        if children_stopping:
+            await asyncio.wait(children_stopping)
+
+        try:
+            await actor.stopped()
+
+        except Exception as e:
+            log.exception(f'Exception raised while awaiting stop of {actor_ref}', exc_info=e)
+
+        for other in actor_ctx.watched_by:
+            self._tell(other, Terminated(actor_ref), sender=None)
+            other_ctx = self._actors[other]
+            other_ctx.watching.remove(actor_ref)
+
+        for other in actor_ctx.watching:
+            other_ctx = self._actors[other]
+            other_ctx.watched_by.remove(actor_ref)
+
+        if actor_ctx.parent:
+            parent_ctx = self._actors[actor_ctx.parent]
+            parent_ctx.children.remove(actor_ref)
+        else:
+            self.children.remove(actor_ref)
+
+        while not actor_ctx.letterbox.empty():
+            sender, message = actor_ctx.letterbox.get_nowait()
+            if sender and sender != actor_ref:
+                deadletter = DeadLetter(actor_ref, message)
+                self._tell(sender, deadletter, sender=None)
+
+        actor_ctx.is_stopped.set()
+        del self._actors[actor_ref]
+
+    @staticmethod
+    def _validate_actor_ref(actor: Union[Actor, ActorRef]) -> ActorRef:
+        """Проверяет и возвращает ActorRef."""
+        if isinstance(actor, Actor):
+            actor = actor.actor_ref
+
+        if not isinstance(actor, ActorRef):
+            raise ValueError(f'Not an actor: {actor}')
+
+        return actor
+
+
+class _ActorContext:
+    """Контекст выполнения актора."""
+
+    def __init__(self, system: ActorSystem, actor_ref: ActorRef, parent: Optional[ActorRef]):
+        self.system: ActorSystem = system
+        self.actor_ref: ActorRef = actor_ref
+        self.parent: Optional[ActorRef] = parent
+        self.letterbox: asyncio.Queue = asyncio.Queue()
+        self.lifecycle: Optional[asyncio.Task] = None
+        self.watching: Set[ActorRef] = set()
+        self.watched_by: Set[ActorRef] = set()
+        self.children: List[ActorRef] = []
+        self.is_stopped: asyncio.Event = asyncio.Event()
+        self.receiving_messages: bool = False

actio-0.0.2/src/actio/messages.py

@@ -0,0 +1,23 @@
+# actio/messages.py
+# -*- coding: utf-8 -*-
+
+from typing import Any
+from dataclasses import dataclass
+
+from . import ActorRef
+
+
+@dataclass(frozen=True)
+class PoisonPill:
+    pass
+
+
+@dataclass(frozen=True)
+class DeadLetter:
+    actor: ActorRef
+    message: Any
+
+
+@dataclass(frozen=True)
+class Terminated:
+    actor: ActorRef

actio-0.0.2/src/actio/ref.py

@@ -0,0 +1,38 @@
+# actio/ref.py
+# -*- coding: utf-8 -*-
+
+from typing import Dict
+from typing import Any
+from typing import Optional
+
+from dataclasses import dataclass
+from dataclasses import field
+
+
+@dataclass(repr=False, eq=False, frozen=True)
+class ActorRef:
+    actor_id: str
+    path: str
+    name: str
+
+    def __str__(self):
+        return self.path
+
+    def __hash__(self):
+        return hash(self.actor_id)
+
+    def __repr__(self):
+        return self.path
+
+    def __eq__(self, other):
+        return isinstance(other, ActorRef) and self.actor_id == other.actor_id
+
+
+@dataclass
+class ActorDefinition:
+    name: str
+    cls: type
+    parent: Optional[str]
+    replicas: int = 1
+    minimal: int = 1
+    config: Dict[str, Any] = field(default_factory=dict)

actio-0.0.2/src/actio/registry.py

@@ -0,0 +1,130 @@
+# actio/registry.py
+# -*- coding: utf-8 -*-
+
+import logging
+import asyncio
+
+from typing import Dict
+from typing import Any
+from typing import Optional
+from typing import List
+
+from . import ActorRef
+from . import ActorDefinition
+
+from . import ActorSystem
+
+log = logging.getLogger('actio.registry')
+
+
+class ActorRegistry:
+    def __init__(self):
+        self._definitions: Dict[str, ActorDefinition] = {}
+
+    def actio(
+        self,
+        name: Optional[str] = None,
+        parent: Optional[str] = None,
+        replicas: int = 1,
+        minimal: int = 1,
+        config: Optional[Dict[str, Any]] = None
+    ):
+
+        def decorator(cls):
+            actor_name = name or cls.__name__
+            self._definitions[actor_name] = ActorDefinition(
+                name=actor_name,
+                cls=cls,
+                parent=parent,
+                replicas=replicas,
+                minimal=minimal,
+                config=config or {}
+            )
+            return cls
+        return decorator
+
+    async def build_actor_tree(
+        self,
+        system: ActorSystem,
+        root_name: str = 'MainTasks',
+        timeout: float = 5.0
+    ) -> Dict[str, ActorRef]:
+        refs = {}
+        actor_instances = {}
+
+        # Создаем корневые акторы через систему
+        for defn in self._definitions.values():
+            if defn.parent is None:
+                actor_instance = defn.cls()
+                refs[defn.name] = system.create(actor_instance, name=defn.name)
+                actor_instances[defn.name] = actor_instance
+
+        # Создаем дочерние акторы через родительские ЭКЗЕМПЛЯРЫ акторов
+        created = set(refs.keys())
+        while len(created) < len(self._definitions):
+            for defn in self._definitions.values():
+                if defn.name not in created and defn.parent in created:
+                    parent_instance = actor_instances[defn.parent]  # Экземпляр актора-родителя
+                    actor_instance = defn.cls()
+
+                    # создаем через parent_instance.create(), а не parent_ref.create()
+                    child_ref = parent_instance.create(actor_instance, name=defn.name)
+                    refs[defn.name] = child_ref
+                    actor_instances[defn.name] = actor_instance
+
+                    # Сохраняем ссылку в родителе
+                    if hasattr(parent_instance, 'actors') and isinstance(parent_instance.actors, dict):
+                        parent_instance.actors[defn.name] = child_ref
+
+                    created.add(defn.name)
+
+        start_time = asyncio.get_event_loop().time()
+        while asyncio.get_event_loop().time() - start_time < timeout:
+            all_started = True
+            for actor_instance in actor_instances.values():
+                if (
+                    hasattr(actor_instance, '_context')
+                    and actor_instance._context
+                    and not actor_instance._context.receiving_messages
+                ):
+                    all_started = False
+                    break
+
+            if all_started:
+                break
+            await asyncio.sleep(0.1)
+
+        return refs
+
+    def get_actor_graph(self) -> Dict[Optional[str], List[str]]:
+        graph = {}
+        for defn in self._definitions.values():
+            if defn.parent not in graph:
+                graph[defn.parent] = []
+            graph[defn.parent].append(defn.name)
+
+        return graph
+
+    def print_actor_tree(self):
+        """Печатает дерево акторов в консоль"""
+        graph = self.get_actor_graph()
+
+        def print_node(parent: Optional[str], level: int = 0):
+            indent = "  " * level
+            if parent in graph:
+                for child in graph[parent]:
+                    defn = self._definitions[child]
+                    log.warning(f"{indent}├── {child} (replicas={defn.replicas}, minimal={defn.minimal})")
+                    print_node(child, level + 1)
+            elif parent is None:
+                for root in graph[None]:
+                    defn = self._definitions[root]
+                    log.warning(f"┌── {root} (replicas={defn.replicas}, minimal={defn.minimal})")
+                    print_node(root, 1)
+
+        log.warning("Actor System Tree:")
+        print_node(None)
+
+
+registry = ActorRegistry()
+actio = registry.actio