Simplified API

* Fix mypy errors regarding incomplete type names for CDP types imported
  from other modules.
* Update tests to match previous bullet.
* Regenerate modules.

Author: mehaase

generator/generate.py

@@ -14,6 +14,9 @@
     ForwardRef = typing._ForwardRef # type: ignore
 
 
+cdp_modules = None
+
+
 def indent(text: str, count: int):
     ''' Indent text with the specified number of spaces. '''
     return tw_indent(text, ' '  * count)
@@ -23,18 +26,17 @@ def main():
     ''' Main entry point. '''
     root = pathlib.Path(__file__).resolve().parent.parent / 'trio_cdp' / 'generated'
     clean(root)
-    modules = list()
-    for name, module in inspect.getmembers(cdp):
-        if name.startswith('_') or name in ('cdp', 'util'):
-            continue
-        modules.append(name)
+    ignored = lambda name: name.startswith('_') or name in ('cdp', 'util')
+    global cdp_modules
+    cdp_modules = {n:m for n,m in inspect.getmembers(cdp) if not ignored(n)}
+    for name, module in cdp_modules.items():
         generate_module(root, name, module)
     init = root / '__init__.py'
     with init.open('w') as file:
         file.write('# DO NOT EDIT THIS FILE!\n#\n')
         file.write('# This code is generated off of PyCDP modules. If you need to make\n')
         file.write('# changes, edit the generator and regenerate all of the modules.\n\n')
-        for module in modules:
+        for module in cdp_modules:
             file.write(f'from . import {module}\n')
 
 
@@ -45,17 +47,18 @@ def clean(root: pathlib.Path):
             path.unlink()
 
 
-def generate_module(root: pathlib.Path, module_name: str, module: types.ModuleType):
+def generate_module(root: pathlib.Path, module_name: str, 
+        module: types.ModuleType):
     ''' Generate code for a module. '''
     print('* Generating module:', module_name)
     module_path = root / f'{module_name}.py'
     commands = list()
     classes = list()
     for name, obj in inspect.getmembers(module):
-        if name.startswith('_') or name in ('dataclass', 'event_class'):
+        if name.startswith('_') or name in ('dataclass', 'deprecated', 'event_class'):
             continue
         if inspect.isfunction(obj):
-            commands.append(generate_command(module_name, name, obj))
+            commands.append(generate_command(module, module_name, obj))
         elif inspect.isclass(obj):
             classes.append(name)
 
@@ -76,16 +79,19 @@ def generate_module(root: pathlib.Path, module_name: str, module: types.ModuleTy
         file.write('\n\n'.join(commands))
 
 
-def generate_command(module: str, name: str, fn: types.FunctionType):
+def generate_command(module: types.ModuleType, module_name: str, 
+        fn: types.FunctionType):
     ''' Generate code for one command, i.e. one PyCDP wrapper function. '''
-    print(f'  - {name}()')
+    fn_name = fn.__name__
+    print(f'  - {fn_name}()')
     sig = inspect.signature(fn)
+    type_hints = typing.get_type_hints(fn, globalns=vars(module), localns=None)
 
     # Generate the argument list.
     args = list()
     call_args = list()
     for param in sig.parameters.values():
-        ann = format_annotation(param.annotation)
+        ann = format_annotation(module, type_hints[param.name])
         if param.default != inspect.Parameter.empty:
             default_str = f' = {param.default}'
         else:
@@ -107,18 +113,18 @@ def generate_command(module: str, name: str, fn: types.FunctionType):
         doc = ''
 
     # The original function returns a generator. We want to grab the return type of the
-    # generator and set that as the return type of this wrapper function.
-    return_type = format_annotation(sig.return_annotation.__args__[2])
+    # generator and set that as the return type of this wrapper function.        
+    return_type = format_annotation(module, type_hints['return'].__args__[2])
 
     # Format the function and return it as a string.
-    ctx_name, ctx_fn = which_context(module, name)
-    body = f"{ctx_name} = {ctx_fn}('{module}.{name}')\n"
-    body += f"return await {ctx_name}.execute(cdp.{module}.{name}({call_arg_str}))"
+    ctx_name, ctx_fn = which_context(module_name, fn_name)
+    body = f"{ctx_name} = {ctx_fn}('{module_name}.{fn_name}')\n"
+    body += f"return await {ctx_name}.execute(cdp.{module_name}.{fn_name}({call_arg_str}))"
     body = indent(body, 4)
-    return f'async def {name}({arg_str}) -> {return_type}:\n{doc}{body}\n'
+    return f'async def {fn_name}({arg_str}) -> {return_type}:\n{doc}{body}\n'
 
 
-def format_annotation(ann: typing.Any):
+def format_annotation(current_module: types.ModuleType, ann: typing.Any):
     '''
     Given a type annotation, return a stringified version.
 
@@ -127,32 +133,31 @@ def format_annotation(ann: typing.Any):
     have to access private members to figure out what the specific annotation actually
     is.
     '''
-    if isinstance(ann, str):
-        ann_str = ann
-    elif isinstance(ann, ForwardRef):
-        ann_str = ann.__forward_arg__
-    elif ann in (bool, dict, float, int, str):
-        ann_str = ann.__name__
-    elif ann is type(None):
+    if ann is type(None):
         ann_str = 'None'
+    elif isinstance(ann, type):
+        if ann.__module__ not in (current_module.__name__, 'builtins'):
+            ann_str = f'{ann.__module__}.{ann.__name__}'
+        else:
+            ann_str = ann.__name__
     elif ann._name == 'Any':
         ann_str = 'typing.Any'
     elif ann._name == 'List':
-        nested_ann = format_annotation(ann.__args__[0])
+        nested_ann = format_annotation(current_module, ann.__args__[0])
         ann_str = f'typing.List[{nested_ann}]'
     elif ann._name == 'Tuple':
-        nested_anns = ', '.join(format_annotation(a) for a in ann.__args__)
+        nested_anns = ', '.join(format_annotation(current_module, a) for a in ann.__args__)
         ann_str = f'typing.Tuple[{nested_anns}]'
     elif ann._name is None and len(ann.__args__) > 1:
         # For some reason union annotations don't have a name?
         # If the union has two members and one of them is NoneType, then it's really
         # a typing.Optional.
         if len(ann.__args__) == 2 and any(a is type(None) for a in ann.__args__):
-            nested_ann = format_annotation(
-                [a for a in ann.__args__ if a is not type(None)][0])
+            opt_type = [a for a in ann.__args__ if a is not type(None)][0]
+            nested_ann = format_annotation(current_module, opt_type)
             ann_str = f'typing.Optional[{nested_ann}]'
         else:
-            nested_anns = ', '.join(format_annotation(a) for a in ann.__args__)
+            nested_anns = ', '.join(format_annotation(current_module, a) for a in ann.__args__)
             ann_str = f'typing.Union[{nested_anns}]'
     else:
         raise Exception(f'Cannot format annotation: {repr(ann)}')

generator/test_generate.py

@@ -5,15 +5,15 @@
 from .generate import generate_command
 
 
-def test_generate_command():
+def test_dom_query_selector():
 
     expected = dedent("""\
         async def query_selector(
                 node_id: NodeId,
                 selector: str
             ) -> NodeId:
             '''
-            Executes `querySelector` on a given node.
+            Executes ``querySelector`` on a given node.
 
             :param node_id: Id of the node to query upon.
             :param selector: Selector string.
@@ -23,4 +23,45 @@ async def query_selector(
             return await session.execute(cdp.dom.query_selector(node_id, selector))
     """)
 
-    assert expected == generate_command('dom', 'query_selector', cdp.dom.query_selector)
+    assert expected == generate_command(cdp.dom, 'dom', cdp.dom.query_selector)
+
+
+def test_accessibility_disable():
+    expected = dedent("""\
+        async def disable() -> None:
+            '''
+            Disables the accessibility domain.
+            '''
+            session = get_session_context('accessibility.disable')
+            return await session.execute(cdp.accessibility.disable())
+    """)
+
+    assert expected == generate_command(cdp.accessibility, 'accessibility',
+        cdp.accessibility.disable)
+
+
+def test_accessibility_get_partial_ax_tree():
+    expected = dedent("""\
+        async def get_partial_ax_tree(
+                node_id: typing.Optional[cdp.dom.NodeId] = None,
+                backend_node_id: typing.Optional[cdp.dom.BackendNodeId] = None,
+                object_id: typing.Optional[cdp.runtime.RemoteObjectId] = None,
+                fetch_relatives: typing.Optional[bool] = None
+            ) -> typing.List[AXNode]:
+            '''
+            Fetches the accessibility node and partial accessibility tree for this DOM node, if it exists.
+
+            **EXPERIMENTAL**
+
+            :param node_id: *(Optional)* Identifier of the node to get the partial accessibility tree for.
+            :param backend_node_id: *(Optional)* Identifier of the backend node to get the partial accessibility tree for.
+            :param object_id: *(Optional)* JavaScript object id of the node wrapper to get the partial accessibility tree for.
+            :param fetch_relatives: *(Optional)* Whether to fetch this nodes ancestors, siblings and children. Defaults to true.
+            :returns: The ``Accessibility.AXNode`` for this DOM node, if it exists, plus its ancestors, siblings and children, if requested.
+            '''
+            session = get_session_context('accessibility.get_partial_ax_tree')
+            return await session.execute(cdp.accessibility.get_partial_ax_tree(node_id, backend_node_id, object_id, fetch_relatives))
+    """)
+
+    assert expected == generate_command(cdp.accessibility, 'accessibility',
+        cdp.accessibility.get_partial_ax_tree)

trio_cdp/generated/__init__.py

@@ -25,7 +25,7 @@
 from . import headless_experimental
 from . import heap_profiler
 from . import indexed_db
-from . import input
+from . import input_
 from . import inspector
 from . import io
 from . import layer_tree

trio_cdp/generated/accessibility.py

@@ -33,7 +33,7 @@ async def disable() -> None:
 
 async def enable() -> None:
     '''
-    Enables the accessibility domain which causes `AXNodeId`s to remain consistent between method calls.
+    Enables the accessibility domain which causes ``AXNodeId``'s to remain consistent between method calls.
     This turns on accessibility for the page, which can impact performance until accessibility is disabled.
     '''
     session = get_session_context('accessibility.enable')
@@ -44,27 +44,30 @@ async def get_full_ax_tree() -> typing.List[AXNode]:
     '''
     Fetches the entire accessibility tree
 
+    **EXPERIMENTAL**
+
     :returns: 
     '''
     session = get_session_context('accessibility.get_full_ax_tree')
     return await session.execute(cdp.accessibility.get_full_ax_tree())
 
 
 async def get_partial_ax_tree(
-        node_id: typing.Optional[dom.NodeId] = None,
-        backend_node_id: typing.Optional[dom.BackendNodeId] = None,
-        object_id: typing.Optional[runtime.RemoteObjectId] = None,
+        node_id: typing.Optional[cdp.dom.NodeId] = None,
+        backend_node_id: typing.Optional[cdp.dom.BackendNodeId] = None,
+        object_id: typing.Optional[cdp.runtime.RemoteObjectId] = None,
         fetch_relatives: typing.Optional[bool] = None
     ) -> typing.List[AXNode]:
     '''
     Fetches the accessibility node and partial accessibility tree for this DOM node, if it exists.
 
-    :param node_id: Identifier of the node to get the partial accessibility tree for.
-    :param backend_node_id: Identifier of the backend node to get the partial accessibility tree for.
-    :param object_id: JavaScript object id of the node wrapper to get the partial accessibility tree for.
-    :param fetch_relatives: Whether to fetch this nodes ancestors, siblings and children. Defaults to true.
-    :returns: The ``Accessibility.AXNode`` for this DOM node, if it exists, plus its ancestors, siblings and
-    children, if requested.
+    **EXPERIMENTAL**
+
+    :param node_id: *(Optional)* Identifier of the node to get the partial accessibility tree for.
+    :param backend_node_id: *(Optional)* Identifier of the backend node to get the partial accessibility tree for.
+    :param object_id: *(Optional)* JavaScript object id of the node wrapper to get the partial accessibility tree for.
+    :param fetch_relatives: *(Optional)* Whether to fetch this nodes ancestors, siblings and children. Defaults to true.
+    :returns: The ``Accessibility.AXNode`` for this DOM node, if it exists, plus its ancestors, siblings and children, if requested.
     '''
     session = get_session_context('accessibility.get_partial_ax_tree')
     return await session.execute(cdp.accessibility.get_partial_ax_tree(node_id, backend_node_id, object_id, fetch_relatives))

trio_cdp/generated/animation.py

@@ -37,16 +37,16 @@ async def enable() -> None:
 
 
 async def get_current_time(
-        id: str
+        id_: str
     ) -> float:
     '''
     Returns the current time of the an animation.
 
-    :param id: Id of animation.
+    :param id_: Id of animation.
     :returns: Current time of the page.
     '''
     session = get_session_context('animation.get_current_time')
-    return await session.execute(cdp.animation.get_current_time(id))
+    return await session.execute(cdp.animation.get_current_time(id_))
 
 
 async def get_playback_rate() -> float:
@@ -73,7 +73,7 @@ async def release_animations(
 
 async def resolve_animation(
         animation_id: str
-    ) -> runtime.RemoteObject:
+    ) -> cdp.runtime.RemoteObject:
     '''
     Gets the remote object of the Animation.
 

trio_cdp/generated/application_cache.py

@@ -27,7 +27,7 @@ async def enable() -> None:
 
 
 async def get_application_cache_for_frame(
-        frame_id: page.FrameId
+        frame_id: cdp.page.FrameId
     ) -> ApplicationCache:
     '''
     Returns relevant application cache data for the document in given frame.
@@ -44,15 +44,14 @@ async def get_frames_with_manifests() -> typing.List[FrameWithManifest]:
     Returns array of frame identifiers with manifest urls for each frame containing a document
     associated with some application cache.
 
-    :returns: Array of frame identifiers with manifest urls for each frame containing a document
-    associated with some application cache.
+    :returns: Array of frame identifiers with manifest urls for each frame containing a document associated with some application cache.
     '''
     session = get_session_context('application_cache.get_frames_with_manifests')
     return await session.execute(cdp.application_cache.get_frames_with_manifests())
 
 
 async def get_manifest_for_frame(
-        frame_id: page.FrameId
+        frame_id: cdp.page.FrameId
     ) -> str:
     '''
     Returns manifest URL for document in the given frame.

trio_cdp/generated/audits.py

@@ -11,7 +11,7 @@
 import cdp.audits
 
 async def get_encoded_response(
-        request_id: network.RequestId,
+        request_id: cdp.network.RequestId,
         encoding: str,
         quality: typing.Optional[float] = None,
         size_only: typing.Optional[bool] = None
@@ -22,12 +22,13 @@ async def get_encoded_response(
 
     :param request_id: Identifier of the network request to get content for.
     :param encoding: The encoding to use.
-    :param quality: The quality of the encoding (0-1). (defaults to 1)
-    :param size_only: Whether to only return the size information (defaults to false).
-    :returns: a tuple with the following items:
-        0. body: (Optional) The encoded body as a base64 string. Omitted if sizeOnly is true.
-        1. originalSize: Size before re-encoding.
-        2. encodedSize: Size after re-encoding.
+    :param quality: *(Optional)* The quality of the encoding (0-1). (defaults to 1)
+    :param size_only: *(Optional)* Whether to only return the size information (defaults to false).
+    :returns: A tuple with the following items:
+
+        0. **body** – *(Optional)* The encoded body as a base64 string. Omitted if sizeOnly is true.
+        1. **originalSize** – Size before re-encoding.
+        2. **encodedSize** – Size after re-encoding.
     '''
     session = get_session_context('audits.get_encoded_response')
     return await session.execute(cdp.audits.get_encoded_response(request_id, encoding, quality, size_only))