pyroflow 0.1.6__tar.gz → 0.2.0__tar.gz

{pyroflow-0.1.6 → pyroflow-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyroflow
-Version: 0.1.6
+Version: 0.2.0
 Summary: Conversation-oriented Pyrogram extension with per-update listeners and multi-session coordination
 Project-URL: Homepage, https://github.com/eeeob/pyroflow
 Project-URL: Bug Tracker, https://github.com/eeeob/pyroflow/issues
@@ -13,7 +13,6 @@ Classifier: Framework :: AsyncIO
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
@@ -22,16 +21,21 @@ Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Communications :: Chat
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
-Requires-Python: >=3.9
+Requires-Python: >=3.10
 Requires-Dist: cachetools
 Requires-Dist: kurigram>=2.2.0
 Requires-Dist: sortedcontainers==2.4.0
-Requires-Dist: typing-extensions>=4.6.0; python_version < '3.10'
+Requires-Dist: typing-extensions>=4.6.0; python_version < '3.13'
 Provides-Extra: dev
 Requires-Dist: hatch<=1.16.5; extra == 'dev'
 Requires-Dist: twine<=6.2.0; extra == 'dev'
 Provides-Extra: redis
 Requires-Dist: redis>=4.2.0; extra == 'redis'
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
+Requires-Dist: pytest>=7.0; extra == 'test'
+Requires-Dist: redis>=4.2.0; extra == 'test'
+Requires-Dist: tomli; (python_version < '3.11') and extra == 'test'
 Description-Content-Type: text/markdown
 
 # pyroflow
@@ -72,7 +76,7 @@ pyroflow solves all three problems:
 
 ## Installation
 
-**Minimum requirements:** Python 3.9+
+**Minimum requirements:** Python 3.10+
 
 ```
 pip install pyroflow          # core
@@ -233,10 +237,10 @@ client.run()
 A `UpdateHistory` records which handlers ran successfully for each update. This enables features like `back` buttons that replay or inspect previous processing steps.
 
 ```python
-from pyroflow import Client, MessageHistory
+from pyroflow import Client, CallbackQueryHistory
 
 client = Client("my_session")
-client.register_history(MessageHistory())
+client.register_history(CallbackQueryHistory())
 
 client.run()
 ```
@@ -248,7 +252,7 @@ They can also be removed at runtime:
 ```python
 await client.unregister_listener(Message)
 await client.unregister_coordinated(Message)
-await client.unregister_history(Message)
+await client.unregister_history(CallbackQueryHistory)
 ```
 
 ---

{pyroflow-0.1.6 → pyroflow-0.2.0}/README.md

@@ -36,7 +36,7 @@ pyroflow solves all three problems:
 
 ## Installation
 
-**Minimum requirements:** Python 3.9+
+**Minimum requirements:** Python 3.10+
 
 ```
 pip install pyroflow          # core
@@ -197,10 +197,10 @@ client.run()
 A `UpdateHistory` records which handlers ran successfully for each update. This enables features like `back` buttons that replay or inspect previous processing steps.
 
 ```python
-from pyroflow import Client, MessageHistory
+from pyroflow import Client, CallbackQueryHistory
 
 client = Client("my_session")
-client.register_history(MessageHistory())
+client.register_history(CallbackQueryHistory())
 
 client.run()
 ```
@@ -212,7 +212,7 @@ They can also be removed at runtime:
 ```python
 await client.unregister_listener(Message)
 await client.unregister_coordinated(Message)
-await client.unregister_history(Message)
+await client.unregister_history(CallbackQueryHistory)
 ```
 
 ---

{pyroflow-0.1.6 → pyroflow-0.2.0}/pyproject.toml

@@ -7,7 +7,7 @@ build-backend = "hatchling.build"
 name = "pyroflow"
 dynamic = ["version"]
 description = "Conversation-oriented Pyrogram extension with per-update listeners and multi-session coordination"
-requires-python = ">=3.9"
+requires-python = ">=3.10"
 authors = [{ name = "Abdullah", email = "aldheeb01@gmail.com" }]
 readme = "README.md"
 license = { text = "MIT" }
@@ -27,7 +27,6 @@ classifiers = [
     "Intended Audience :: Developers",
     "License :: OSI Approved :: MIT License",
     "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.9",
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
@@ -43,7 +42,7 @@ dependencies = [
     "cachetools", 
     "sortedcontainers==2.4.0", 
     "kurigram>=2.2.0", 
-    "typing_extensions>=4.6.0; python_version < '3.10'",
+    "typing_extensions>=4.6.0; python_version < '3.13'",
 ]
 
 
@@ -62,6 +61,13 @@ redis = [
     "redis>=4.2.0",
 ]
 
+test = [
+    "pytest>=7.0",
+    "pytest-asyncio>=0.23",
+    "redis>=4.2.0",
+    "tomli; python_version < '3.11'",
+]
+
 
 [tool.hatch.build.targets.sdist]
 exclude = [
@@ -78,3 +84,11 @@ allow-direct-references = true
 [tool.hatch.build.targets.wheel]
 ignore-vcs = true
 packages = ["pyroflow"]
+
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+filterwarnings = [
+    "ignore::DeprecationWarning",
+]

pyroflow-0.2.0/pyroflow/__meta__.py

@@ -0,0 +1 @@
+__version__ = "0.2.0"

pyroflow-0.2.0/pyroflow/enums.py

@@ -0,0 +1,21 @@
+import sys
+
+if sys.version_info >= (3, 11):
+    from enum import StrEnum
+else:
+    from enum import Enum
+    
+    class StrEnum(str, Enum):
+        def _generate_next_value_(self, *args):
+            return self.lower()
+
+from enum import IntEnum, auto
+
+
+class UpdateLockState(IntEnum):
+    PROCESSING = 0
+    HANDLED    = 1
+
+class DuplicatePolicy(StrEnum):
+    REJECT = auto()
+    REPLACE = auto()

{pyroflow-0.1.6 → pyroflow-0.2.0}/pyroflow/listener_coordinator/listener_coordinator.py

@@ -1,18 +1,11 @@
 from abc import ABC, abstractmethod
-from typing import Optional, Union, Tuple, TYPE_CHECKING
+from typing import Optional, Union, Tuple, TypeAlias, TYPE_CHECKING
 
 
 from ..utils.typings import AsyncLockProto
 from ..typings import ListenerCoordinatorIdT
 from ..models import ListenerKey
 
-import sys
-
-if sys.version_info >= (3, 10):
-    from typing import TypeAlias
-else:
-    from typing_extensions import TypeAlias
-
 if TYPE_CHECKING:
     from ..update_listener import UpdateListener
 

{pyroflow-0.1.6 → pyroflow-0.2.0}/pyroflow/models.py

@@ -8,7 +8,6 @@ import asyncio
 import time
 
 
-
 @dataclass(frozen=True, slots=True, eq=False)
 class ListenerKey:
     chat_id: int
@@ -18,11 +17,11 @@ class ListenerKey:
     @property
     def to_tuple(self) -> Tuple[int, Optional[int], Optional[int]]:
         return (
-            self.chat_id, 
-            self.user_id, 
+            self.chat_id,
+            self.user_id,
             self.message_id
         )
-    
+
 
     def sub_keys(self, min_dep: int = 1) -> Generator["ListenerKey", None, None]:
         keys = self.to_tuple
@@ -32,26 +31,26 @@ class ListenerKey:
             yield ListenerKey(
                 *keys[:i]
             )
-    
+
     def __hash__(self):
         return hash(self.to_tuple)
-    
+
     def __eq__(self, value):
         return isinstance(value, ListenerKey) and self.to_tuple == value.to_tuple
 
 @dataclass(slots=True)
 class ListenerModel:
     key: ListenerKey
-    meta: Optional[JsonValueT] = None 
+    meta: Optional[JsonValueT] = None
     future: asyncio.Future = field(default_factory=asyncio.Future)
 
 
     def resolve(self, update) -> None:
         self.future.set_result(update)
-    
+
     def set_exc(self, exc: Exception) -> None:
         self.future.set_exception(exc)
-    
+
     def done(self) -> bool:
         return self.future.done()
 

{pyroflow-0.1.6 → pyroflow-0.2.0}/pyroflow/typings.py

@@ -1,11 +1,4 @@
-from typing import Union, Tuple
-
-import sys
-
-if sys.version_info >= (3, 10):
-    from typing import TypeAlias
-else:
-    from typing_extensions import TypeAlias
+from typing import Union, Tuple, TypeAlias
 
 UpdateCoordinatorKeyT: TypeAlias = Tuple[Union[int, str], ...]
 UpdateHistoryKeyT = UpdateCoordinatorKeyT

{pyroflow-0.1.6 → pyroflow-0.2.0}/pyroflow/update_coordinated/callback_query_coordinated.py

@@ -28,4 +28,4 @@ class CallbackQueryCoordinated(UpdateCoordinated[CallbackQuery]):
         return (update.id, )
     
     async def _is_coordinatable(self, update):
-        True
+        return True

pyroflow-0.2.0/pyroflow/update_history/message_history.py

@@ -0,0 +1,42 @@
+from typing import TYPE_CHECKING
+
+from ..types import Message
+from .update_history import UpdateHistory
+
+
+class MessageHistory(UpdateHistory[Message]):
+    __update_type__ = Message
+
+    if not TYPE_CHECKING:
+        def __init__(
+            self,
+            store_factory = None,
+            is_recordable_func = None,
+            extract_key_func = None,
+            extract_data_func = None,
+            **kw
+            ):
+
+            if is_recordable_func is None:
+                is_recordable_func = self._is_recordable
+
+            if extract_key_func is None:
+                extract_key_func = self._extract_key
+
+            if extract_data_func is None:
+                extract_data_func = self._extract_data
+
+            super().__init__(store_factory, is_recordable_func, extract_key_func, extract_data_func, **kw)
+
+    async def _is_recordable(self, update):
+        return update.chat is not None
+
+    async def _extract_key(self, update):
+        return (
+            update.chat.id,
+            getattr(update.from_user, "id", None),
+            update.id,
+        )
+
+    async def _extract_data(self, update):
+        return update.text

{pyroflow-0.1.6 → pyroflow-0.2.0}/pyroflow/utils/async_tools.py

@@ -10,11 +10,34 @@ import functools
 import logging
 import contextvars
 import inspect
+import traceback
 
 
 log = logging.getLogger(__file__)
 
 
+def _log_exc(
+    header: Optional[str],
+    caller_stack: List[traceback.FrameSummary],
+    exc: BaseException,
+    index: Optional[int] = None,
+) -> None:
+    exc_trace = traceback.format_exception(type(exc), exc, exc.__traceback__)
+    caller_trace = traceback.format_list(caller_stack)
+
+    if header is None:
+        header = ""
+
+    if index is not None:
+        header = f"{header} [awaitable index={index}]" if header else f"[awaitable index={index}]"
+
+    log.error(
+        "%s\n%s",
+        header,
+        "".join(caller_trace) + "".join(exc_trace)
+    )
+
+
 @overload
 async def to_thread(
     func: Callable[_P, _T],
@@ -37,25 +60,26 @@ async def to_thread(
     func,
     *args,
     executor = None,
-    log_exc = True, 
-    return_exc = False, 
+    log_exc = True,
+    return_exc = False,
     **kwargs,
     ):
-    
+    caller_stack = traceback.extract_stack()[:-1]
+
     loop = asyncio.get_running_loop()
     ctx = contextvars.copy_context()
     func = functools.partial(ctx.run, func, *args, **kwargs)
-    
-    
+
+
     try:
         return await loop.run_in_executor(executor, func)
     except Exception as e:
         if log_exc:
-            log.exception("error in to_thread")
-        
+            _log_exc("error in to_thread", caller_stack, e)
+
         if return_exc:
             return e
-        
+
         raise
 
 
@@ -77,12 +101,14 @@ async def gather_helper(
     log_exc = True,
     ):
 
+    caller_stack = traceback.extract_stack()[:-1]
+
     results = await asyncio.gather(*flat_cont(coros), return_exceptions=return_exc)
 
     if log_exc:
-        for r in results:
+        for i, r in enumerate(results):
             if is_exception(r):
-                log.error("error in gather_helper", exc_info=r)
+                _log_exc("error in gather_helper", caller_stack, r, index=i)
 
     return results
 
@@ -130,15 +156,24 @@ async def safe_await(
     log_exc = True,
     ):
 
+    caller_stack = traceback.extract_stack()[:-1]
+
     results = []
+    flat_coros = flat_cont(coros)
+    is_multi = len(flat_coros) > 1
 
-    for coro in flat_cont(coros):
+    for i, coro in enumerate(flat_coros):
         try:
             result = await coro
         except Exception as e:
             if log_exc:
-                log.exception("Error in safe_await")
-                
+                _log_exc(
+                    "error in safe_await",
+                    caller_stack,
+                    e,
+                    index=i if is_multi else None,
+                )
+
             result = e
 
         if is_exception(result):
@@ -172,21 +207,21 @@ async def maybe_awaitable(
 async def maybe_awaitable(
     awaitable_or_callable,
     *args,
-    executor = None, 
-    return_exc = False, 
+    executor = None,
+    return_exc = False,
     log_exc = True,
     **kwargs,
 ):
-    
+
     if inspect.isawaitable(awaitable_or_callable):
         if args or kwargs:
             raise TypeError(
                 "Cannot pass args/kwargs to an already-created awaitable"
             )
         return await safe_await(
-            awaitable_or_callable, 
-            return_exc=return_exc, 
-            log_exc=log_exc, 
+            awaitable_or_callable,
+            return_exc=return_exc,
+            log_exc=log_exc,
         )
     elif iscoroutinefunction_wrapped(awaitable_or_callable):
         return await safe_await(
@@ -209,12 +244,9 @@ async def maybe_awaitable(
         )
 
 
-
-
-
 __all__ = [
-    "to_thread", 
-    "gather_helper", 
-    "safe_await", 
+    "to_thread",
+    "gather_helper",
+    "safe_await",
     "maybe_awaitable"
-]
+]

{pyroflow-0.1.6 → pyroflow-0.2.0}/pyroflow/utils/classes.py

@@ -1,18 +1,12 @@
 from abc import ABC
-from typing import Generic, Type
+from typing import Generic, Type, ClassVar
 
 from pyrogram.types import Update as PyroUpdate
 from .typings import UpdateType
 
 import asyncio
-import sys
 
 
-if sys.version_info >= (3, 10):
-    from typing import ClassVar
-else:
-    from typing_extensions import ClassVar
-
 class AsyncioLock(asyncio.Lock):
     async def release(self):
         return super().release()

{pyroflow-0.1.6 → pyroflow-0.2.0}/pyroflow/utils/typings.py

@@ -1,19 +1,15 @@
 from typing import (
-    Collection as TCollection, Generator, Union, Reversible, 
-    Sequence, AbstractSet, Mapping, List, Any, Dict, 
-    Callable, Coroutine, Awaitable, TypeVar, 
-    Literal, TYPE_CHECKING, 
+    Collection as TCollection, Generator, Union, Reversible,
+    Sequence, AbstractSet, Mapping, List, Any, Dict,
+    Coroutine, Awaitable, TypeVar,
+    Literal, TYPE_CHECKING,
+    ParamSpec, TypeAlias, Protocol, Callable,
 )
 
 from enum import Enum
 
 import sys
 
-if sys.version_info >= (3, 10):
-    from typing import ParamSpec, TypeAlias, Protocol
-else:
-    from typing_extensions import ParamSpec, TypeAlias, Protocol
-
 if sys.version_info >= (3, 11):
     from enum import EnumType
 else:
@@ -74,15 +70,15 @@ UpdateType = TypeVar("UpdateType", bound=PyroUpdate)
 
 
 __all__ = (
-    "Container", 
-    "NestedContainer", 
-    "NotContainer", 
-    "MaybeAwaitable", 
-    "Number", 
-    "MaybeCoroutineCallable", 
-    "AsyncLockProto", 
-    "JsonValueT", 
-    "UpdateType", 
-    "_P", "_T", "_CT", 
-    "_True", "_False", 
+    "Container",
+    "NestedContainer",
+    "NotContainer",
+    "MaybeAwaitable",
+    "Number",
+    "MaybeCoroutineCallable",
+    "AsyncLockProto",
+    "JsonValueT",
+    "UpdateType",
+    "_P", "_T", "_CT",
+    "_True", "_False",
 )

{pyroflow-0.1.6 → pyroflow-0.2.0}/pyroflow/utils/validate_tools.py

@@ -6,10 +6,8 @@ import inspect
 
 if sys.version_info >= (3, 13):
     from typing import TypeIs
-elif sys.version_info >= (3, 10):
-    from typing_extensions import TypeIs
 else:
-    from typing_extensions import TypeGuard as TypeIs
+    from typing_extensions import TypeIs
 
 from .typings import Container, NotContainer, _T
 

pyroflow-0.2.0/tests/conftest.py

@@ -0,0 +1,70 @@
+"""Shared fixtures and object factories for the pyroflow test suite.
+
+Importing ``pyroflow`` here is deliberate and must happen before any test
+runs: ``@patch_cls`` monkey-patches Pyrogram's ``Client``, ``Dispatcher``,
+``Message`` and ``CallbackQuery`` in-place at import time, and the whole
+suite relies on that global patch being active.
+"""
+
+from types import SimpleNamespace
+
+import pyroflow  # noqa: F401 — activates the @patch_cls global monkey-patch
+import pytest
+
+from pyrogram.types import Message, CallbackQuery, Chat, User
+from pyrogram.enums import ChatType
+
+
+def make_message(chat_id=100, user_id=7, message_id=5, **overrides):
+    """Build a minimal, listenable :class:`Message` instance.
+
+    Defaults produce a private, incoming, non-service message that
+    ``MessageListener._is_listenable`` accepts. Any field can be
+    overridden via keyword to exercise edge cases.
+    """
+    msg = Message(
+        id=message_id,
+        chat=Chat(id=chat_id, type=ChatType.PRIVATE),
+        from_user=User(id=user_id, is_self=False),
+    )
+    for key, value in overrides.items():
+        setattr(msg, key, value)
+    return msg
+
+
+def make_callback_query(chat_id=100, user_id=7, message_id=5, data="cb", **overrides):
+    """Build a minimal :class:`CallbackQuery` whose ``message`` is listenable."""
+    cbq = CallbackQuery(
+        id="cbq-1",
+        from_user=User(id=user_id, is_self=False),
+        chat_instance="chat-instance",
+        message=make_message(chat_id, user_id, message_id),
+        data=data,
+    )
+    for key, value in overrides.items():
+        setattr(cbq, key, value)
+    return cbq
+
+
+@pytest.fixture
+def message_factory():
+    return make_message
+
+
+@pytest.fixture
+def callback_factory():
+    return make_callback_query
+
+
+@pytest.fixture
+def raw_message_factory():
+    """A ``Message`` carrying a ``raw.peer_id`` for coordinator key extraction."""
+
+    def _factory(chat_id=100, user_id=7, message_id=5, peer_channel_id=100):
+        msg = make_message(chat_id, user_id, message_id)
+        # get_peer_id() understands raw PeerChannel/PeerUser objects; a
+        # SimpleNamespace with the right attribute name is enough here.
+        msg.raw = SimpleNamespace(peer_id=SimpleNamespace(channel_id=peer_channel_id))
+        return msg
+
+    return _factory