chromedeveloperprotocol-client 0.1.0__py3-none-any.whl

cdp/generator/client_generator.py

@@ -0,0 +1,246 @@
+from jinja2_strcase import StrcaseExtension
+from jinja2 import Environment
+
+DOMAINS_TEMPLATE = """\
+\"\"\"CDP Domains library for interacting with various domains.\"\"\"
+from typing import TYPE_CHECKING, Any, Dict, Optional
+
+if TYPE_CHECKING:
+    from .service import Client
+    {% for domain in domains %}
+    from .protocol.{{ domain['domain'] | to_snake }}.service import {{ domain['domain'] }}
+    {% endfor %}
+
+class Domains:
+    \"\"\"
+    Collection of all CDP domains.
+    
+    This class acts as a container for all available CDP domain services. 
+    Each domain is lazily initialized when first accessed.
+    \"\"\"
+    def __init__(self, client: "Client"):
+        \"\"\"
+        Initialize the Domains container.
+        
+        Args:
+            client ("Client"): The parent CDP client instance.
+        \"\"\"
+        self.client = client
+        {% for domain in domains %}
+        self._{{ domain['domain'] | to_snake }}: Optional['{{ domain['domain'] }}'] = None
+        {% endfor %}
+
+    {% for domain in domains %}
+    @property
+    def {{ domain['domain'] | to_snake }}(self) -> '{{ domain['domain'] }}':
+        \"\"\"
+        {% if domain['description'] %}{{ domain['description'] | replace("\\n", " ") }}{% else %}Access the {{ domain['domain'] }} domain.{% endif %}
+        \"\"\"
+        if self._{{ domain['domain'] | to_snake }} is None:
+            from .protocol.{{ domain['domain'] | to_snake }}.service import {{ domain['domain'] }}
+            self._{{ domain['domain'] | to_snake }} = {{ domain['domain'] }}(client=self.client)
+        return self._{{ domain['domain'] | to_snake }}
+
+    {% endfor %}
+"""
+
+SERVICE_TEMPLATE = """\
+from typing import Optional, Dict, Any, Callable,Annotated, List
+from operator import add
+import websockets
+import asyncio
+import logging
+import json
+
+from .domains import Domains
+from .generator.service import CDPGenerator
+
+class Client(Domains):
+    \"\"\"
+    Core client for interacting with Chrome DevTools Protocol (CDP).
+    
+    This class provides a high-level API to send commands and listen for events across
+    various CDP domains. It manages the underlying WebSocket connection and dispatches
+    messages to the appropriate handlers.
+    
+    Attributes:
+        url (str): The WebSocket URL of the remote debugging target.
+        ws (websockets.ClientConnection): The active WebSocket connection.
+        listen_task (asyncio.Task): Background task processing incoming CDP messages.
+        id_counter (int): Counter for generating unique request IDs.
+        pending_requests (Dict[int, asyncio.Future]): Tracks outstanding requests by ID.
+        event_handlers (Dict[str, List[Callable]]): Registered callbacks for CDP events.
+    \"\"\"
+    def __init__(self, url: str, refresh: bool = False):
+        \"\"\"
+        Initialize the CDP Client.
+        
+        Args:
+            url (str): WebSocket debugger URL.
+            refresh (bool): If True, regenerates the CDP protocol definitions on initialization.
+        \"\"\"
+        super().__init__(self)
+        self.url = url
+        self.ws :Optional[websockets.ClientConnection] = None
+        self.listen_task :Optional[asyncio.Task] = None
+        self.id_counter: Annotated[int, add] = 0
+        self.pending_requests: Dict[int, asyncio.Future] = {}
+        self.event_handlers: Dict[str, List[Callable[[Any, Optional[str]], None]]] = {}
+        
+        if refresh:
+            self.refresh()
+
+    async def __aenter__(self):
+        \"\"\"Connect to the WebSocket and start the background listener.\"\"\"
+        self.ws = await websockets.connect(self.url,max_size=100*1024*1024)
+        self.listen_task = asyncio.create_task(self.listen())
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        \"\"\"Cancel the listener, clear pending requests, and close the WebSocket.\"\"\"
+        for future in self.pending_requests.values():
+            if not future.done():
+                future.set_exception(Exception("WebSocket connection closed"))
+        self.pending_requests.clear()
+        if self.listen_task:
+            try:
+                self.listen_task.cancel()
+                await self.listen_task
+            except asyncio.CancelledError:
+                pass
+            finally:
+                self.listen_task = None
+        if self.ws:
+            await self.ws.close()
+            self.ws = None
+
+    async def send(self, method: str, params: Optional[dict] = None,session_id: Optional[str] = None) -> Any:
+        \"\"\"
+        Send a CDP command and wait for the result.
+        
+        Args:
+            method (str): The CDP method name (e.g., 'Page.navigate').
+            params (dict, optional): Parameters for the method.
+            session_id (str, optional): Target session ID for flat protocol usage.
+            
+        Returns:
+            Any: The 'result' object from the CDP response.
+            
+        Raises:
+            Exception: If the CDP returns an error or the connection is lost.
+        \"\"\"
+        self.id_counter+=1
+        future = asyncio.Future()
+        self.pending_requests[self.id_counter] = future
+        
+        try:
+            message = {"id": self.id_counter, "method": method, "params": params or {}}
+            if session_id:
+                message['sessionId'] = session_id
+            await self.ws.send(json.dumps(message))
+            return await future
+        except Exception as e:
+            self.pending_requests.pop(self.id_counter, None)
+            raise e
+
+    def on(self, event: str, callback: Callable[[Any, Optional[str]], None]) -> None:
+        \"\"\"
+        Register an event handler. Alias for `Client.register`.
+        
+        Args:
+            event (str): The CDP event name (e.g., 'Page.loadEventFired').
+            callback (callable): Function called with (params, session_id).
+        \"\"\"
+        self.register(event, callback)
+
+    def register(self, event: str, callback: Callable[[Any, Optional[str]], None]) -> None:
+        \"\"\"
+        Register a handler for a specific CDP event.
+        
+        Args:
+            event (str): The CDP event name.
+            callback (callable): Function called with (params, session_id).
+        \"\"\"
+        if event not in self.event_handlers:
+            self.event_handlers[event] = []
+        self.event_handlers[event].append(callback)
+
+    def unregister(self, event: str) -> None:
+        \"\"\"
+        Unregister all handlers for a specific CDP event.
+        
+        Args:
+            event (str): The CDP event name.
+        \"\"\"
+        if event in self.event_handlers:
+            del self.event_handlers[event]
+    
+    def refresh(self):
+        \"\"\"
+        Refresh the CDP protocol definitions by fetching latest schemas and 
+        regenerating the client source code on disk.
+        \"\"\"
+        generator = CDPGenerator()
+        generator.generate()
+
+    async def listen(self):
+        \"\"\"
+        Internal background loop that receives messages from the WebSocket.
+        Dispatches responses to pending request futures and events to registered handlers.
+        \"\"\"
+        while True:
+            try:
+                message = await self.ws.recv()
+                data = json.loads(message)
+                if "id" in data:
+                    # Method
+                    request_id=data["id"]
+                    logging.debug(f"Received method response: {data}")
+                    if request_id not in self.pending_requests:
+                        continue
+                    future = self.pending_requests.pop(request_id)
+                    if not future.done():
+                        if "error" in data:
+                            future.set_exception(Exception(data.get("error")))
+                        else:
+                            future.set_result(data.get("result"))
+                elif 'method' in data:
+                    # Event
+                    method=data.get("method")
+                    params = data.get("params", {})
+                    session_id=data.get("sessionId")
+                    logging.debug(f"Received event: {data}")
+                    if method not in self.event_handlers:
+                        continue
+                    
+                    handlers = self.event_handlers[method]
+                    for handler in handlers:
+                        try:
+                            if asyncio.iscoroutinefunction(handler):
+                                asyncio.create_task(handler(params,session_id))
+                            else:
+                                handler(params,session_id)
+                        except Exception as e:
+                            logging.error(f"Error in event handler for {method}: {e}")
+                            continue
+            except websockets.exceptions.ConnectionClosed:
+                logging.info("CDP WebSocket connection closed")
+                break
+            except Exception as e:
+                logging.error(f"Error in CDP listen loop: {e}")
+                break
+"""
+
+class ClientGenerator:
+    def __init__(self, protocol_package: str, package_name: str):
+        self.env=Environment(trim_blocks=True,lstrip_blocks=True,extensions=[StrcaseExtension])
+        self.protocol_package = protocol_package
+        self.package_name = package_name
+
+    def generate_domains(self, domains: list[dict]):
+        template = self.env.from_string(DOMAINS_TEMPLATE)
+        return template.render(domains=domains, protocol_package=self.protocol_package).strip()
+
+    def generate_service(self):
+        template = self.env.from_string(SERVICE_TEMPLATE)
+        return template.render().strip()

cdp/generator/constant.py

@@ -0,0 +1,4 @@
+
+BROWSER_PROTOCOL_URL = "https://raw.githubusercontent.com/ChromeDevTools/devtools-protocol/refs/heads/master/json/browser_protocol.json"
+
+JS_PROTOCOL_URL = "https://raw.githubusercontent.com/ChromeDevTools/devtools-protocol/refs/heads/master/json/js_protocol.json"

cdp/generator/domain_generator.py

@@ -0,0 +1,149 @@
+from jinja2 import Environment
+from jinja2_strcase import StrcaseExtension
+from .method_generator import MethodGenerator
+from .event_generator import EventGenerator
+
+METHODS_SERVICE_TEMPLATE = """\
+\"\"\"CDP {{ domain_name }} Domain Methods\"\"\"
+{% for import_ in imports %}
+{{ import_ }}
+{% endfor %}
+
+if TYPE_CHECKING:
+    from ....service import Client
+
+class {{ class_name }}:
+    \"\"\"
+    Methods for the {{ domain_name }} domain.
+    \"\"\"
+    def __init__(self, client: "Client"):
+        \"\"\"
+        Initialize the {{ domain_name }} methods.
+        
+        Args:
+            client ("Client"): The parent CDP client instance.
+        \"\"\"
+        self.client = client
+
+    {% for implementation in method_implementations %}
+    {{ implementation | indent(4) }}
+    {% endfor %}
+"""
+
+EVENTS_SERVICE_TEMPLATE = """\
+\"\"\"CDP {{ domain_name }} Domain Events\"\"\"
+{% for import_ in imports %}
+{{ import_ }}
+{% endfor %}
+
+if TYPE_CHECKING:
+    from ....service import Client
+
+class {{ class_name }}:
+    \"\"\"
+    Events for the {{ domain_name }} domain.
+    \"\"\"
+    def __init__(self, client: "Client"):
+        \"\"\"
+        Initialize the {{ domain_name }} events.
+        
+        Args:
+            client ("Client"): The parent CDP client instance.
+        \"\"\"
+        self.client = client
+
+    {% for implementation in event_implementations %}
+    {{ implementation | indent(4) }}
+    {% endfor %}
+"""
+
+DOMAIN_SERVICE_TEMPLATE = """\
+\"\"\"CDP {{ domain_name }} Domain\"\"\"
+from typing import TYPE_CHECKING
+from .methods.service import {{ domain_name }}Methods
+from .events.service import {{ domain_name }}Events
+
+if TYPE_CHECKING:
+    from ...service import Client
+
+class {{ domain_name }}({{ domain_name }}Methods, {{ domain_name }}Events):
+    \"\"\"
+    {{ domain_description | replace("\\n", " ") }}
+    \"\"\"
+    def __init__(self, client: "Client"):
+        \"\"\"
+        Initialize the {{ domain_name }} domain.
+        
+        Args:
+            client ("Client"): The parent CDP client instance.
+        \"\"\"
+        {{ domain_name }}Methods.__init__(self, client)
+        {{ domain_name }}Events.__init__(self, client)
+"""
+
+class DomainGenerator:
+    def __init__(self, method_generator: MethodGenerator, event_generator: EventGenerator, package_name: str):
+        self.method_generator = method_generator
+        self.event_generator = event_generator
+        self.package_name = package_name
+        self.env = Environment(trim_blocks=True, lstrip_blocks=True, extensions=[StrcaseExtension])
+
+    def generate_methods_service(self, domain: dict) -> str:
+        domain_name = domain['domain']
+        self.method_generator.current_domain = domain_name
+        self.method_generator.clear()
+        
+        methods = domain.get('commands', [])
+        method_implementations = []
+        for method in methods:
+            if not method.get('deprecated', False):
+                code = self.method_generator.generate_method_implementation(method)
+                method_implementations.append(code)
+
+        imports = self.method_generator.imports.copy()
+        imports.update(self.method_generator.type_checking_imports)
+        imports.add("from .types import *")
+        imports.add("from ..types import *") # Import shared types
+        imports.add("from typing import Optional, Dict, Any, Callable, TYPE_CHECKING")
+        
+        class_name = f"{domain_name}Methods"
+        template = self.env.from_string(METHODS_SERVICE_TEMPLATE)
+        return template.render(
+            domain_name=domain_name,
+            class_name=class_name,
+            imports=sorted(imports),
+            method_implementations=method_implementations
+        ).strip()
+
+    def generate_events_service(self, domain: dict) -> str:
+        domain_name = domain['domain']
+        self.event_generator.current_domain = domain_name
+        self.event_generator.clear()
+        
+        events = domain.get('events', [])
+        event_implementations = []
+        for event in events:
+            if not event.get('deprecated', False):
+                code = self.event_generator.generate_event_implementation(event)
+                event_implementations.append(code)
+
+        imports = self.event_generator.imports.copy()
+        imports.update(self.event_generator.type_checking_imports)
+        imports.add("from .types import *")
+        imports.add("from ..types import *")
+        imports.add("from typing import Optional, Dict, Any, Callable, TYPE_CHECKING")
+
+        class_name = f"{domain_name}Events"
+        template = self.env.from_string(EVENTS_SERVICE_TEMPLATE)
+        return template.render(
+            domain_name=domain_name,
+            class_name=class_name,
+            imports=sorted(imports),
+            event_implementations=event_implementations
+        ).strip()
+
+    def generate_domain_service(self, domain: dict) -> str:
+        domain_name = domain['domain']
+        domain_description = domain.get('description', f'Access the {domain_name} domain.')
+        template = self.env.from_string(DOMAIN_SERVICE_TEMPLATE)
+        return template.render(domain_name=domain_name, domain_description=domain_description).strip()

cdp/generator/event_generator.py

@@ -0,0 +1,202 @@
+from jinja2 import Environment
+from jinja2_strcase import StrcaseExtension
+import inflection
+
+EVENT_SERVICES_TEMPLATE = """\
+\"\"\"CDP {{ domain_name }} Events\"\"\"
+
+from client.service import CDPClient
+from typing import TypedDict, Optional, Callable
+from protocol.{{ domain_name | to_snake }}.events.types import *
+
+class {{ domain_name }}Events:
+    {% if event_implementations | length > 0 %}
+    def __init__(self,client:CDPClient):
+        self.client=client
+    {% for implementation in event_implementations %}
+    {{ implementation | indent(4) }}
+    {% endfor %}
+    {% else %}
+    pass
+    {% endif %}     
+"""
+
+EVENT_IMPLEMENTATION_TEMPLATE = """\
+def on_{{ event_name | to_snake }}(self, callback: Callable[[{{ event_name }}Event,Optional[str]], None]=None) -> None:
+    \"\"\"
+    {% if event_description %}{{ event_description | replace("\\n", " ") }}{% else %}No description available for {{ event_name }}.{% endif %}
+    
+    Args:
+        callback (callable, optional): Function called when the event is fired. 
+            The callback receives (params: {{ event_name }}Event, session_id: Optional[str]).
+    \"\"\"
+    self.client.on('{{ domain_name }}.{{ event_name }}', callback)
+"""
+
+EVENT_TYPES_TEMPLATE = """\
+\"\"\"CDP {{ domain_name }} Events\"\"\"
+
+{% for import_ in imports %}
+{{ import_ }}
+{% endfor %}
+{% if type_checking_imports %}
+
+from typing import TYPE_CHECKING
+if TYPE_CHECKING:
+    {% for type_checking_import in type_checking_imports %}
+    {{ type_checking_import }}
+    {% endfor %}
+{% endif %}
+
+{% for definition in event_definitions_code %}
+{{ definition }}
+{% endfor %}         
+"""
+
+EVENT_DEFINITION_TEMPLATE = """\
+class {{event_name}}Event(TypedDict, total={{total}}):
+    {% if not required_parameters and not optional_parameters %}
+    pass
+    {% else %}
+    {% if required_parameters %}
+    {% for parameter in required_parameters %}
+    {{ parameter['name'] }}: '{{ parameter['type'] }}'
+    {% if parameter['description'] %}
+    \"\"\"{{ parameter['description'] | replace('\\n', ' ') | replace('`', '') }}\"\"\"
+    {% endif %}
+    {% endfor %}
+    {% endif %}
+    {% if optional_parameters %}
+    {% for parameter in optional_parameters %}
+    {{ parameter['name'] }}: NotRequired['{{ parameter['type'] }}']
+    {% if parameter['description'] %}
+    \"\"\"{{ parameter['description'] | replace('\\n', ' ') | replace('`', '') }}\"\"\"
+    {% endif %}
+    {% endfor %}
+    {% endif %}
+    {% endif %}
+"""
+
+class EventGenerator:
+    def __init__(self,path, protocol_package:str):
+        self.path = path
+        self.protocol_package = protocol_package
+        self.current_domain:str=None
+        self.env=Environment(trim_blocks=True,lstrip_blocks=True,extensions=[StrcaseExtension])
+        self.imports = set()
+        self.generated_events = set()
+        self.type_checking_imports = set()
+
+    def clear(self):
+        self.imports.clear()
+        self.generated_events.clear()
+        self.type_checking_imports.clear()
+
+    def generate_event_services(self,domain:dict):
+        self.current_domain=domain.get('domain')
+        events=domain.get('events',[])
+        event_implementations=[self.generate_event_implementation(event) for event in events]
+        template = self.env.from_string(EVENT_SERVICES_TEMPLATE)
+        code = template.render(
+            domain_name=self.current_domain,
+            event_implementations=event_implementations,
+        )
+        return code.strip()
+
+    def generate_event_implementation(self,event:dict):
+        event_name=event.get('name')
+        event_description=event.get('description','')
+        template = self.env.from_string(EVENT_IMPLEMENTATION_TEMPLATE)
+        code = template.render(
+            event_name=event_name,
+            domain_name=self.current_domain,
+            event_description=event_description
+        )
+        return code.strip()
+
+    def generate_event_types(self,domain:dict):
+        self.current_domain=domain.get('domain')
+        events=domain.get('events',[])
+        self.clear()
+        self.imports.add("from typing import TypedDict, NotRequired, Required, Literal, Any, Dict, Union, Optional, List, Set, Tuple")
+        for event in events:
+            self.generated_events.add(event.get('name'))
+
+        event_definitions_code=[self.generate_event_definition(event) for event in events if not event.get('deprecated',False)]
+        template = self.env.from_string(EVENT_TYPES_TEMPLATE)
+        code = template.render(
+            domain_name=self.current_domain,
+            event_definitions_code=event_definitions_code,
+            imports=sorted(filter(lambda x: not x.startswith(f'from {self.protocol_package}.{self.current_domain}.types import'),self.imports)),
+            type_checking_imports=sorted(self.type_checking_imports),
+        )
+        return code.strip()
+
+    def generate_event_definition(self,event_definition): 
+        event_name=event_definition.get('name')   
+        parameters=event_definition.get('parameters',[])
+        required_parameters=[]
+        optional_parameters=[]
+        for parameter in parameters:
+            parameter['type'] = self.resolve_parameter_type(parameter)
+            if parameter.get('optional',False):
+                optional_parameters.append(parameter)
+            else:
+                required_parameters.append(parameter)
+
+        total = not (optional_parameters and not required_parameters)
+        template = self.env.from_string(EVENT_DEFINITION_TEMPLATE)
+        code = template.render(
+            total=total,
+            event_name=event_name,
+            required_parameters=required_parameters,
+            optional_parameters=optional_parameters,
+        )
+        self.generated_events.add(event_name)
+        return code.strip()
+
+    def resolve_parameter_type(self, parameter:dict):
+        if "$ref" in parameter:
+            return self.resolve_type_reference(parameter)
+        parameter_type=parameter.get("type","any")
+        match parameter_type:
+            case 'object':
+                return "Dict[str, Any]"
+            case 'array':
+                items=parameter.get('items',{})
+                return f"List[{self.resolve_type_reference(items) if '$ref' in items else self.map_primitive_type(items.get('type'))}]"
+            case 'string':
+                if 'enum' in parameter:
+                    return f"Literal[{', '.join(f'\"{v}\"' for v in parameter.get('enum'))}]"
+                else:
+                    return "str"
+            case _:
+                return self.map_primitive_type(parameter_type)
+
+    def resolve_type_reference(self, type_ref:dict):
+        ref=type_ref.get('$ref')
+        if '.' in ref:
+            parts=ref.split('.')
+            type_name=parts[1]
+            domain=inflection.underscore(parts[0])
+            self.type_checking_imports.add(f"from {self.protocol_package}.{domain}.types import {type_name}")
+            return type_name
+        else:
+            domain=inflection.underscore(self.current_domain)
+            self.type_checking_imports.add(f"from {self.protocol_package}.{domain}.types import {ref}")
+            return ref
+
+    def map_primitive_type(self, type_name: str):
+        match type_name:
+            case "string":
+                return "str"
+            case "object":
+                return "Dict[str, Any]"
+            case "number":
+                return "float"
+            case "integer":
+                return "int"
+            case "boolean":
+                return "bool"
+            case _:
+                return "Any"