mahler
======

.. py:module:: mahler


Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/mahler/controller/index
   /autoapi/mahler/engines/index
   /autoapi/mahler/fingerprint/index
   /autoapi/mahler/protocols/index


Classes
-------

.. autoapisummary::

   mahler.Controller
   mahler.Element
   mahler.Window
   mahler.Fingerprint


Package Contents
----------------

.. 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



.. py:class:: Element(native_element: Any, parent: Element | None = None)

   Bases: :py:obj:`Protocol`


   Remote browser object API.

   :param native_element: The native element API for the underlying
                          automation suite.
   :type native_element: Any
   :param parent: The parent. Defaults to None.
   :type parent: Element | None, optional


   .. py:property:: parent
      :type: Element | None


      The parent element this was selected from, if any.


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

      Select all child elements of this node 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) -> Element | None

      Select the first child element of this node 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



   .. py:method:: click() -> None

      Click on this element.



   .. py:method:: content() -> str

      Return the text content of this element.



   .. py:method:: type_on(text: str, delay: float = 0) -> None

      Emulate typing on this element.

      :param text: Text to type.
      :type text: str
      :param delay: Time in seconds to wait between keys.
                    Defaults to 0.
      :type delay: float, optional



.. py:class:: Window(model: Literal['chrome', 'firefox'], headless: bool = True, enable_javascript: bool = True, fingerprint: mahler.fingerprint.Fingerprint | None = None)

   Bases: :py:obj:`Protocol`


   Remote browser interactive API.

   :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


   .. 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.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.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



.. py:class:: Fingerprint

   Fingerprint class to hold browser signature.


   .. py:attribute:: headers
      :type:  dict | None


   .. py:attribute:: user_agent
      :type:  str | None