mokr.execution ============== .. py:module:: mokr.execution Submodules ---------- .. toctree:: :maxdepth: 1 /autoapi/mokr/execution/context/index /autoapi/mokr/execution/handle/index Classes ------- .. autoapisummary:: mokr.execution.ExecutionContext mokr.execution.ElementHandle mokr.execution.JavascriptHandle Package Contents ---------------- .. py:class:: ExecutionContext(client: mokr.connection.DevtoolsConnection, context_payload: dict, object_handle_factory: Any, frame: mokr.frame.Frame = None) Class to handle execution of JavaScript functions, element manipulation, and associated runtime error translation. :param client: Remote connection from parent. :type client: DevtoolsConnection :param context_payload: Context from triggering event. :type context_payload: dict :param object_handle_factory: Factory for handling remote objects. Should create `mokr.execution.JavascriptHandle` based objects. :type object_handle_factory: Any :param frame: The `mokr.frame.Frame` that spawned this. Defaults to None. :type frame: Frame, optional .. py:property:: frame :type: mokr.frame.Frame | None Parent `mokr.frame.Frame` that spawned this. .. py:method:: evaluate(page_function: str, *args: Any, force_expr: bool = False) -> Any :async: Run `ExecutionContext.evaluate_handle` and try to run `mokr.execution.JavascriptHandle.json` on the result to return the object as a dictionary. :param page_function: JavaScript function to run. :type page_function: str :param force_expr: If True, treat `page_function` as an expression. Otherwise, automatically determine if it is a function or an expression. Defaults to False. :type force_expr: bool :raises mokr.exceptions.NetworkError: :raises either evaluating the function or requesting the resulting object.: :returns: The decoded object (dict) via `mokr.execution.JavascriptHandle.json` or None if a known error occurs decoding it. :rtype: dict | None .. py:method:: evaluate_handle(page_function: str, *args: Any, force_expr: bool = False, eval_script_url_suffix: str | None = None) -> mokr.execution.handle.javascript.JavascriptHandle :async: Execute a JavaScript function with given arguments. :param page_function: JavaScript function to run. :type page_function: str :raises ElementHandleError: Raised if execution fails. :returns: `mokr.execution.JavascriptHandle`. :rtype: JavascriptHandle .. py:method:: query_objects(javascript_handle: mokr.execution.handle.javascript.JavascriptHandle) -> mokr.execution.handle.javascript.JavascriptHandle :async: Query all objects with the given `mokr.execution.JavascriptHandle`'s `get_property("objectId")`. :param javascript_handle: A valid (not disposed) `mokr.execution.JavascriptHandle` object. :type javascript_handle: JavascriptHandle :raises ElementHandleError: Raised if the given handle is disposed, or does not have an "objectId" remote property (primitive type). :returns: A `mokr.execution.JavascriptHandle` initialised from the remot response. :rtype: JavascriptHandle .. py:class:: ElementHandle(context: mokr.execution.context.ExecutionContext, client: mokr.connection.DevtoolsConnection, remote_object: dict, page: mokr.browser.page.Page, frame_manager: mokr.frame.FrameManager) Bases: :py:obj:`mokr.execution.context.JavascriptHandle` Representation of a DOM element. Creation of an `ElementHandle` blocks the remote DOM element from garbage collection unless it is disposed manually or the parent frame is navigated from. :param context: `mokr.execution.ExecutionContext` of the `mokr.frame.FrameManager` that spawned this. :type context: ExecutionContext :param client: Remote connection from parent. :type client: DevtoolsConnection :param remote_object: The raw response from the remote connection representing the object. :type remote_object: dict :param page: The `mokr.browser.Page` the element was located in. :type page: Page :param frame_manager: The parent `mokr.frame.FrameManager` that spawned this element. :type frame_manager: FrameManager .. py:method:: content_frame() -> mokr.frame.Frame | None :async: Return the content frame for this element or None if not within iframe. :returns: Target `mokr.frame.Frame` if within iframe. :rtype: Frame | None .. py:method:: content() -> str :async: .. py:method:: hover() -> None :async: Mouse hover over this element. :raises ElementHandleError: Raised if element is detached from DOM. .. py:method:: click(button: Literal['left', 'right', 'middle'] = 'left', click_count: int = 1, delay: int | float | None = 1000) -> None :async: Click the center of this element with the bound `ElementHandle._page.mouse`. If not in view, this will attempt to scroll the element into view. :param button: Mouse button to click with. Defaults to "left". :type button: Literal["left", "right", "middle"], optional :param click_count: Number of clicks to run. Defaults to 1. :type click_count: int, optional :param delay: Time in milliseconds to wait before each click. Defaults to 1000. :type delay: int | float | None, optional :raises ElementHandleError: Raised if element is detached from DOM. .. py:method:: upload_file(file_paths: list[str]) -> None :async: Set files at given `file_paths` as upload targets for this element. :param file_paths: List of file paths for upload. :type file_paths: list[str] .. py:method:: tap() -> None :async: Tap the center of this element with the bound `ElementHandle._page.touchscreen`. If not in view, this will attempt to scroll the element into view. :raises ElementHandleError: Raised if element is detached from DOM. .. py:method:: focus() -> None :async: Focus on this element. .. py:method:: type_text(text: str, delay: int | float = 0) -> None :async: Focus this element and type characters into it. Uses bound `ElementHandle._page.keyboard`. Note that modifier keys do not alter text case, meaning sending `mokr.input.Keyboard.press("shift")` and typing `ElementHandle.type_text("mokr")` will not type "MOKR" into the it. :param text: Text to type. :type text: str :param delay: Time in milliseconds to wait between each character typed. Defaults to 0. :type delay: int | float, optional .. py:method:: press(key: str, delay: int | float | None = None) -> None :async: Focus this element and press the given `key` by sending `mokr.input.Keyboard.down` and `mokr.input.Keyboard.up` events, with the given `delay` in between. Modifier keys effect this method, meaning sending `mokr.input.Keyboard.press("shift")` and then `mokr.input.Keyboard.press("m")` will type an uppercase "M". :param key: Name of key. See `mokr.input.Keyboard.key_definitions`. :type key: str :param delay: Time in milliseconds to "hold" the key down. Defaults to None. :type delay: int | float | None, optional .. py:method:: bounding_box() -> dict[str, float] | None :async: Return the bounding box for this element, if visible. Othwerise, return None. :returns: Dictionary keyed with "x", "y", "width", and "height", if visible. Othwerwise, None. :rtype: dict[str, float] | None .. py:method:: box_model() -> dict | None :async: Return the box model for this element, if visible. Otherwise, None. :returns: If not visible, None. Othwerwise, Dictionary keyed with "content", "padding", "border", "margin", "width", and "height". Each key value will be a dictionary containing "x" and "y". :rtype: dict | None .. py:method:: screenshot(file_type: Literal['png', 'jpeg'] | None = None, file_path: str | None = None, jpeg_quality: int | None = None, omit_background: bool = False, encoding: Literal['binary', 'base64'] = 'binary', scale: int | float = 1) -> bytes :async: Take a screenshot of the element. Will scroll element inyo the viewport, if needed. :param file_type: File type to save the image as. Defaults to "png" if None. :type file_type: Literal["png", "jpeg"] | None, optional :param file_path: Path to save image to. If given without `file_type`, the type will be inferred. Defaults to None. :type file_path: str | None, optional :param jpeg_quality: JPEG quality, 0-100 (only applicable if type is or is inferred to be JPEG. Defaults to 100 if None. :type jpeg_quality: int | None, optional :param omit_background: Make the background transparent if True. Not supported on Firefox. Defaults to False. :type omit_background: bool, optional :param encoding: Encoding type to return the image data as. Defaults to "binary". :type encoding: Literal["binary", "base64"], optional :param scale: Image scale, 0-1. Defaults to 1. :type scale: int | float, optional :raises ValueError: Raised if `file_type` isn't given and can't be inferred as a supported type from `file_path`, if given. :raises ElementHandleError: Raised if element is not visible (has no `mokr.execution.ElementHandle.bounding_box`). :returns: The image content. :rtype: bytes .. py:method:: query_selector(selector: str) -> ElementHandle | None :async: Return the first child element in this element that matches the selector, if any. :param selector: Element selector to locate. :type selector: str :returns: ElementHandle if found or None. :rtype: ElementHandle | None .. py:method:: query_selector_all(selector: str) -> list[ElementHandle] :async: Return all child elements in this element that match the selector, if any. :param selector: Element selector to locate. :type selector: str :returns: List of ElementHandle if any or empty list. :rtype: list[ElementHandle] .. py:method:: xpath(expression: str) -> list[ElementHandle] :async: Return all child elements in this element that match the expression, if any. :param expression: XPath expression to evaluate. :type expression: str :returns: List of ElementHandle if any or empty list. :rtype: list[ElementHandle] .. py:method:: is_in_viewport() -> bool :async: Evaluate if the element is withing the viewport. :returns: True if in viewport, else False. :rtype: bool .. py:class:: JavascriptHandle(context: mokr.execution.context.ExecutionContext, client: mokr.connection.DevtoolsConnection, remote_object: dict) Representative of a JavaScript object within the frame. JavascriptHandles are created automatically by `mokr.frame.FrameManager` and `mokr.browser.WebWorker`. :param context: `mokr.execution.ExecutionContext` of the `mokr.frame.FrameManager` that spawned this. :type context: ExecutionContext :param client: Remote connection from parent. :type client: DevtoolsConnection :param remote_object: The raw response from the remote connection representing the object. :type remote_object: dict .. py:property:: execution_context :type: mokr.execution.context.ExecutionContext Get `mokr.execution.ExecutionContext` of this handle. .. py:method:: get_property(property_name: str) -> JavascriptHandle :async: Get a property of the remote object related to this handle. :param property_name: Name of the target property. :type property_name: str :returns: Newly created `JavascriptHandle` from the result. :rtype: JavascriptHandle .. py:method:: get_properties() -> dict[str, JavascriptHandle] :async: Get all properties of the remote object related to this handle. :returns: Dictionary keyed as "property name" to newly created `JavascriptHandle`s from the results. :rtype: dict[str, JavascriptHandle] .. py:method:: json() -> dict :async: Get and JSONify the values of the remote object this handle represents. :returns: Dictionary of JSONified values. :rtype: dict .. py:method:: dispose() -> None :async: Stop referencing this handle. Allows it to be garbage-collected by the browser. .. py:method:: to_string() -> str Get a string representation of the remote object this represents. :returns: String representation of remote object. May contain object data or just the type. :rtype: str