chromedeveloperprotocol-client 0.1.0__py3-none-any.whl

cdp/generator/method_generator.py

@@ -0,0 +1,215 @@
+from jinja2_strcase import StrcaseExtension
+from jinja2 import Environment
+import inflection
+
+METHOD_IMPLEMENTATION_TEMPLATE = """\
+async def {{ method_name | to_snake }}(self, params: {% if parameters|length > 0 %}Optional[{{ method_name }}Parameters]{% else %}None{% endif %}=None,session_id: Optional[str] = None) -> {% if return_parameters|length > 0 %}{{ method_name }}Returns{% else %}Dict[str, Any]{% endif %}:
+    \"\"\"
+    {% if method_description %}{{ method_description | replace("\\n", " ") }}{% else %}No description available for {{ method_name }}.{% endif %}
+    
+    Args:
+        params ({% if parameters|length > 0 %}{{ method_name }}Parameters{% else %}None{% endif %}, optional): Parameters for the {{ method_name }} method.
+        session_id (str, optional): Target session ID for flat protocol usage.
+        
+    Returns:
+        {% if return_parameters|length > 0 %}{{ method_name }}Returns{% else %}Dict[str, Any]{% endif %}: The result of the {{ method_name }} call.
+    \"\"\"
+    return await self.client.send(method="{{ domain_name }}.{{ method_name }}", params=params,session_id=session_id)
+"""
+
+METHOD_TYPES_TEMPLATE = """\
+\"\"\"CDP {{ domain_name }} Methods Types\"\"\"
+
+{% 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 parameter_definitions_code %}
+{{ definition }}
+{% endfor %}
+{% for definition in return_definitions_code %}
+{{ definition }}
+{% endfor %}
+"""
+
+PARAMETER_DEFINITION_TEMPLATE = """\
+class {{ method_name }}Parameters(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 %}
+"""
+
+RETURN_DEFINITION_TEMPLATE = """\
+class {{ method_name }}Returns(TypedDict):
+    {% if not return_parameters %}
+    pass
+    {% else %}
+    {% for return_parameter in return_parameters %}
+    {{ return_parameter['name'] }}: '{{ return_parameter['type'] }}'
+    {% if return_parameter['description'] %}
+    \"\"\"{{ return_parameter['description'] | replace('\\n', ' ') | replace('`', '') }}\"\"\"
+    {% endif %}
+    {% endfor %}
+    {% endif %}
+"""
+
+class MethodGenerator:
+    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_methods = set()
+        self.type_checking_imports = set()
+
+    def clear(self):
+        self.imports.clear()
+        self.generated_methods.clear()
+        self.type_checking_imports.clear()
+
+    def generate_method_implementation(self,method:dict):
+        method_name=method.get('name')
+        method_description=method.get('description','')
+        parameters=method.get('parameters',[])
+        return_parameters=method.get('returns',[])
+        template = self.env.from_string(METHOD_IMPLEMENTATION_TEMPLATE)
+        code = template.render(
+            domain_name=self.current_domain,
+            method_name=method_name,
+            method_description=method_description,
+            parameters=parameters,
+            return_parameters=return_parameters,
+        )
+        return code.strip()
+
+    def generate_method_types(self,domain:dict):
+        self.current_domain=domain.get('domain')
+        methods=domain.get('commands',[])
+        self.clear()
+        self.imports.add("from typing import TypedDict, NotRequired, Required, Literal, Any, Dict, Union, Optional, List, Set, Tuple")
+        for method in methods:
+            self.generated_methods.add(method.get('name'))
+
+        parameter_definitions_code=[self.generate_parameter_definition(method) for method in methods if not method.get('deprecated',False)]
+        return_definitions_code=[self.generate_return_definition(method) for method in methods if not method.get('deprecated',False)]
+
+        template = self.env.from_string(METHOD_TYPES_TEMPLATE)
+        code = template.render(
+            domain_name=self.current_domain,
+            parameter_definitions_code=parameter_definitions_code,
+            return_definitions_code=return_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_parameter_definition(self, method_definition:dict):
+        method_name=method_definition.get('name')
+        parameters=method_definition.get('parameters',[])
+        if not parameters:
+            return ''
+        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(PARAMETER_DEFINITION_TEMPLATE)
+        code = template.render(
+            total=total,
+            method_name=method_name,
+            required_parameters=required_parameters,
+            optional_parameters=optional_parameters,
+        )
+        self.generated_methods.add(method_name)
+        return code.strip()
+
+    def generate_return_definition(self, method_definition:dict):
+        method_name=method_definition.get('name')
+        return_parameters=method_definition.get('returns',[])
+        if not return_parameters:
+            return ""
+        for return_parameter in return_parameters:
+            return_parameter['type']=self.resolve_parameter_type(return_parameter)
+        template = self.env.from_string(RETURN_DEFINITION_TEMPLATE)
+        code = template.render(
+            method_name=method_name,
+            return_parameters=return_parameters
+        )
+        self.generated_methods.add(method_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"

cdp/generator/service.py

@@ -0,0 +1,153 @@
+from .constant import BROWSER_PROTOCOL_URL, JS_PROTOCOL_URL
+from .method_generator import MethodGenerator
+from .event_generator import EventGenerator
+from .type_generator import TypeGenerator
+from .client_generator import ClientGenerator
+from .domain_generator import DomainGenerator
+from jinja2_strcase import StrcaseExtension
+from jinja2 import Environment
+from textwrap import dedent
+from functools import cache
+from pathlib import Path
+from typing import Any, Optional
+import inflection
+import httpx
+
+class CDPGenerator:    
+    def __init__(self, src_path: Optional[Path] = None):
+        if src_path is None:
+            self.root_path = Path(__file__).parent.parent.parent.parent
+            self.src_path = self.root_path / "src"
+        else:
+            self.src_path = src_path
+            self.root_path = src_path.parent
+            
+        self.cdp_path = self.src_path / "cdp"
+        self.protocol_path = self.cdp_path / "protocol"
+        self.client_path = self.cdp_path
+        
+        self.protocol_package = "cdp.protocol"
+        self.package_name = "cdp"
+        
+        self.method_generator = MethodGenerator(self.protocol_path, self.protocol_package)
+        self.event_generator = EventGenerator(self.protocol_path, self.protocol_package)
+        self.type_generator = TypeGenerator(self.protocol_path, self.protocol_package)
+        self.domain_generator = DomainGenerator(self.method_generator, self.event_generator, self.package_name)
+        self.client_generator = ClientGenerator(self.protocol_package, self.package_name)
+
+    @property
+    @cache
+    def domains(self):
+        domains = []
+        for url in [BROWSER_PROTOCOL_URL, JS_PROTOCOL_URL]:
+            try:
+                protocol = httpx.get(url).json()
+                domains.extend(protocol.get('domains', []))
+            except Exception as e:
+                print(f"Failed to load protocol from {url}: {e}")
+        return domains
+
+    def generate(self):
+        # Create base directories and __init__.py files
+        self.cdp_path.mkdir(parents=True, exist_ok=True)
+        self.protocol_path.mkdir(parents=True, exist_ok=True)
+        
+        self.ensure_init(self.cdp_path)
+        self.ensure_init(self.protocol_path)
+        
+        # Add py.typed to both cdp and cdp.protocol
+        (self.cdp_path / "py.typed").write_text("")
+        (self.protocol_path / "py.typed").write_text("")
+        
+        self.generate_protocol()
+        self.generate_client()
+        
+    def ensure_init(self, path: Path):
+        init_file = path / "__init__.py"
+        if not init_file.exists():
+            init_file.write_text("")
+
+    def generate_protocol(self):
+        for domain in self.domains:
+            if not domain.get('deprecated', False):
+                self.generate_domain_types(domain)
+                self.generate_domain_services(domain)
+    
+    def generate_client(self):
+        client_dir = self.client_path
+        domains = list(filter(lambda x: not x.get('deprecated', False), self.domains))
+        
+        # Generate domains.py with Domains class
+        domains_content = self.client_generator.generate_domains(domains)
+        self.write_file(client_dir / "domains.py", domains_content)
+
+        # Generate service.py with Client class
+        service_content = self.client_generator.generate_service()
+        self.write_file(client_dir / "service.py", service_content)
+        
+        # Generate cdp/__init__.py
+        init_content = dedent("""
+            from .domains import Domains
+            from .service import Client
+            
+            __all__ = ["Domains", "Client"]
+        """).strip()
+        self.write_file(client_dir / "__init__.py", init_content)
+
+    def generate_domain_services(self, domain: dict):
+        domain_name_snake = inflection.underscore(domain['domain'])
+        domain_dir = self.protocol_path / domain_name_snake
+        
+        methods_dir = domain_dir / "methods"
+        events_dir = domain_dir / "events"
+        
+        domain_dir.mkdir(parents=True, exist_ok=True)
+        methods_dir.mkdir(parents=True, exist_ok=True)
+        events_dir.mkdir(parents=True, exist_ok=True)
+        
+        self.ensure_init(domain_dir)
+        self.ensure_init(methods_dir)
+        self.ensure_init(events_dir)
+        
+        # Generate methods service
+        methods_content = self.domain_generator.generate_methods_service(domain)
+        self.write_file(methods_dir / "service.py", methods_content)
+
+        # Generate events service
+        events_content = self.domain_generator.generate_events_service(domain)
+        self.write_file(events_dir / "service.py", events_content)
+
+        # Generate main service
+        service_content = self.domain_generator.generate_domain_service(domain)
+        self.write_file(domain_dir / "service.py", service_content)
+
+    def generate_domain_types(self, domain: dict):
+        domain_name_snake = inflection.underscore(domain['domain'])
+        domain_dir = self.protocol_path / domain_name_snake
+        
+        methods_dir = domain_dir / "methods"
+        events_dir = domain_dir / "events"
+        
+        domain_dir.mkdir(parents=True, exist_ok=True)
+        methods_dir.mkdir(parents=True, exist_ok=True)
+        events_dir.mkdir(parents=True, exist_ok=True)
+        
+        self.ensure_init(domain_dir)
+        self.ensure_init(methods_dir)
+        self.ensure_init(events_dir)
+
+        # Generate types
+        types_content = self.type_generator.generate_types(domain)
+        self.write_file(domain_dir / "types.py", types_content)
+
+        # Generate method types
+        method_types_content = self.method_generator.generate_method_types(domain)
+        self.write_file(methods_dir / "types.py", method_types_content)
+
+        # Generate event types
+        event_types_content = self.event_generator.generate_event_types(domain)
+        self.write_file(events_dir / "types.py", event_types_content)
+
+    def write_file(self, path: Path, content: str):
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(content, encoding='utf-8')

cdp/generator/type_generator.py

@@ -0,0 +1,231 @@
+from jinja2 import Environment
+from pathlib import Path
+import inflection
+
+TYPES_TEMPLATE = """\
+\"\"\"CDP {{ current_domain }} Types\"\"\"
+
+{% 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 type_definitions_code %}
+{{ definition }}
+{% endfor %}
+"""
+
+ARRAY_TYPE_TEMPLATE = """\
+{{ type_name }} = List['{{ type_type }}']
+{% if type_description %}
+\"\"\"{{ type_description | replace('\\n', ' ') | replace('`', '') }}\"\"\"
+{% endif %}
+"""
+
+PRIMITIVE_TYPE_TEMPLATE = """\
+{{ type_name }} = {{ type_type }}
+{% if type_description %}
+\"\"\"{{ type_description | replace('\\n', ' ') | replace('`', '') }}\"\"\"
+{% endif %}
+"""
+
+LITERAL_TYPE_TEMPLATE = """\
+{{ type_name }} = Literal[{{ enum_values }}]
+{% if type_description %}
+\"\"\"{{ type_description | replace('\\n', ' ') }}\"\"\"
+{% endif %}
+"""
+
+OBJECT_TYPE_TEMPLATE = """\
+class {{ type_name }}(TypedDict, total={{ total }}):
+    {% if type_description %}
+    \"\"\"{{ type_description | replace('\\n', ' ') | replace('`', '') }}\"\"\"
+    {% endif %}
+    {% if not required_properties and not optional_properties %}
+    pass
+    {% else %}
+    {% if required_properties %}
+    {% for property in required_properties %}
+    {{ property['name'] }}: '{{ property['type'] }}'
+    {% if property.get('description') %}
+    \"\"\"{{ property['description'] | replace('\\n', ' ') | replace('\\\"', '') | replace('`','') }}\"\"\"
+    {% endif %}
+    {% endfor %}
+    {% endif %}
+    {% if optional_properties %}
+    {% for property in optional_properties %}
+    {{ property['name'] }}: NotRequired['{{ property['type'] }}']
+    {% if property.get('description') %}
+    \"\"\"{{ property['description'] | replace('\\n', ' ') | replace('`', '') }}\"\"\"
+    {% endif %}
+    {% endfor %}
+    {% endif %}
+    {% endif %}
+"""
+
+class TypeGenerator:
+    def __init__(self,path: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)
+        self.imports = set()
+        self.generated_types = set()
+        self.type_checking_imports = set()
+
+    def clear(self):
+        self.imports.clear()
+        self.generated_types.clear()
+        self.type_checking_imports.clear()
+
+    def generate_types(self, domain: dict):
+        self.current_domain = domain.get('domain')
+        type_definitions = domain.get('types', [])
+        self.clear()
+        self.imports.add("from typing import TypedDict, NotRequired, Required, Literal, Any, Dict, Union, Optional, List, Set, Tuple")
+        for type_definition in type_definitions:
+            self.generated_types.add(type_definition.get('id'))
+
+        type_definitions_code=[self.generate_type_definition(type_definition) for type_definition in type_definitions]
+        template = self.env.from_string(TYPES_TEMPLATE)
+        code = template.render(
+            current_domain=self.current_domain,
+            type_definitions_code=type_definitions_code,
+            imports=sorted(filter(lambda x: not x.startswith(f'from {self.protocol_package}.{inflection.underscore(self.current_domain)}.types import'),self.imports)),
+            type_checking_imports=sorted(self.type_checking_imports),
+        )
+        return code.strip()
+
+    def generate_type_definition(self, type_definition: dict):
+        type_type = type_definition.get('type')
+        if type_type == "string" and "enum" in type_definition:
+            return self.generate_literal_type(type_definition)
+        elif type_type == "object":
+            return self.generate_object_type(type_definition)
+        elif type_type == "array":
+            return self.generate_array_type(type_definition)
+        elif type_type in ["string", "number", "integer", "boolean"]:
+            return self.generate_primitive_type(type_definition)
+
+    def generate_array_type(self, type_definition: dict):
+        type_name = type_definition.get('id')
+        type_description = type_definition.get('description')
+        items = type_definition.get('items', {})
+        template = self.env.from_string(ARRAY_TYPE_TEMPLATE)
+        code = template.render(
+            type_name=type_name,
+            type_type=self.resolve_type_reference(items) if '$ref' in items else self.map_primitive_type(items.get('type')),
+            type_description=type_description,
+        )
+        self.generated_types.add(type_name)
+        return code.strip()
+
+    def generate_primitive_type(self, type_definition: dict):
+        type_name=type_definition.get('id')
+        type_description=type_definition.get('description')
+        type_type=type_definition.get('type')
+        template = self.env.from_string(PRIMITIVE_TYPE_TEMPLATE)
+        code = template.render(
+            type_name=type_name,
+            type_type=self.map_primitive_type(type_type),
+            type_description=type_description,
+        )
+        self.generated_types.add(type_name)
+        return code.strip()
+
+    def generate_literal_type(self, type_definition: dict):
+        type_name = type_definition.get('id')
+        type_description = type_definition.get('description')
+        enum_values = type_definition.get('enum', [])
+        template = self.env.from_string(LITERAL_TYPE_TEMPLATE)
+        code = template.render(
+            type_name=type_name,
+            enum_values=",".join(f"'{v}'" for v in enum_values),
+            type_description=type_description,
+        )
+        self.generated_types.add(type_name)
+        return code.strip()
+
+    def generate_object_type(self, type_definition: dict):
+        type_name = type_definition.get('id')
+        type_description = type_definition.get('description', '')
+        properties = type_definition.get('properties', [])
+        required_properties = []
+        optional_properties = []
+        for property in properties:
+            is_optional = property.get('optional', False)
+            if property.get('deprecated', False):
+                continue
+            property['type'] = self.resolve_property_type(property)
+            if is_optional:
+                optional_properties.append(property)
+            else:
+                required_properties.append(property)
+        total = not (optional_properties and not required_properties)
+        template = self.env.from_string(OBJECT_TYPE_TEMPLATE)
+        code = template.render(
+            type_name=type_name,
+            total=total,
+            type_description=type_description,
+            required_properties=required_properties,
+            optional_properties=optional_properties,
+        )
+        self.generated_types.add(type_name)
+        return code.strip()
+
+    def resolve_property_type(self, property: dict):
+        if '$ref' in property:
+            return self.resolve_type_reference(property)
+        property_type = property.get('type','any')
+        match property_type:
+            case 'object':
+                return "Dict[str, Any]"
+            case 'array':
+                items=property.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 property:
+                    return f"Literal[{', '.join(f'\"{v}\"' for v in property.get('enum'))}]"
+                else:
+                    return "str"
+            case _:
+                return self.map_primitive_type(property_type)
+        
+    def resolve_type_reference(self, type_ref:dict):
+        ref = type_ref.get('$ref')
+        if '.' in ref:
+            parts=ref.split('.')
+            type_name=parts[1]
+            current_domain=self.current_domain.lower()
+            domain=parts[0].lower()
+            if (current_domain!=domain) or (type_name not in self.generated_types):
+                domain=inflection.underscore(domain)
+                self.type_checking_imports.add(f"from {self.protocol_package}.{domain}.types import {type_name}")
+            return type_name
+        else:
+            if ref not in self.generated_types:
+                domain=inflection.underscore(self.current_domain)
+                self.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"

cdp/protocol/accessibility/events/service.py

@@ -0,0 +1,37 @@
+"""CDP Accessibility Domain Events"""
+from ..types import *
+from .types import *
+from typing import Optional, Dict, Any, Callable, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ....service import Client
+
+class AccessibilityEvents:
+    """
+    Events for the Accessibility domain.
+    """
+    def __init__(self, client: "Client"):
+        """
+        Initialize the Accessibility events.
+        
+        Args:
+            client ("Client"): The parent CDP client instance.
+        """
+        self.client = client
+
+    def on_load_complete(self, callback: Callable[[loadCompleteEvent,Optional[str]], None]=None) -> None:
+        """
+    The loadComplete event mirrors the load complete event sent by the browser to assistive technology when the web page has finished loading.    
+        Args:
+            callback (callable, optional): Function called when the event is fired. 
+                The callback receives (params: loadCompleteEvent, session_id: Optional[str]).
+        """
+        self.client.on('Accessibility.loadComplete', callback)
+    def on_nodes_updated(self, callback: Callable[[nodesUpdatedEvent,Optional[str]], None]=None) -> None:
+        """
+    The nodesUpdated event is sent every time a previously requested node has changed the in tree.    
+        Args:
+            callback (callable, optional): Function called when the event is fired. 
+                The callback receives (params: nodesUpdatedEvent, session_id: Optional[str]).
+        """
+        self.client.on('Accessibility.nodesUpdated', callback)

cdp/protocol/accessibility/events/types.py

@@ -0,0 +1,14 @@
+"""CDP Accessibility Events"""
+
+from typing import TypedDict, NotRequired, Required, Literal, Any, Dict, Union, Optional, List, Set, Tuple
+
+from typing import TYPE_CHECKING
+if TYPE_CHECKING:
+    from cdp.protocol.accessibility.types import AXNode
+
+class loadCompleteEvent(TypedDict, total=True):
+    root: 'AXNode'
+    """New document root node."""
+class nodesUpdatedEvent(TypedDict, total=True):
+    nodes: 'List[AXNode]'
+    """Updated node data."""