mokr ==== .. py:module:: mokr Submodules ---------- .. toctree:: :maxdepth: 1 /autoapi/mokr/browser/index /autoapi/mokr/connection/index /autoapi/mokr/console/index /autoapi/mokr/constants/index /autoapi/mokr/download/index /autoapi/mokr/exceptions/index /autoapi/mokr/execution/index /autoapi/mokr/frame/index /autoapi/mokr/input/index /autoapi/mokr/launch/index /autoapi/mokr/network/index /autoapi/mokr/utils/index /autoapi/mokr/waiters/index Attributes ---------- .. autoapisummary:: mokr.BROWSER_CLOSE mokr.MOKR_VERSION mokr.TARGET_GET_CONTEXTS mokr.version mokr.version_info Classes ------- .. autoapisummary:: mokr.Browser mokr.Connection mokr.ChromeLauncher mokr.FirefoxLauncher Functions --------- .. autoapisummary:: mokr.get_ws_endpoint mokr.launch mokr.connect Package Contents ---------------- .. py:class:: Browser(browser_type: Literal['chrome', 'firefox'], connection: mokr.connection.Connection, context_ids: list[str], ignore_https_errors: bool, default_viewport: dict | None, process: subprocess.Popen | None = None, close_callback: Callable | None = None, proxy_credentials: dict | None = None, default_user_agent: str | None = None, **kwargs: Any) Bases: :py:obj:`pyee.EventEmitter` This class is created upon connect to a browser. It is essentially a container for the individual pages and browser contexts. :param browser_type: The type of browser. :type browser_type: Literal["chrome", "firefox"] :param connection: Websocket connection. :type connection: `mokr.network.Connection` :param context_ids: Browser context identifiers. :type context_ids: list[str] :param ignore_https_errors: Ignore site security errors. :type ignore_https_errors: bool :param default_viewport: Default viewport configuration. :type default_viewport: dict | None :param process: Local browser process, if any. Defaults to None. :type process: Popen | None, optional :param close_callback: Callback to run on close. Defaults to None. :type close_callback: Callable | None, optional :param proxy_credentials: (dict | None, optional): Dictionary with proxy credentials keyed as "username" and "password". Credentials should be for the proxy the browser process is bound to. :param default_user_agent: Default user agent to use on all new pages. :type default_user_agent: str, optional .. py:property:: kind :type: str One of "chrome" or "firefox". .. py:property:: process :type: subprocess.Popen | None The local browser process. If created via `mokr.connect`, will return None. .. py:property:: version :type: str Get browser version (product from browser full version info.) .. py:property:: user_agent :type: str Get the user agent the browser was spawned with or that is set as the default to override with. This can be overidden later again with `mokr.browser.Page.set_user_agent`. .. py:property:: browser_contexts :type: list[mokr.browser.context.BrowserContext] A list of all `mokr.browser.BrowserContext` instances attached to this browser. By default, this will be a single context. .. py:property:: ws_endpoint :type: str The websocket URL that this `Browser`'s `mokr.connection.Connection` object is using. .. py:method:: first_page() -> mokr.browser.page.Page | None :async: Return the first page in the default context's `BrowserContext.pages`. If no pages active, returns None. :returns: First active page in the default context, if any. :rtype: Page | None .. py:method:: ready() -> Browser :async: Enable target discovery in the remote connection. :returns: This `Browser` class. :rtype: Browser .. py:method:: create_incognito_browser_context() -> mokr.browser.context.BrowserContext :async: Create a new browser context. This is akin to spawning an incognito browser window, it will not share cookies or storage with pages in other contexts. To do so, use `Browser.new_page` instead. Example:: browser = await launch().launch() # Navigate and login or perform another storage-accessed action. context = await browser.create_incognito_browser_context() page = await context.first_page() # Navigate to the same site. Session isn't shared! ... :returns: A new `mokr.browser.BrowserContext`. :rtype: BrowserContext .. py:method:: new_page() -> mokr.browser.page.Page :async: Spawn a new page within the default context. :returns: A new `mokr.browser.Page` at "about:blank". :rtype: Page .. py:method:: targets() -> list[mokr.browser.target.Target] A list of all `mokr.browser.Target`s in all contexts attached to this `Browser` object. :returns: All initialised targets within all contexts in this browser. :rtype: list[Target] .. py:method:: pages() -> list[mokr.browser.page.Page] :async: A list of all `mokr.browser.Page`s in all contexts attached to this `Browser` object. :returns: All pages within all contexts in this browser. :rtype: list[Page] .. py:method:: close() -> None :async: Run the `close_callback` given during initialisation. .. py:method:: disconnect() -> None :async: Disconnect the `Browser`'s `Connection` object's websocket connection and fail any `Browser.targets` that haven't finished initialising. .. py:class:: Connection(url: str, loop: asyncio.AbstractEventLoop, delay: int = 0) Bases: :py:obj:`pyee.EventEmitter`, :py:obj:`mokr.connection.base.RemoteConnection` Create remote connection. :param url: Websocket URL for remote connection. :type url: str :param loop: Running asyncio loop. :type loop: asyncio.AbstractEventLoop :param delay: Time in milliseconds to wait before handling messages. Defaults to 0. :type delay: int, optional .. py:attribute:: connection :type: mokr.connection.devtools.DevtoolsConnection :value: None .. py:property:: url :type: str Get remote websocket URL. .. py:method:: send(method: str, params: dict = None) -> Awaitable[dict] Send message to remote connection via websocket. :param method: Method to run. :type method: str :param params: Arguments for method, if any. Defaults to None. :type params: dict, optional :raises ConnectionError: Raised if the connection is closed. :returns: Remote response as dictionary. :rtype: Awaitable[dict] .. py:method:: dispose() -> None :async: Sever all connections. .. py:method:: create_session(target_info: dict) -> mokr.connection.devtools.DevtoolsConnection :async: Create a new `mokr.connection.DevtoolsConnection`. :param target_info: Target info from triggered event. :type target_info: dict :returns: New `DevtoolsConnection`. :rtype: DevtoolsConnection .. py:data:: BROWSER_CLOSE :value: 'Browser.close' .. py:data:: MOKR_VERSION :value: '0.2.0' .. py:data:: TARGET_GET_CONTEXTS :value: 'Target.getBrowserContexts' .. py:class:: ChromeLauncher(binary_path: str = None, headless: bool = None, user_data_dir: str = None, devtools: bool = False, ignore_default_args: bool | list[str] = False, ignore_https_errors: bool = False, default_viewport: dict[str, int] = None, proxy: str = None, default_user_agent: str = None, slow_mo: int = 0, log_level: str | int = None, args: list[str] = None, dumpio: bool = False, env: dict[str, str] = None, loop: asyncio.AbstractEventLoop = None, firefox_user_prefs: dict = None, firefox_addons_paths: list[str] = None) Bases: :py:obj:`mokr.launch.base.Launcher` Class to handle launching browser process and creation of a `mokr.browser.Browser` object. :param binary_path: Path to executable to use. Defaults to None (looks for default executable that can be installed via `mokr install`). :type binary_path: str, optional :param headless: Run the browser in headless (no window) mode. Defaults to None (uses opposite value to `devtools`). :type headless: bool, optional :param user_data_dir: Path to a user data directory. Defaults to None. :type user_data_dir: str, optional :param devtools: Automatically open the developer tools panel. Defaults to False. :type devtools: bool, optional :param ignore_default_args: Either a bool to indicate ignoring all arguments or a list of arguments to ignore. Be cautious, ignoring some arguments may cause unexpected results. Defaults to False. :type ignore_default_args: bool | list[str], optional :param ignore_https_errors: Ignore site security errors. Defaults to False. :type ignore_https_errors: bool, optional :param default_viewport: Set the default viewport for new pages. Accepts a dictionary keyed with viewport options. Not all viewport options are considered, only: "isMobile", "width", "height", "deviceScaleFactor", "isLandscape", and "hasTouch". Defaults to None (800x600 viewport). :type default_viewport: dict[str, int], optional :param proxy: Proxy to route all requests through. Can be a regular HTTP/S proxy or SOCKS proxy. Expects proxy as `://[(optional):]@`. :type proxy: str, optional :param default_user_agent: Default user agent to use on all new pages. :type default_user_agent: str, optional :param slow_mo: Slow execution of remote calls by the given time in milliseconds. Defaults to 0. :type slow_mo: int, optional :param log_level: Log level to log at. Defaults to None (same as root). :type log_level: str | int, optional :param args: Additional arguments to pass to the browser process when launching. Defaults to None. :type args: list[str], optional :param dumpio: Pipe the browser process' stdout and stderr into ``process.stdout`` and ``process.stderr``. Defaults to False. :type dumpio: bool, optional :param env: Additional environment variables that the browser process will be able to read. Defaults to None. :type env: dict[str, str], optional :param loop: A running asyncio loop to execute within. Defaults to None (uses `asyncio.get_event_loop`). :type loop: asyncio.AbstractEventLoop, optional :param firefox_user_prefs: Firefox only. User preferences to load. :type firefox_user_prefs: dict :param firefox_addons_paths: Firefox only. A list of paths to addons that will be installed as temporary extensions. :type firefox_addons_paths: list[str] Example:: ```python from mokr.launch import ChromeLauncher, FirefoxLauncher async with ChromeLauncher() as browser: page = await browser.first_page() await page.goto("https://example.com") # Or, to avoid the contextmanager. launcher = FirefoxLauncher() browser = await launcher.launch() page = await browser.first_page() await page.goto("https://example.com") await launcher.stop() ``` .. py:attribute:: kind :value: 'chrome' .. py:class:: FirefoxLauncher(*args, **kwargs) Bases: :py:obj:`mokr.launch.base.Launcher` Class to handle launching browser process and creation of a `mokr.browser.Browser` object. :param binary_path: Path to executable to use. Defaults to None (looks for default executable that can be installed via `mokr install`). :type binary_path: str, optional :param headless: Run the browser in headless (no window) mode. Defaults to None (uses opposite value to `devtools`). :type headless: bool, optional :param user_data_dir: Path to a user data directory. Defaults to None. :type user_data_dir: str, optional :param devtools: Automatically open the developer tools panel. Defaults to False. :type devtools: bool, optional :param ignore_default_args: Either a bool to indicate ignoring all arguments or a list of arguments to ignore. Be cautious, ignoring some arguments may cause unexpected results. Defaults to False. :type ignore_default_args: bool | list[str], optional :param ignore_https_errors: Ignore site security errors. Defaults to False. :type ignore_https_errors: bool, optional :param default_viewport: Set the default viewport for new pages. Accepts a dictionary keyed with viewport options. Not all viewport options are considered, only: "isMobile", "width", "height", "deviceScaleFactor", "isLandscape", and "hasTouch". Defaults to None (800x600 viewport). :type default_viewport: dict[str, int], optional :param proxy: Proxy to route all requests through. Can be a regular HTTP/S proxy or SOCKS proxy. Expects proxy as `://[(optional):]@`. :type proxy: str, optional :param default_user_agent: Default user agent to use on all new pages. :type default_user_agent: str, optional :param slow_mo: Slow execution of remote calls by the given time in milliseconds. Defaults to 0. :type slow_mo: int, optional :param log_level: Log level to log at. Defaults to None (same as root). :type log_level: str | int, optional :param args: Additional arguments to pass to the browser process when launching. Defaults to None. :type args: list[str], optional :param dumpio: Pipe the browser process' stdout and stderr into ``process.stdout`` and ``process.stderr``. Defaults to False. :type dumpio: bool, optional :param env: Additional environment variables that the browser process will be able to read. Defaults to None. :type env: dict[str, str], optional :param loop: A running asyncio loop to execute within. Defaults to None (uses `asyncio.get_event_loop`). :type loop: asyncio.AbstractEventLoop, optional :param firefox_user_prefs: Firefox only. User preferences to load. :type firefox_user_prefs: dict :param firefox_addons_paths: Firefox only. A list of paths to addons that will be installed as temporary extensions. :type firefox_addons_paths: list[str] Example:: ```python from mokr.launch import ChromeLauncher, FirefoxLauncher async with ChromeLauncher() as browser: page = await browser.first_page() await page.goto("https://example.com") # Or, to avoid the contextmanager. launcher = FirefoxLauncher() browser = await launcher.launch() page = await browser.first_page() await page.goto("https://example.com") await launcher.stop() ``` .. py:attribute:: kind :value: 'firefox' .. py:method:: launch() -> mokr.browser.browser.Browser :async: Start browser process and return a `mokr.browser.Browser` object. .. py:function:: get_ws_endpoint(url) -> str Get the websocket URL for the remote browser at `url`. :param url: Remote browser URL. :type url: _type_ :raises BrowserError: Raised if browser closes while trying to resolve. :returns: Websocket URL from `/json/version` response. :rtype: str .. py:data:: version :value: '0.2.0' .. py:data:: version_info .. py:function:: launch(browser_type: Literal['chrome', 'firefox'] = 'chrome', binary_path: str = None, headless: bool = None, user_data_dir: str = None, devtools: bool = False, ignore_default_args: bool | list[str] = False, ignore_https_errors: bool = False, default_viewport: dict[str, int] = None, proxy: str = None, default_user_agent: str = None, slow_mo: int = 0, log_level: str | int = None, args: list[str] = None, dumpio: bool = False, env: dict[str, str] = None, loop: asyncio.AbstractEventLoop = None, firefox_user_prefs: dict = None, firefox_addons_paths: list[str] = None) -> browser.Browser Launch a browser process and create a `mokr.browser.Browser`. Wrapper for `mokr.launch.Launcher.launch`. :param browser_type: The type of browser to, use. One of "chrome" or "firefox". Note that Firefox is not fully implemented and only offers partial functionality. :type browser_type: Literal["chrome", "firefox"] :param binary_path: Path to executable to use. Defaults to None (looks for default executable that can be installed via `mokr install`). :type binary_path: str, optional :param headless: Run the browser in headless (no window) mode. Defaults to None (uses opposite value to `devtools`). :type headless: bool, optional :param user_data_dir: Path to a user data directory. Defaults to None. :type user_data_dir: str, optional :param devtools: Automatically open the developer tools panel. Defaults to False. :type devtools: bool, optional :param ignore_default_args: Either a bool to indicate ignoring all arguments or a list of arguments to ignore. Be cautious, ignoring some arguments may cause unexpected results. Defaults to False. :type ignore_default_args: bool | list[str], optional :param ignore_https_errors: Ignore site security errors. Defaults to False. :type ignore_https_errors: bool, optional :param default_viewport: Set the default viewport for new pages. Accepts a dictionary keyed with viewport options. Not all viewport options are considered, only: "isMobile", "width", "height", "deviceScaleFactor", "isLandscape", and "hasTouch". Defaults to None (800x600 viewport). :type default_viewport: dict[str, int], optional :param proxy: Proxy to route all requests through. Can be a regular HTTP/S proxy or SOCKS proxy. Expects proxy as `://[(optional):]@`. :type proxy: str, optional :param default_user_agent: Default user agent to use on all new pages. :type default_user_agent: str, optional :param slow_mo: Slow execution of remote calls by the given time in milliseconds. Defaults to 0. :type slow_mo: int, optional :param log_level: Log level to log at. Defaults to None (same as root). :type log_level: str | int, optional :param args: Additional arguments to pass to the browser process when launching. Defaults to None. :type args: list[str], optional :param dumpio: Pipe the browser process' stdout and stderr into ``process.stdout`` and ``process.stderr``. Defaults to False. :type dumpio: bool, optional :param env: Additional environment variables that the browser process will be able to read. Defaults to None. :type env: dict[str, str], optional :param loop: A running asyncio loop to execute within. Defaults to None (uses `asyncio.get_event_loop`). :type loop: asyncio.AbstractEventLoop, optional :param firefox_user_prefs: Firefox only. User preferences to load. :type firefox_user_prefs: dict :param firefox_addons_paths: Firefox only. A list of paths to addons that will be installed as temporary extensions. :type firefox_addons_paths: list[str] Example:: ```python from mokr import launch async with launch() as browser: page = await browser.first_page() await page.goto("https://example.com") # Or, to avoid the contextmanager. launcher = launch() browser = await launcher.launch() page = await browser.first_page() await page.goto("https://example.com") await launcher.stop() ``` :raises ValueError: Raised if `browser_type` isn't of "chrome" or "firefox". :returns: A newly created `mokr.browser.Browser` instance. :rtype: Browser .. py:function:: connect(browser_type: Literal['chrome', 'firefox'] = 'chrome', browser_ws_endpoint: str = None, browser_url: str = None, ignore_https_errors: bool = False, default_viewport: dict[str, int] = None, slow_mo: int = 0, log_level: str | int = None, loop: asyncio.AbstractEventLoop = None) -> browser.Browser :async: Connect to an existing running browser. :param browser_type: The type of browser to connect to. One of "chrome" or "firefox". Note that Firefox is not fully implemented and only offers partial functionality. :type browser_type: Literal["chrome", "firefox"] :param browser_ws_endpoint: An existing browser websocket endpoint to connect to. Should be formated like `"ws://${host}:${port}/devtools/browser/"`. Defaults to None, if not given, must give `browser_url`. :type browser_ws_endpoint: str, optional :param browser_url: An existing browser URL to connect to and get the websocket URL from. Should follow format of "http://${host}:${port}". Defaults to None, if not given, must give `browser_ws_endpoint`. :type browser_url: str, optional :param ignore_https_errors: Ignore site security errors. Defaults to False. :type ignore_https_errors: bool, optional :param default_viewport: Set the default viewport for new pages. Accepts a dictionary keyed with viewport options. Not all viewport options are considered, only: "isMobile", "width", "height", "deviceScaleFactor", "isLandscape", and "hasTouch". Defaults to None (800x600 viewport). :type default_viewport: dict[str, int], optional :param slow_mo: Slow execution of remote calls by the given time in milliseconds. Defaults to 0. :type slow_mo: int, optional :param log_level: Log level to log at. Defaults to None (same as root). :type log_level: str | int, optional :param loop: A running asyncio loop to execute within. Defaults to None (uses `asyncio.get_event_loop`). :type loop: asyncio.AbstractEventLoop, optional :raises ValueError: Raised if `browser_type` isn't of "chrome" or "firefox" or neither `browser_ws_endpoint` nor `browser_url` are given. :returns: A newly created `mokr.browser.Browser` instance. :rtype: Browser