cdpify 0.3.0__tar.gz → 0.4.0__tar.gz

{cdpify-0.3.0 → cdpify-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cdpify
-Version: 0.3.0
+Version: 0.4.0
 Summary: A Python client for the Chrome DevTools Protocol (CDP) optimized for DX.
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.12
@@ -8,6 +8,8 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
+Provides-Extra: orjson
+Requires-Dist: orjson>=3.11.3; extra == "orjson"
 Provides-Extra: websocket
 Requires-Dist: websockets>=15.0.1; extra == "websocket"
 Provides-Extra: generator
@@ -40,7 +42,7 @@ without working with raw JSON messages.
 
 - **Typed by default** — generated models for commands, results, events, and
   shared protocol types
-- **Complete domain coverage** — access all 58 generated CDP domains through
+- **Complete domain coverage** — access all 59 generated CDP domains through
   properties such as `client.page`, `client.network`, and `client.runtime`
 - **Async throughout** — transport-neutral core with an optional WebSocket
   implementation
@@ -56,9 +58,19 @@ pip install "cdpify[websocket]"
 ```
 
 Requires Python 3.12 or newer. The WebSocket extra provides the recommended
-default transport used by `Client(url)`. Install `cdpify` without an extra when
+default transport used by `CdpClient(url)`. Install `cdpify` without an extra when
 supplying your own `Transport` implementation.
 
+For faster JSON encoding and decoding in the WebSocket transport, install the
+optional `orjson` extra as well:
+
+```bash
+pip install "cdpify[websocket,orjson]"
+```
+
+The transport automatically uses `orjson` when available and otherwise uses
+Python's standard `json` module. Outgoing WebSocket messages remain text frames.
+
 Install the generator dependencies only when regenerating protocol modules:
 
 ```bash
@@ -75,7 +87,7 @@ import asyncio
 import json
 from urllib.request import urlopen
 
-from cdpify import Client
+from cdpify import CdpClient
 
 
 def get_websocket_url() -> str:
@@ -86,7 +98,7 @@ def get_websocket_url() -> str:
 async def main() -> None:
     ws_url = get_websocket_url()
 
-    async with Client(ws_url) as client:
+    async with CdpClient(ws_url) as client:
         await client.page.navigate(url="https://example.com")
 
         result = await client.runtime.evaluate(
@@ -99,14 +111,34 @@ async def main() -> None:
 asyncio.run(main())
 ```
 
-Domains are available as lazy properties on `Client`. Parameters use
+Domains are available as lazy properties on `CdpClient`. Parameters use
 Python's `snake_case`; `cdpify` handles conversion to and from CDP's wire format.
 
+Named protocol enums use `StrEnum`, so typed code can use constants such as
+`ResourceType.FETCH` or `CookieOperation.SET_COOKIE`. Decoded responses and
+events contain enum members, including in nested models and lists:
+
+```python
+from cdpify.domains.network import LoadingFailedEvent, NetworkEvent, ResourceType
+
+async for event in client.listen(LoadingFailedEvent):
+    assert event.__cdp_event__ is NetworkEvent.LOADING_FAILED
+    if event.type is ResourceType.FETCH:
+        print(event.error_text)
+```
+
+Enum members work as strings and expose the original protocol value through
+`.value`. Unknown values from newer Chrome versions are preserved as members
+of the same enum without changing its declared constants or iteration.
+Anonymous enum annotations such as `Literal["jpeg", "png"]` still accept direct
+strings. Open string fields, including EventSource's server-defined
+`event_name`, remain strings.
+
 ## Supported domains
 
-The generated client currently includes all 58 domains from the bundled CDP
-specifications. Each domain is available as a lazy property on `Client` and
-`CDPSession`:
+The generated client currently includes all 59 domains from the bundled CDP
+specifications. Each domain is available as a lazy property on `CdpClient` and
+`CdpSession`:
 
 | CDP domain | Python accessor | CDP domain | Python accessor |
 | --- | --- | --- | --- |
@@ -137,37 +169,50 @@ specifications. Each domain is available as a lazy property on `Client` and
 | `FedCm` | `client.fed_cm` | `Tethering` | `client.tethering` |
 | `Fetch` | `client.fetch` | `Tracing` | `client.tracing` |
 | `FileSystem` | `client.file_system` | `WebAudio` | `client.web_audio` |
-| `HeadlessExperimental` | `client.headless_experimental` | `WebAuthn` | `client.web_authn` |
-| `HeapProfiler` | `client.heap_profiler` | `WebMCP` | `client.web_mcp` |
+| `FindInPage` | `client.find_in_page` | `WebAuthn` | `client.web_authn` |
+| `HeadlessExperimental` | `client.headless_experimental` | `WebMCP` | `client.web_mcp` |
+| `HeapProfiler` | `client.heap_profiler` |  |  |
 
 ## Listening for events
 
-Events are exposed as typed async streams:
+Pass a generated event class to `listen()`. The returned subscription is an
+async iterator of typed events:
 
 ```python
-from cdpify.domains.network.events import NetworkEvent, RequestWillBeSentEvent
+from cdpify.domains.network.events import RequestWillBeSentEvent
 
 
 await client.network.enable()
 
-async for event in client.listen(
-    event_name=NetworkEvent.REQUEST_WILL_BE_SENT,
-    event_type=RequestWillBeSentEvent,
-):
+async for event in client.listen(RequestWillBeSentEvent):
     print(event.request.method, event.request.url)
 ```
 
-`client.listen()` accepts an optional `timeout` in seconds and yields only
-events from the root connection. A session view applies the same rule to its
-bound target:
+The subscription is registered as soon as `listen()` is called, and events are
+buffered until you read them. To wait for an event that your own command
+triggers, subscribe first and then send the command:
+
+```python
+from cdpify.domains.page.events import LoadEventFiredEvent
+
+
+async with client.listen(LoadEventFiredEvent) as events:
+    await client.page.navigate(url="https://example.com")
+    await events.next(timeout=10)
+```
+
+Leaving the `async with` block unsubscribes. A stream also ends when the client
+disconnects; `events.next()` then raises `CDPStreamClosedError`. The optional
+`timeout` on `listen()` limits how long each read waits and raises
+`TimeoutError` when it expires.
+
+`client.listen()` yields only events from the root connection. A session view
+applies the same rule to its bound target:
 
 ```python
 tab = client.session("session-id")
 
-async for event in tab.listen(
-    event_name=NetworkEvent.REQUEST_WILL_BE_SENT,
-    event_type=RequestWillBeSentEvent,
-):
+async for event in tab.listen(RequestWillBeSentEvent):
     # This stream contains events from this session only.
     print(event.request.url)
 ```
@@ -177,15 +222,50 @@ To observe the root connection and all attached sessions together, use
 event model:
 
 ```python
-async for received in client.listen_all(
-    event_name=NetworkEvent.REQUEST_WILL_BE_SENT,
-    event_type=RequestWillBeSentEvent,
-):
+async for received in client.listen_all(RequestWillBeSentEvent):
     print(received.session_id, received.value.request.url)
 ```
 
 `received.session_id` is `None` for a root event. Generated event dataclasses
-contain only fields defined by the CDP specification.
+contain only fields defined by the CDP specification, plus their CDP name in
+`__cdp_event__`. To listen with your own dataclass, pass the name explicitly:
+`client.listen(MyEvent, event_name="Page.loadEventFired")`.
+
+An incoming event is decoded once per event class, when the first listener
+reads it. Matching `listen()`, `CdpSession.listen()`, and `listen_all()`
+subscriptions share that model (`received.value` for `listen_all()`). Treat
+event data as read-only: changing a shared model also changes what other
+listeners see. Make a deep copy when you need your own mutable instance:
+
+```python
+from copy import deepcopy
+
+owned_event = deepcopy(event)
+```
+
+Different incoming messages and different event classes have separate cached
+models. Unread events are not decoded. A cache is released when the last
+subscription has read or discarded the incoming event.
+
+### Limiting buffered events
+
+Set `max_queue_size` on `CdpClient` to limit each listener's buffer. The default,
+`0`, is unlimited. A full buffer discards its oldest event so slow consumers do
+not block command responses. Override the limit for an individual subscription:
+
+```python
+client = CdpClient(ws_url, max_queue_size=256)
+
+async with client:
+    async with client.listen(RequestWillBeSentEvent, max_queue_size=32) as events:
+        event = await events.next(timeout=10)
+        print(events.dropped_events)
+```
+
+The same options apply to `listen_all()` and `CdpSession.listen()`. Passing `0`
+to a listener disables its limit. `events.dropped_events` counts events evicted
+by that listener's buffer. Disconnecting drains the remaining buffered events;
+`aclose()` releases them immediately.
 
 ## Working with target sessions
 
@@ -194,10 +274,10 @@ Attach to a target in flat mode and create an immutable session view with
 session:
 
 ```python
-from cdpify import Client
+from cdpify import CdpClient
 
 
-async with Client(browser_ws_url) as root_client:
+async with CdpClient(browser_ws_url) as root_client:
     attached = await root_client.target.attach_to_target(
         target_id="target-id",
         flatten=True,
@@ -238,11 +318,12 @@ await tab.execute("Runtime.evaluate", {"expression": "1 + 1"})
 ## Configuration
 
 ```python
-client = Client(
+client = CdpClient(
     url="ws://localhost:9222/devtools/browser/...",
     additional_headers={"Authorization": "Bearer token"},
     max_frame_size=100 * 1024 * 1024,
     default_timeout=30.0,
+    max_queue_size=256,
 )
 ```
 
@@ -250,11 +331,20 @@ For another transport protocol, implement the exported `Transport` protocol
 and inject it directly:
 
 ```python
-from cdpify import Client
+from cdpify import CdpClient
 
-client = Client(transport=my_transport)
+client = CdpClient(transport=my_transport)
 ```
 
+Custom transports can optionally implement `CallbackTransport` from
+`cdpify.transport` to deliver events directly to the client. The default
+WebSocket transport uses this path to avoid an intermediate event queue.
+Transports that implement only `Transport.events()` continue to work.
+
+When using `WebSocketTransport.events()` directly, its `max_queue_size` option
+sets the same drop-oldest limit on its transport buffer; `dropped_events` counts
+those evictions. A client-supplied custom transport manages its own buffer limits.
+
 For methods not covered by the generated API, use the low-level escape hatch:
 
 ```python
@@ -264,6 +354,38 @@ result = await client.execute(
 )
 ```
 
+### Generated type aliases
+
+Generated aliases such as `FrameId`, `NodeId`, and `TargetFilter` use Python's
+`type` statement. Use them in annotations and pass ordinary Python values:
+
+```python
+from cdpify.domains.page import FrameId
+
+frame_id: FrameId = "F1"
+```
+
+Aliases are not constructors or runtime classes. Use `"F1"` directly rather
+than `FrameId("F1")`, and `isinstance(frame_id, str)` for a runtime check.
+
+### When Chrome deviates from the spec
+
+Chrome does not always send every field the protocol marks as required.
+Instead of failing, cdpify logs a warning on the `cdpify.codec` logger and
+sets the missing field to `None`, even if its type says otherwise. Unknown
+fields from newer Chrome versions are ignored.
+
+Deprecated CDP commands still work but emit a `DeprecationWarning`. Use
+Python's warning filters to silence them or turn them into errors:
+
+```python
+import warnings
+
+warnings.filterwarnings(
+    "ignore", category=DeprecationWarning, message=r"\w+\.\w+ is deprecated"
+)
+```
+
 ## Development
 
 Install the project and its development dependencies with
@@ -275,6 +397,10 @@ uv run pytest
 uv run ruff check . --exclude cdpify/domains
 ```
 
+Use `uv sync --dev --extra orjson` and `uv run --extra orjson pytest` to include
+the optional backend. CI installs this extra and tests both JSON backends on
+Ubuntu, Windows, and macOS with Python 3.12, 3.13, and 3.14.
+
 To download the latest protocol definitions and regenerate all domain clients:
 
 ```bash