Merge pull request #14 from HyperionGray/generator_improvements

Generator improvements

Author: domderen

cdp/browser.py

@@ -302,9 +302,7 @@ def get_histograms(
     '''
     Get Chrome histograms.
 
-    :param query: Requested substring in name. Only histograms which have query as a
-    substring in their name are extracted. An empty or absent query returns
-    all histograms.
+    :param query: Requested substring in name. Only histograms which have query as a substring in their name are extracted. An empty or absent query returns all histograms.
     :param delta: If true, retrieve delta since last call.
     :returns: Histograms.
     '''
@@ -398,8 +396,7 @@ def set_window_bounds(
     Set position and/or size of the browser window.
 
     :param window_id: Browser window id.
-    :param bounds: New window bounds. The 'minimized', 'maximized' and 'fullscreen' states cannot be combined
-    with 'left', 'top', 'width' or 'height'. Leaves unspecified fields unchanged.
+    :param bounds: New window bounds. The 'minimized', 'maximized' and 'fullscreen' states cannot be combined with 'left', 'top', 'width' or 'height'. Leaves unspecified fields unchanged.
     '''
     params: T_JSON_DICT = dict()
     params['windowId'] = window_id.to_json()

cdp/debugger.py

@@ -297,8 +297,7 @@ def enable(
     Enables debugger for the given page. Clients should not assume that the debugging has been
     enabled until the result for this command is received.
 
-    :param max_scripts_cache_size: The maximum size in bytes of collected scripts (not referenced by other heap objects)
-    the debugger can hold. Puts no limit if paramter is omitted.
+    :param max_scripts_cache_size: The maximum size in bytes of collected scripts (not referenced by other heap objects) the debugger can hold. Puts no limit if paramter is omitted.
     :returns: Unique identifier of the debugger.
     '''
     params: T_JSON_DICT = dict()
@@ -328,12 +327,9 @@ def evaluate_on_call_frame(
 
     :param call_frame_id: Call frame identifier to evaluate on.
     :param expression: Expression to evaluate.
-    :param object_group: String object group name to put result into (allows rapid releasing resulting object handles
-    using ``releaseObjectGroup``).
-    :param include_command_line_api: Specifies whether command line API should be available to the evaluated expression, defaults
-    to false.
-    :param silent: In silent mode exceptions thrown during evaluation are not reported and do not pause
-    execution. Overrides ``setPauseOnException`` state.
+    :param object_group: String object group name to put result into (allows rapid releasing resulting object handles using ``releaseObjectGroup``).
+    :param include_command_line_api: Specifies whether command line API should be available to the evaluated expression, defaults to false.
+    :param silent: In silent mode exceptions thrown during evaluation are not reported and do not pause execution. Overrides ``setPauseOnException`` state.
     :param return_by_value: Whether the result is expected to be a JSON object that should be sent by value.
     :param generate_preview: Whether preview should be generated for the result.
     :param throw_on_side_effect: Whether to throw an exception if side effect cannot be ruled out during evaluation.
@@ -380,8 +376,7 @@ def get_possible_breakpoints(
     the same.
 
     :param start: Start of range to search possible breakpoint locations in.
-    :param end: End of range to search possible breakpoint locations in (excluding). When not specified, end
-    of scripts is used as end of range.
+    :param end: End of range to search possible breakpoint locations in (excluding). When not specified, end of scripts is used as end of range.
     :param restrict_to_function: Only consider locations which are in the same (non-nested) function as start.
     :returns: List of the possible breakpoint locations.
     '''
@@ -551,8 +546,7 @@ def set_async_call_stack_depth(
     '''
     Enables or disables async call stacks tracking.
 
-    :param max_depth: Maximum depth of async call stacks. Setting to ``0`` will effectively disable collecting async
-    call stacks (default).
+    :param max_depth: Maximum depth of async call stacks. Setting to ``0`` will effectively disable collecting async call stacks (default).
     '''
     params: T_JSON_DICT = dict()
     params['maxDepth'] = max_depth
@@ -613,8 +607,7 @@ def set_breakpoint(
     Sets JavaScript breakpoint at a given location.
 
     :param location: Location to set breakpoint in.
-    :param condition: Expression to use as a breakpoint condition. When specified, debugger will only stop on the
-    breakpoint if this expression evaluates to true.
+    :param condition: Expression to use as a breakpoint condition. When specified, debugger will only stop on the breakpoint if this expression evaluates to true.
     :returns: a tuple with the following items:
         0. breakpointId: Id of the created breakpoint for further reference.
         1. actualLocation: Location this breakpoint resolved into.
@@ -669,12 +662,10 @@ def set_breakpoint_by_url(
 
     :param line_number: Line number to set breakpoint at.
     :param url: URL of the resources to set breakpoint on.
-    :param url_regex: Regex pattern for the URLs of the resources to set breakpoints on. Either ``url`` or
-    ``urlRegex`` must be specified.
+    :param url_regex: Regex pattern for the URLs of the resources to set breakpoints on. Either ``url`` or ``urlRegex`` must be specified.
     :param script_hash: Script hash of the resources to set breakpoint on.
     :param column_number: Offset in the line to set breakpoint at.
-    :param condition: Expression to use as a breakpoint condition. When specified, debugger will only stop on the
-    breakpoint if this expression evaluates to true.
+    :param condition: Expression to use as a breakpoint condition. When specified, debugger will only stop on the breakpoint if this expression evaluates to true.
     :returns: a tuple with the following items:
         0. breakpointId: Id of the created breakpoint for further reference.
         1. locations: List of the locations this breakpoint resolved into upon addition.
@@ -712,8 +703,7 @@ def set_breakpoint_on_function_call(
     calling it will also trigger the breakpoint.
 
     :param object_id: Function object id.
-    :param condition: Expression to use as a breakpoint condition. When specified, debugger will
-    stop on the breakpoint if this expression evaluates to true.
+    :param condition: Expression to use as a breakpoint condition. When specified, debugger will stop on the breakpoint if this expression evaluates to true.
     :returns: Id of the created breakpoint for further reference.
     '''
     params: T_JSON_DICT = dict()
@@ -790,8 +780,7 @@ def set_script_source(
 
     :param script_id: Id of the script to edit.
     :param script_source: New content of the script.
-    :param dry_run: If true the change will not actually be applied. Dry run may be used to get result
-    description without actually modifying the code.
+    :param dry_run: If true the change will not actually be applied. Dry run may be used to get result description without actually modifying the code.
     :returns: a tuple with the following items:
         0. callFrames: (Optional) New stack trace in case editing has happened while VM was stopped.
         1. stackChanged: (Optional) Whether current call stack  was modified after applying the changes.
@@ -845,8 +834,7 @@ def set_variable_value(
     Changes value of variable in a callframe. Object-based scopes are not supported and must be
     mutated manually.
 
-    :param scope_number: 0-based number of scope as was listed in scope chain. Only 'local', 'closure' and 'catch'
-    scope types are allowed. Other scopes could be manipulated manually.
+    :param scope_number: 0-based number of scope as was listed in scope chain. Only 'local', 'closure' and 'catch' scope types are allowed. Other scopes could be manipulated manually.
     :param variable_name: Variable name.
     :param new_value: New variable value.
     :param call_frame_id: Id of callframe that holds variable.
@@ -869,8 +857,7 @@ def step_into(
     '''
     Steps into the function call.
 
-    :param break_on_async_call: Debugger will issue additional Debugger.paused notification if any async task is scheduled
-    before next pause.
+    :param break_on_async_call: Debugger will issue additional Debugger.paused notification if any async task is scheduled before next pause.
     '''
     params: T_JSON_DICT = dict()
     if break_on_async_call is not None:

cdp/dom.py

@@ -498,8 +498,7 @@ def copy_to(
 
     :param node_id: Id of the node to copy.
     :param target_node_id: Id of the element to drop the copy into.
-    :param insert_before_node_id: Drop the copy before this node (if absent, the copy becomes the last child of
-    ``targetNodeId``).
+    :param insert_before_node_id: Drop the copy before this node (if absent, the copy becomes the last child of ``targetNodeId``).
     :returns: Id of the node clone.
     '''
     params: T_JSON_DICT = dict()
@@ -529,10 +528,8 @@ def describe_node(
     :param node_id: Identifier of the node.
     :param backend_node_id: Identifier of the backend node.
     :param object_id: JavaScript object id of the node wrapper.
-    :param depth: The maximum depth at which children should be retrieved, defaults to 1. Use -1 for the
-    entire subtree or provide an integer larger than 0.
-    :param pierce: Whether or not iframes and shadow roots should be traversed when returning the subtree
-    (default is false).
+    :param depth: The maximum depth at which children should be retrieved, defaults to 1. Use -1 for the entire subtree or provide an integer larger than 0.
+    :param pierce: Whether or not iframes and shadow roots should be traversed when returning the subtree (default is false).
     :returns: Node description.
     '''
     params: T_JSON_DICT = dict()
@@ -701,10 +698,8 @@ def get_document(
     '''
     Returns the root DOM node (and optionally the subtree) to the caller.
 
-    :param depth: The maximum depth at which children should be retrieved, defaults to 1. Use -1 for the
-    entire subtree or provide an integer larger than 0.
-    :param pierce: Whether or not iframes and shadow roots should be traversed when returning the subtree
-    (default is false).
+    :param depth: The maximum depth at which children should be retrieved, defaults to 1. Use -1 for the entire subtree or provide an integer larger than 0.
+    :param pierce: Whether or not iframes and shadow roots should be traversed when returning the subtree (default is false).
     :returns: Resulting node.
     '''
     params: T_JSON_DICT = dict()
@@ -727,10 +722,8 @@ def get_flattened_document(
     '''
     Returns the root DOM node (and optionally the subtree) to the caller.
 
-    :param depth: The maximum depth at which children should be retrieved, defaults to 1. Use -1 for the
-    entire subtree or provide an integer larger than 0.
-    :param pierce: Whether or not iframes and shadow roots should be traversed when returning the subtree
-    (default is false).
+    :param depth: The maximum depth at which children should be retrieved, defaults to 1. Use -1 for the entire subtree or provide an integer larger than 0.
+    :param pierce: Whether or not iframes and shadow roots should be traversed when returning the subtree (default is false).
     :returns: Resulting node.
     '''
     params: T_JSON_DICT = dict()
@@ -901,8 +894,7 @@ def move_to(
 
     :param node_id: Id of the node to move.
     :param target_node_id: Id of the element to drop the moved node into.
-    :param insert_before_node_id: Drop node before this one (if absent, the moved node becomes the last child of
-    ``targetNodeId``).
+    :param insert_before_node_id: Drop node before this one (if absent, the moved node becomes the last child of ``targetNodeId``).
     :returns: New id of the moved node.
     '''
     params: T_JSON_DICT = dict()
@@ -1088,10 +1080,8 @@ def request_child_nodes(
     the specified depth.
 
     :param node_id: Id of the node to get children for.
-    :param depth: The maximum depth at which children should be retrieved, defaults to 1. Use -1 for the
-    entire subtree or provide an integer larger than 0.
-    :param pierce: Whether or not iframes and shadow roots should be traversed when returning the sub-tree
-    (default is false).
+    :param depth: The maximum depth at which children should be retrieved, defaults to 1. Use -1 for the entire subtree or provide an integer larger than 0.
+    :param pierce: Whether or not iframes and shadow roots should be traversed when returning the sub-tree (default is false).
     '''
     params: T_JSON_DICT = dict()
     params['nodeId'] = node_id.to_json()
@@ -1193,8 +1183,7 @@ def set_attributes_as_text(
 
     :param node_id: Id of the element to set attributes for.
     :param text: Text with a number of attributes. Will parse this text using HTML parser.
-    :param name: Attribute name to replace with new attributes derived from text in case text parsed
-    successfully.
+    :param name: Attribute name to replace with new attributes derived from text in case text parsed successfully.
     '''
     params: T_JSON_DICT = dict()
     params['nodeId'] = node_id.to_json()

cdp/dom_debugger.py

@@ -110,10 +110,8 @@ def get_event_listeners(
     Returns event listeners of the given object.
 
     :param object_id: Identifier of the object to return listeners for.
-    :param depth: The maximum depth at which Node children should be retrieved, defaults to 1. Use -1 for the
-    entire subtree or provide an integer larger than 0.
-    :param pierce: Whether or not iframes and shadow roots should be traversed when returning the subtree
-    (default is false). Reports listeners for all contexts if pierce is enabled.
+    :param depth: The maximum depth at which Node children should be retrieved, defaults to 1. Use -1 for the entire subtree or provide an integer larger than 0.
+    :param pierce: Whether or not iframes and shadow roots should be traversed when returning the subtree (default is false). Reports listeners for all contexts if pierce is enabled.
     :returns: Array of relevant listeners.
     '''
     params: T_JSON_DICT = dict()
@@ -233,8 +231,7 @@ def set_event_listener_breakpoint(
     Sets breakpoint on particular DOM event.
 
     :param event_name: DOM Event name to stop on (any DOM event will do).
-    :param target_name: EventTarget interface name to stop on. If equal to ``"*"`` or not provided, will stop on any
-    EventTarget.
+    :param target_name: EventTarget interface name to stop on. If equal to ``"*"`` or not provided, will stop on any EventTarget.
     '''
     params: T_JSON_DICT = dict()
     params['eventName'] = event_name

cdp/dom_snapshot.py

@@ -16,6 +16,7 @@
 from . import dom
 from . import dom_debugger
 from . import page
+from deprecated.sphinx import deprecated # type: ignore
 
 
 @dataclass
@@ -738,13 +739,16 @@ def enable() -> typing.Generator[T_JSON_DICT,T_JSON_DICT,None]:
     json = yield cmd_dict
 
 
+@deprecated(version="1.3")
 def get_snapshot(
         computed_style_whitelist: typing.List[str],
         include_event_listeners: typing.Optional[bool] = None,
         include_paint_order: typing.Optional[bool] = None,
         include_user_agent_shadow_tree: typing.Optional[bool] = None
     ) -> typing.Generator[T_JSON_DICT,T_JSON_DICT,typing.Tuple[typing.List['DOMNode'], typing.List['LayoutTreeNode'], typing.List['ComputedStyle']]]:
     '''
+    .. deprecated:: 1.3
+
     Returns a document snapshot, including the full DOM tree of the root node (including iframes,
     template contents, and imported documents) in a flattened array, as well as layout and
     white-listed computed style information for the nodes. Shadow DOM in the returned DOM tree is