diff --git a/scripts/codegen/config/docs.py b/scripts/codegen/config/docs.py index d973c25..67881ec 100644 --- a/scripts/codegen/config/docs.py +++ b/scripts/codegen/config/docs.py @@ -24,11 +24,13 @@ ), "query_selector": ( "Return a handle for the first element matching `selector`, or `None`. " - "The element's `innerHTML`/`outerHTML` are fetched only with `html=True`." + "The element's `innerHTML`/`outerHTML` are fetched only with `html=True`; " + "reading `inner_html` or `outer_html` without it raises `BAPValueError`." ), "query_selector_all": ( "Return handles for every element matching `selector`. " - "The elements' `innerHTML`/`outerHTML` are fetched only with `html=True`." + "The elements' `innerHTML`/`outerHTML` are fetched only with `html=True`; " + "reading `inner_html` or `outer_html` without it raises `BAPValueError`." ), } diff --git a/scripts/codegen/emit_docs.py b/scripts/codegen/emit_docs.py index 15a786f..90deeb4 100644 --- a/scripts/codegen/emit_docs.py +++ b/scripts/codegen/emit_docs.py @@ -102,6 +102,11 @@ def _class_page(identifier: str, title: str, class_: Class) -> str: "", ) ) + property_summary = _summary( + member.docstring.value if member.docstring else None + ) + if property_summary: + lines.extend((property_summary, "")) continue if not isinstance(member, Function): continue diff --git a/src/browserless_bap/_page_generated.py b/src/browserless_bap/_page_generated.py index 9a03866..69e7c00 100644 --- a/src/browserless_bap/_page_generated.py +++ b/src/browserless_bap/_page_generated.py @@ -630,7 +630,7 @@ async def query_selector( visible: bool | UnsetType = UNSET, html: bool | UnsetType = UNSET, ) -> ElementHandle | None: - "Return a handle for the first element matching `selector`, or `None`. The element's `innerHTML`/`outerHTML` are fetched only with `html=True`." + "Return a handle for the first element matching `selector`, or `None`. The element's `innerHTML`/`outerHTML` are fetched only with `html=True`; reading `inner_html` or `outer_html` without it raises `BAPValueError`." args = drop_unset( { "selector": selector, @@ -661,7 +661,7 @@ async def query_selector_all( visible: bool | UnsetType = UNSET, html: bool | UnsetType = UNSET, ) -> list[ElementHandle]: - "Return handles for every element matching `selector`. The elements' `innerHTML`/`outerHTML` are fetched only with `html=True`." + "Return handles for every element matching `selector`. The elements' `innerHTML`/`outerHTML` are fetched only with `html=True`; reading `inner_html` or `outer_html` without it raises `BAPValueError`." args = drop_unset( { "selector": selector, diff --git a/src/browserless_bap/page.py b/src/browserless_bap/page.py index 666ae4c..c5752bb 100644 --- a/src/browserless_bap/page.py +++ b/src/browserless_bap/page.py @@ -344,9 +344,8 @@ async def response( body: bool | UnsetType = UNSET, body_encoding: bool | UnsetType = UNSET, ) -> list[ResponseResponse]: - """List responses; fetch bodies only with body=True. - - body_encoding=True implies body=True and adds the base64Encoded flag. + """List responses. Bodies are fetched only with body=True or body_encoding=True; + body_encoding=True also adds the base64Encoded flag. """ args = _drop_unset( { diff --git a/src/browserless_bap/sync_api/_page_generated.py b/src/browserless_bap/sync_api/_page_generated.py index 28c116a..16b1e8a 100644 --- a/src/browserless_bap/sync_api/_page_generated.py +++ b/src/browserless_bap/sync_api/_page_generated.py @@ -479,7 +479,7 @@ def query_selector( visible: bool | UnsetType = UNSET, html: bool | UnsetType = UNSET, ) -> ElementHandle | None: - "Return a handle for the first element matching `selector`, or `None`. The element's `innerHTML`/`outerHTML` are fetched only with `html=True`." + "Return a handle for the first element matching `selector`, or `None`. The element's `innerHTML`/`outerHTML` are fetched only with `html=True`; reading `inner_html` or `outer_html` without it raises `BAPValueError`." return cast( "ElementHandle | None", self._invoke( @@ -499,7 +499,7 @@ def query_selector_all( visible: bool | UnsetType = UNSET, html: bool | UnsetType = UNSET, ) -> list[ElementHandle]: - "Return handles for every element matching `selector`. The elements' `innerHTML`/`outerHTML` are fetched only with `html=True`." + "Return handles for every element matching `selector`. The elements' `innerHTML`/`outerHTML` are fetched only with `html=True`; reading `inner_html` or `outer_html` without it raises `BAPValueError`." return cast( "list[ElementHandle]", self._invoke( diff --git a/src/browserless_bap/sync_api/element_handle.py b/src/browserless_bap/sync_api/element_handle.py index 088c888..b05cd67 100644 --- a/src/browserless_bap/sync_api/element_handle.py +++ b/src/browserless_bap/sync_api/element_handle.py @@ -13,6 +13,7 @@ class ElementHandle(SyncBase[Any]): @property def inner_html(self) -> str | None: + """Element HTML. Requires html=True on the query that produced this handle.""" return cast(str | None, self._impl.inner_html) @property @@ -33,6 +34,7 @@ def local_name(self) -> str | None: @property def outer_html(self) -> str | None: + """Element markup. Requires html=True on the query that produced this handle.""" return cast(str | None, self._impl.outer_html) @property diff --git a/src/browserless_bap/sync_api/page.py b/src/browserless_bap/sync_api/page.py index 99bd849..c68e853 100644 --- a/src/browserless_bap/sync_api/page.py +++ b/src/browserless_bap/sync_api/page.py @@ -221,9 +221,8 @@ def response( body: bool | UnsetType = UNSET, body_encoding: bool | UnsetType = UNSET, ) -> list[ResponseResponse]: - """List responses; fetch bodies only with body=True. - - body_encoding=True implies body=True and adds the base64Encoded flag. + """List responses. Bodies are fetched only with body=True or body_encoding=True; + body_encoding=True also adds the base64Encoded flag. """ return cast( list[ResponseResponse], diff --git a/tests/test_codegen_docs.py b/tests/test_codegen_docs.py index c2b8169..6616189 100644 --- a/tests/test_codegen_docs.py +++ b/tests/test_codegen_docs.py @@ -59,6 +59,16 @@ def test_docs_cli_emits_deterministic_docusaurus_reference(tmp_path: Path) -> No assert "## `closed`" in before[Path("sync-page.mdx")] assert "## `inner_html`" in before[Path("async-element-handle.mdx")] assert "## `selector`" in before[Path("sync-element-handle.mdx")] + for page in ("async-element-handle.mdx", "sync-element-handle.mdx"): + assert ( + "Requires html=True on the query that produced this handle." + in before[Path(page)] + ) + for page in ("async-page.mdx", "sync-page.mdx"): + assert ( + "body_encoding=True also adds the base64Encoded flag." in before[Path(page)] + ) + assert "raises `BAPValueError`" in before[Path(page)] assert "listener_count(event: str) -> int" in before[Path("sync-page.mdx")] assert "Wait for the next event payload" in before[Path("async-page.mdx")] assert "Start tracking" in before[Path("sync-page.mdx")]