Implementation:SeleniumHQ Selenium Python CDP Generator

Knowledge Sources	SeleniumHQ_Selenium
Domains	WebDriver, Code_Generation, Python_Bindings
Last Updated	2026-02-12 00:00 GMT

Overview

The Python CDP generator (generate.py) reads Chrome DevTools Protocol JSON schema files and produces typed Python modules for each CDP domain, enabling type-safe CDP interaction from Selenium's Python bindings.

Description

This generator is a Python port/adaptation of the HyperionGray python-chrome-devtools-protocol generator (MIT licensed). It processes CDP JSON protocol definitions and produces a complete Python package with:

Type System: Maps CDP types to Python via the CdpPrimitiveType enum:

• boolean to bool, integer to int, number to float, object to dict, string to str, any to typing.Any.

Code Generation Classes:

• CdpType: Generates Python classes for CDP types. Primitive types become subclasses of their Python equivalent. Enum types become enum.Enum subclasses. Object types become @dataclass classes with to_json() and from_json() methods.
• CdpCommand: Generates Python generator functions for each CDP command. Commands yield a JSON dict (the protocol message), receive the response JSON, and return the typed result. Parameters support optional values and cross-domain $ref references.
• CdpEvent: Generates @dataclass classes decorated with @event_class for each CDP event. Events include a from_json() class method for deserialization.
• CdpDomain: Represents a full CDP domain and generates a complete Python module file, including computed import statements for cross-domain type references.
• CdpProperty, CdpParameter, CdpReturn: Handle property declarations, parameter code generation, and return value deserialization.

Module Structure: For each CDP version, generates:

• One Python module per domain (e.g., network.py, page.py).
• An __init__.py that re-exports all domain modules.
• A util.py with the event parser registry and T_JSON_DICT type alias.
• A py.typed marker for PEP 561 compliance.

CDP Patches: The generator applies two hardcoded patches for known CDP specification errors: a self-referencing $ref in the DOM domain's resolveNode command, and an extraneous backtick in a Page event description.

Usage

This script is invoked during the build process to regenerate CDP bindings when protocol versions change. It requires Python 3.7+ and the inflection library.

Code Reference

Source Location

• Repository: SeleniumHQ_Selenium
• File: py/generate.py

Signature

def main(browser_protocol_path, js_protocol_path, output_path)

def parse(json_path, output_path) -> list[CdpDomain]

def generate_init(init_path, domains)

def generate_docs(docs_path, domains)

class CdpPrimitiveType(Enum):
    @classmethod
    def get_annotation(cls, cdp_type) -> str
    @classmethod
    def get_constructor(cls, cdp_type, val) -> str

@dataclass
class CdpType:
    @classmethod
    def from_json(cls, type_) -> CdpType
    def generate_code(self) -> str
    def get_refs(self) -> set

@dataclass
class CdpCommand:
    @classmethod
    def from_json(cls, command, domain) -> CdpCommand
    def generate_code(self) -> str
    def get_refs(self) -> set

@dataclass
class CdpEvent:
    @classmethod
    def from_json(cls, json, domain) -> CdpEvent
    def generate_code(self) -> str
    def get_refs(self) -> set

@dataclass
class CdpDomain:
    @classmethod
    def from_json(cls, domain) -> CdpDomain
    def generate_code(self) -> str
    def generate_imports(self) -> str

Import

# Run as a script:
python py/generate.py browser_protocol.json js_protocol.json output_dir/

# Or import for programmatic use:
from generate import main, parse, CdpDomain

I/O Contract

Inputs (Command-Line Arguments)

Argument	Position	Type	Description
Browser Protocol JSON	0	Path	Path to CDP browser_protocol.json
JS Protocol JSON	1	Path	Path to CDP js_protocol.json
Output Directory	2	Path	Directory to write generated Python modules

Output Files

File	Description
{domain}.py	One module per CDP domain (e.g., network.py, page.py) containing types, commands, and events
__init__.py	Package init that imports all domain modules and util
util.py	Utility module with T_JSON_DICT type alias, event_class decorator, and parse_json_event function
py.typed	PEP 561 marker file for type checker support

CDP to Python Type Mapping

CDP Type	Python Annotation
boolean	bool
integer	int
number	float
string	str
object	dict
any	typing.Any
array (with items)	typing.List[T]
enum	enum.Enum subclass
$ref	Direct class reference (cross-domain uses dotted import)

Usage Examples

# Generate CDP Python bindings for a specific version:
python py/generate.py \
  third_party/cdp/browser_protocol.json \
  third_party/cdp/js_protocol.json \
  py/selenium/webdriver/common/devtools/v125/

# Example of generated code (consumer side):
from selenium.webdriver.common.devtools.v125 import network

# Commands are generator functions:
cmd = network.enable(max_total_buffer_size=None, max_resource_buffer_size=None)

# Events are dataclasses with from_json:
event = network.RequestWillBeSent.from_json(json_dict)
print(event.request_id)

Related Pages

• SeleniumHQ_Selenium_CdpClientGenerator - Java equivalent CDP code generator
• SeleniumHQ_Selenium_DevTools_Send - DevTools protocol send API
• SeleniumHQ_Selenium_DevTools_CreateSession - DevTools session management
• SeleniumHQ_Selenium_Python_Pyproject - Python package configuration