parsek-cdp 0.1.0__py3-none-any.whl

parsek_cdp/cdp/mixins/event.py

@@ -0,0 +1,78 @@
+"""Base machinery for CDP events.
+
+Every event is a :class:`DataType` (so it deserializes from the ``params`` of a
+protocol notification) plus a class-level handler registry.  Handlers can be
+registered directly on the event class -- without ever instantiating it::
+
+    @Network.RequestWillBeSent.add_handler
+    async def on_request(event: Network.RequestWillBeSent) -> None:
+        print(event.request.url)
+
+The :data:`EVENT_REGISTRY` maps the protocol method name
+(``"Domain.eventName"``) to its event class so a connection can locate and
+deserialize an incoming notification.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, ClassVar, List, TypeVar
+
+from .datatype import DataType
+
+# "Domain.eventName" -> Event subclass
+EVENT_REGISTRY: dict[str, type["Event"]] = {}
+
+EventHandler = Callable[["Event"], Any]
+
+E = TypeVar("E", bound="Event")
+
+
+def register_event(method: str) -> Callable[[type[E]], type[E]]:
+    """Class decorator binding ``cls`` to its protocol method name.
+
+    Returns the class unchanged (and with its concrete type preserved, so type
+    checkers still see the event's own fields).
+    """
+
+    def deco(cls: type[E]) -> type[E]:
+        cls.EVENT_METHOD = method
+        EVENT_REGISTRY[method] = cls
+        return cls
+
+    return deco
+
+
+class Event(DataType):
+    """Base class for all protocol events.
+
+    ``EVENT_METHOD`` is intentionally upper-case: some protocol events carry a
+    parameter literally named ``method``, and a lower-case class attribute would
+    be picked up by ``@dataclass`` as that field's default value.
+    """
+
+    #: Protocol method name, e.g. ``"Network.requestWillBeSent"``.
+    EVENT_METHOD: ClassVar[str] = ""
+    #: Handlers registered directly on the class (global, connection-agnostic).
+    _global_handlers: ClassVar[List[EventHandler]]
+
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        super().__init_subclass__(**kwargs)
+        cls._global_handlers = []
+
+    @classmethod
+    def add_handler(cls, handler: EventHandler) -> EventHandler:
+        """Register ``handler`` for every occurrence of this event.
+
+        Usable as a decorator.  Works without instantiating the class.
+        """
+        cls._global_handlers.append(handler)
+        return handler
+
+    @classmethod
+    def remove_handler(cls, handler: EventHandler) -> None:
+        cls._global_handlers.remove(handler)
+
+    @classmethod
+    def parse(cls, params: dict[str, Any]) -> "Event":
+        """Deserialize the ``params`` payload of a notification."""
+        return cls.from_json(params or {})

parsek_cdp/cdp/mixins/namespace.py

@@ -0,0 +1,31 @@
+"""Attach classes defined in modules onto a class, turning it into a namespace.
+
+Used by features so the feature *class* doubles as its namespace::
+
+    from parsek_cdp.features import RequestListener
+    RequestListener.RequestSent     # event
+    RequestListener.RequestData     # wire type
+    RequestListener.Request         # view type
+
+Only classes *defined in* the given modules are attached (cross-module imports
+are skipped via ``__module__``), and existing attributes are never overwritten.
+
+(CDP domains use a different mechanism -- module-level ``import *`` -- because a
+domain's public handle is its module, not a class.)
+"""
+
+from __future__ import annotations
+
+from types import ModuleType
+
+
+def attach_namespace(target_cls: type, *modules: ModuleType) -> None:
+    """Attach every class defined in ``modules`` onto ``target_cls`` by name."""
+    for module in modules:
+        for name, obj in vars(module).items():
+            if name.startswith("_") or not isinstance(obj, type):
+                continue
+            if obj.__module__ != module.__name__:
+                continue  # imported from elsewhere, not defined here
+            if not hasattr(target_cls, name):
+                setattr(target_cls, name, obj)

parsek_cdp/cdp/network/__init__.py

@@ -0,0 +1,15 @@
+"""The Network CDP domain (generated).
+
+Importing ``Network`` from ``parsek_cdp.cdp`` gives a namespace with this
+domain's events and types as attributes (``Network.SomeEvent`` /
+``Network.SomeType``); commands run on a target via ``page.cdp.Network``.
+"""
+from . import events, functions, types
+from .functions import Network
+from .events import *  # noqa: F401,F403 -- expose events on the namespace
+from .types import *  # noqa: F401,F403 -- expose types on the namespace
+
+#: Protocol domain name (used by features that declare ``domains=(Network,)``).
+DOMAIN = "Network"
+
+__all__ = ["events", "functions", "types", "Network", "DOMAIN"]