mahler.controller
=================

.. py:module:: mahler.controller


Attributes
----------

.. autoapisummary::

   mahler.controller.ENGINE_TO_WINDOW_CLS


Classes
-------

.. autoapisummary::

   mahler.controller.Controller


Module Contents
---------------

.. py:data:: ENGINE_TO_WINDOW_CLS

.. py:class:: Controller(engine: Literal['playwright', 'selenium'], model: Literal['chrome', 'firefox'], headless: bool = True, enable_javascript: bool = True, fingerprint: mahler.fingerprint.Fingerprint | None = None, user_agent: str | None = None)

   Controller class to interact with a browser window.

   :param engine: Automation suite
                  to use.
   :type engine: Literal["playwright", "selenium"]
   :param model: Browser type.
   :type model: Literal["chrome", "firefox"]
   :param headless: Run in headless mode. Defaults to True.
   :type headless: bool, optional
   :param enable_javascript: Enable JavaScript in browser.
                             Defaults to True.
   :type enable_javascript: bool, optional
   :param fingerprint: Browser fingerprint
                       to apply, if any. Defaults to None.
   :type fingerprint: Fingerprint | None, optional
   :param user_agent: User agent to apply to browser,
                      if any. Defaults to None.
   :type user_agent: str | None, optional

   :raises ValueError: Raised if an invalid engine is given.


   .. py:property:: engine
      :type: str


      Automation suite being used.


   .. py:property:: model
      :type: str


      Browser type.


   .. py:property:: window
      :type: mahler.protocols.Window


      Current window object for the controller.


   .. py:method:: goto(url: str, timeout: float | None = None) -> None

      Navigate to a URL.

      :param url: URL to visit.
      :type url: str
      :param timeout: Time in seconds to let load.
                      Defaults to None.
      :type timeout: float | None, optional



   .. py:method:: query_selector_all(selector: str) -> list[mahler.protocols.Element] | None

      Select all elements on the page that match the given selector.

      :param selector: A CSS or XPATH selector string.
      :type selector: str

      :returns:

                A list of elements found, if any.
                    Otherwise, None.
      :rtype: list[Element] | None



   .. py:method:: query_selector(selector: str) -> mahler.protocols.Element | None

      Select the first element on the page that matches the given selector.

      :param selector: A CSS or XPATH selector string.
      :type selector: str

      :returns: Found element, if any. Otherwise, None.
      :rtype: list[Element] | None