selenium-query 0.1.0__py3-none-any.whl

selenium_query/__init__.py

@@ -0,0 +1,10 @@
+
+from ._types_and_tools import center_of
+from .getter import Getter
+from ._any_all_getters import BoolAnyGetter, BoolAllGetter
+from ._values_getter import ValuesGetter
+from ._asserter_getter import AsserterGetter
+from ._filter_getter import FilterGetter
+from ._order_getter import OrderGetter
+from ._mapper_getter import MapperGetter
+from ._negation_transmitter import NotTransmitter

selenium_query/_any_all_getters.py

@@ -0,0 +1,17 @@
+
+from typing import Callable, ClassVar
+
+from .getter import Getter
+
+
+
+# Explicite redeclaration, to register properly the accessor:
+class BoolAllGetter(Getter, accessor="all"):
+    pass
+
+
+
+class BoolAnyGetter(BoolAllGetter, accessor="any"):
+
+    COMBINER: ClassVar[Callable] = any
+

selenium_query/_asserter_getter.py

@@ -0,0 +1,90 @@
+from textwrap import dedent
+from typing import Any, Callable
+
+from selenium.webdriver.remote.webelement import WebElement
+
+from ._basics.generic_value_getter import should_be
+from .getter import Getter
+
+
+
+
+
+
+class AsserterGetter(Getter, accessor="check"):
+    """
+    Asserter version of the Getter (css, data, props, id, has_class, ...), raising
+    AssertionError if ever something doesn't match.
+    * Assertions are chainable.
+    * An extra assertion message (head of default message) can be set using `getter.check(msg)`.
+
+    The expected values can be given as a unique value all the elements must match, or as a list.
+    In the latter,
+
+    Accessible through `Getter.check`.
+    """
+
+    _msg:str = None
+
+    def __call__(self, msg:str):
+        self._msg = dedent(msg).rstrip().lstrip('\n')
+        return self
+
+    def _with_msg(self, msg:str):
+        if not self._msg:
+            return msg
+        return f"\n\n{ self._msg or '' }\n\n{ msg }"
+
+    def _check_elements(
+        self,
+        ref_items,
+        value_getter: Callable[[WebElement,str],Any],
+        *,
+        is_ok:        Callable[[Any,Any],bool] = None,
+        feedback:     Callable[[Any,Any],bool] = None,
+    ) -> 'AsserterGetter' :
+
+        is_ok = self._default_is_ok(is_ok)
+        feedback = feedback or should_be
+
+        bads = [] if self.elements else ('no such element',)
+        bads.extend(
+            f"Wrong number of expected values for {prop!r}: {len(exp)} should be {len(self.elements)}"
+            for prop, exp in ref_items
+            if isinstance(exp, (list,tuple)) and len(self.elements) != len(exp)
+        )
+        for i_elt,element in enumerate(self.elements):
+            bads.extend(
+                f"{prop}: { feedback(expected, actual, self._negate) }"
+                    for prop, exp in ref_items
+                    if not is_ok(
+                        (expected := exp[i_elt] if isinstance(exp, (tuple, list)) else exp),
+                        (actual   := value_getter(element, prop))
+                    )
+            )
+
+        if bads:
+            data = ',\n  '.join(bads)
+            msg = self._with_msg(f"  { data }\n\nOn: { self }")
+            assert False, msg
+
+        self._msg = None
+        return self
+
+
+    def exists(self, exp=True):
+        """ Usable for non existing list of elements """
+        actual = super().exists()   # Already handle the negation!
+        msg = self._with_msg(f"  {actual} should { ' not'*self._negate }be {exp}\n\nOn: {self}")
+        assert actual == exp, msg
+        return self
+
+
+    def count(self, n:int):
+        """ Usable for non existing list of elements """
+        actual = super().count()    # Already handle the negation!
+        msg = self._with_msg(
+            f"  {actual} should { ' not'*self._negate }be {n}\n\nWrong number of children on: {self}"
+        )
+        assert actual == n, msg
+        return self

selenium_query/_basics/action_getter.py

@@ -0,0 +1,362 @@
+
+from contextlib import contextmanager, nullcontext
+from typing import Any, ClassVar, List, Optional, Union, TYPE_CHECKING
+
+from selenium.webdriver import Keys
+from selenium.webdriver.common.action_chains import ActionChains
+
+from .._types_and_tools import GetterOrCss, WaitingContext
+from .base_getter import BaseGetter
+
+if TYPE_CHECKING:
+    from ..getter import Getter
+
+
+
+
+class ActionGetter(BaseGetter):
+    """
+    Relay class, applying automatically the action which are normally `on_element` (or equivalent)
+    to all the self.elements. The chain of actions must then be triggered by accessing the `go`
+    property (triggers Action.perform() on all elements).
+
+    Methods which take another target as argument may take a css selector string instead
+    of a WebElement: the original method will be called with the equivalent element.
+    Note that the cardinality of the elements in the current object and those in the
+    targeted ones must be identical.
+
+    (see: https://github.com/SeleniumHQ/selenium/blob/trunk/py/selenium/webdriver/common/action_chains.py)
+    """
+
+    _context_action: ClassVar[Optional[ActionChains]] = None
+    """
+    Global ActionChains instance used when the `ActionGetter.context_chain_and_go` context
+    manager is used.
+    """
+
+
+    DURATION: ClassVar[int] = 40
+    """
+    Base duration (in milliseconds value for selenium actions (mouse move, in between clicks, ...)
+    Warning about consecutive clicks/actions: short values might end up in different behaviors.
+    Selenium default is 250 ms.
+    """
+
+
+    @staticmethod
+    @contextmanager
+    def swap_duration(duration:int):
+        """
+        Temporarily change the default duration for all actions. Restore it at the end of the tests.
+        """
+        old = ActionGetter.DURATION
+        ActionGetter.DURATION = duration
+        try:
+            yield
+        finally:
+            ActionGetter.DURATION = old
+
+
+    @contextmanager
+    def context_chain_and_go(self, duration:int=None):
+        """
+        With this context manager, the very same ActionChain object is used for every single
+        element/Getter object. When resuming executions, the ActionChain is automatically
+        triggered.
+
+        WARNING:
+        - `scroll_to` is not usable this way: scroll to an element must be done before, and all
+        subsequent moves should be done through other methods.
+        - there are no specific checks about other actions performed when several elements exist
+        on the same Getter object, so everything will be applied in order, even if it actually
+        does not make sense at `perform` time.
+        """
+        ActionGetter._context_action = ActionChains(
+            self.driver,
+            duration=self.DURATION if duration is None else duration
+        )
+        try:
+            yield None
+            ActionGetter._context_action.perform()
+        finally:
+            ActionGetter._context_action = None
+
+
+    def __getitem__(self, idx:int):
+        """
+        Returns a new instance of the current class, with only the element at index @idx.
+        If the current instance has actions, the corresponding action object is shared with the
+        returned object.
+        """
+        sub_getter = super().__getitem__(idx)
+        if self._actions:
+            sub_getter._actions = [self._actions[idx]]
+        return sub_getter
+
+    @property
+    def go(self):
+        """ Alias for `perform()`. """
+        return self.perform()
+
+    def perform(self) -> 'Getter':
+        """
+        Apply all the registered actions, then return a fresh Getter holding the very same
+        elements, but with a find method usable and no actions registered.
+        """
+        for action in self._actions:
+            action.perform()
+        return self
+
+
+    #------------------------------------------------------------------
+
+    def _this_or_that(self, other:Optional[GetterOrCss], current:bool=False):
+        """
+        By default apply the actions on the elements of the current instance.
+        If `@other` is provided, use the corresponding elements instead.
+        If @current=True, this means the current mouse position will be used to perform the
+        action, instead of moving to any element before.
+        """
+        if current and other is not None:
+            raise ValueError(
+                f"Cannot use the `current` mouse location when another element is targeted ({other=!r})."
+            )
+        return (
+            (None,) * len(self.elements) if current else
+            self.elements if not other else
+            self._getter_or_css(other).elements
+        )
+
+    def _getter_or_css(self, thing:Optional[GetterOrCss]) -> 'Getter' :
+        return thing and (self.find(thing, in_page=True) if isinstance(thing, str) else thing)
+
+    def _duplicate_value(self, value:Any):
+        return (value,) * len(self.elements)
+
+    def _apply(self, name:str, *args_values:List[Any]):
+        """
+        @args_values: list of all values to use for each element.
+        The lists are provided in the order matching the original method arguments.
+        Inside the lists, the values must match the self.elements order.
+
+        @returns a new ActionGetter instance, holding the new actions.
+        THIS INSTANCE MUST BE KEPT/STORED/USED to actually trigger all the registered actions.
+        """
+        if not self.elements:
+            raise ValueError(
+                f"Cannot initiate actions on a Getter without known elements.\n{ self }"
+            )
+
+        sizes = [*map(len,args_values)]
+        if len(set(sizes)) != 1:
+            raise ValueError(f"Mismatched arguments data lengths for {name}: {sizes}.\n{ self }")
+
+        zipped_args = tuple(zip(*args_values))
+        if len(zipped_args) != len(self.elements):
+            raise ValueError(
+                f"Mismatched arguments lengths for {name}: {len(self.elements)} elements, but found "
+                f"{len(zipped_args)} sets of arguments.\n{ self }"
+            )
+
+        if ActionGetter._context_action is not None:
+            for args in zipped_args:
+                ActionGetter._context_action = getattr(ActionGetter._context_action, name)(*args)
+            return self # No need to return a new instance, since no instance states are mutated, here.
+
+        else:
+            actions = self._actions or [
+                ActionChains(self.driver, duration=self.DURATION) for _ in self.elements
+            ]
+            built_actions = [
+                getattr(action, name)(*args) for args,action in zip(zipped_args, actions)
+            ]
+            out = ActionGetter.from_(self)
+            out._actions = built_actions
+            return out
+
+
+    #-----------------------------------------------------------------------
+
+
+    def reset_actions(self):
+        return self._apply("reset_actions")
+
+    def click(self, other:Optional[GetterOrCss]=None, *, current=False):
+        return self._apply("click", self._this_or_that(other, current))
+
+    def click_and_hold(self, other:Optional[GetterOrCss]=None, *, current=False):
+        return self._apply("click_and_hold", self._this_or_that(other, current))
+
+    def context_click(self, other:Optional[GetterOrCss]=None, *, current=False):
+        return self._apply("context_click", self._this_or_that(other, current))
+
+    def double_click(self, other:Optional[GetterOrCss]=None, *, current=False):
+        return self._apply("double_click", self._this_or_that(other, current))
+
+    def drag_and_drop(
+        self,
+        target: GetterOrCss,
+        get_target: bool=False,
+        other_src: Optional[GetterOrCss]=None,
+        *,
+        current=False,
+    ):
+        """
+        If @get_target is True, returns the Getter of the targeted elements instead of the current
+        instance.
+        The actions are transferred to the target object (shared object => CAREFUL WITH THAT!!!!)
+        """
+        targets = self._getter_or_css(target)
+        self._apply("drag_and_drop", self._this_or_that(other_src, current), targets.elements)
+        if get_target:
+            targets._actions = self._actions
+            return targets
+        return self
+
+    def drag_and_drop_by_offset(self, xoffset: int, yoffset: int, other_src:Optional[GetterOrCss]=None):
+        return self._apply(
+            "drag_and_drop_by_offset",
+            self._this_or_that(other_src),
+            self._duplicate_value(xoffset),
+            self._duplicate_value(yoffset),
+        )
+
+    def key_down(self, value: str, other:Optional[GetterOrCss]=None, *, current=False):
+        return self._apply("key_down", self._duplicate_value(value), self._this_or_that(other, current))
+
+    def key_up(self, value: str, other:Optional[GetterOrCss]=None, *, current=False):
+        return self._apply("key_up", self._duplicate_value(value), self._this_or_that(other, current))
+
+    def move_by_offset(self, xoffset: int, yoffset: int, release=False):
+        out = self._apply(
+            "move_by_offset",
+            self._duplicate_value(xoffset), self._duplicate_value(yoffset)
+        )
+        if release:
+            self.release(current=True)
+        return out
+
+    def move_to_element(self, other:Optional[GetterOrCss]=None):
+        return self._apply("move_to_element", self._this_or_that(other))
+
+    move_to = move_to_element
+    """ Alias for move_to_element """
+
+    def move_to_element_with_offset(self, xoffset: int, yoffset: int, other:Optional[GetterOrCss]=None):
+        return self._apply(
+            "move_to_element_with_offset", self._this_or_that(other),
+            self._duplicate_value(xoffset), self._duplicate_value(yoffset)
+        )
+
+    def pause(self, seconds: Union[float, int, None]=None):
+        return self._apply("pause", self._duplicate_value(seconds or self.DURATION))
+
+    def release(self, other:Optional[GetterOrCss]=None, *, current=False):
+        return self._apply("release", self._this_or_that(other, current))
+
+    def send_keys_to_element(self, *keys_to_send: str, other:Optional[GetterOrCss]=None, current=False):
+        return self._apply(
+            "send_keys_to_element", self._this_or_that(other, current),
+            *map(self._duplicate_value, keys_to_send)
+        )
+
+    send_keys = send_keys_to_element
+    """
+    Alias for send_keys_to_element (because the Getter setup generalize the thing...)
+    """
+
+
+    # /!\ Selenium's base Scroll stuff just DOES NOT WORK!???
+    #
+    # def scroll_to_element(self, other:Optional[GetterOrCss]=None):
+    #     return self._apply("scroll_to_element", self._this_or_that(other))
+
+    # def scroll_by_amount(self, delta_x: int, delta_y: int):
+    #     return self._apply(
+    #         "scroll_by_amount",
+    #         self._duplicate_value(delta_x), self._duplicate_value(delta_y)
+    #     )
+
+    # def scroll_from_origin(self, scroll_origin: ScrollOrigin, delta_x: int, delta_y: int):
+    #     raise NotImplementedError("Getting lazy...")
+
+    def scroll_to(self, other:Optional[GetterOrCss]=None, *, shift:float=0, target_location:str='3/4'):
+        """
+        Scroll the current/given element into view. @shift may be used to tweak the final scroll
+        position, to avoid some targets to go out of the viewport.
+
+        @shift: Apply a vertical shift to the point considered as the point to center in the page.
+        @target_location: Ratio of innerHeight where to place the "center+shift" of the target.
+
+        WARNING: this action CANNOT be chained with others, because it is applied directly with JS.
+        """
+        elt = self if other is None else self._getter_or_css(other)
+        # Cannot scroll to different elements, considering how the actions are handled, so forbid it:
+        elt.check("Getters.scroll_to usage requires instances with exactly one element").count(1)
+
+        assert not self._actions and not ActionGetter._context_action, (
+            "scroll_to(...) cannot be chained with other actions, because it interacts directly with "
+            "the page, through the JS executor."
+        )
+
+        rect = elt.get.rect
+        center_y = rect['y'] + rect['height']/2 + shift
+
+        self.run_js(f"""
+            var centerY={ center_y }, H=innerHeight, Y=scrollY
+            var inBound = Y + H/6 <= centerY && centerY <= Y + H * 5/6
+            if(!inBound){{
+                scrollTo(0, centerY - H * { target_location } );
+            }}
+        """)
+        return elt
+
+
+    def send_shortcut(
+        self,
+        keys:str,
+        *,
+        waiting_context:WaitingContext=None,
+    ):
+        """
+        Takes a string representing a combination of keys "+" separated (spaces are ignored), like:
+            "Ctrl+S"
+            "Ctrl + Alt + Shift + Enter"
+            ...
+        The string is split, converted to the related selenium Keys and the combination is
+        automatically applied to the element.
+
+        @waiting_context: If given, must be a context manager function (ALREADY CALLED) to control
+        any delay/logic that should ba applied around the shortcut application.
+        """
+        *modifiers,key = map(to_keys, keys.replace(' ','').split("+"))
+        self.scroll_to()
+        with waiting_context or nullcontext():
+            with self.context_chain_and_go():
+                for mod in modifiers:
+                    self.key_down(mod)
+                self.send_keys(key)
+                for mod in modifiers:
+                    self.key_up(mod, current=True)
+                        # `current` because the shortcut could cause a move in the page.
+
+
+
+
+def to_keys(name:str) -> Keys:
+    """
+    Automatically convert a `Keys` name string to the corresponding value, or return the
+    original string.
+
+    * The input is case insensitive.
+    * 'CTRL' is automatically converted to 'CONTROL'
+    * 'PLUS' is automatically converted to 'Keys.ADD' (-> numpad +)
+    """
+    upper = name.upper()
+    if name.upper() == 'PLUS':
+        return Keys.ADD
+    if upper == 'CTRL':
+        upper = 'CONTROL'
+    return getattr(Keys, upper, name)
+
+

selenium_query/_basics/base_getter.py

@@ -0,0 +1,177 @@
+"""
+Kind of jQuery like usage, but for Selenium logistic/elements...
+"""
+
+from dataclasses import dataclass, field
+from functools import wraps
+from typing import Callable, ClassVar, List, TYPE_CHECKING, Tuple
+
+from selenium.webdriver.common.by import By
+from selenium.webdriver.remote.webdriver import WebDriver
+from selenium.webdriver.support.wait import WebDriverWait
+from selenium.webdriver.remote.webelement import WebElement
+from selenium.webdriver.common.action_chains import ActionChains
+
+if TYPE_CHECKING:
+    from ..getter import Getter
+
+
+
+def negate_output(method):
+    @wraps(method)
+    def wrapper(self:'Getter', *a, **kw):
+        out = method(self, *a, **kw)
+        return self.NEGATE_OUTCOME[self._negate](out)
+    return wrapper
+
+def forbid_negation(method):
+    @wraps(method)
+    def wrapper(self:'Getter', *a, **kw):
+        if self._negate:
+            raise ValueError(
+                "The `not_` modifier/property should not be used with the `get` one."
+            )
+        return method(self, *a, **kw)
+    return wrapper
+
+
+@dataclass
+class BaseGetter:
+
+    driver: WebDriver = None
+    waiter: WebDriverWait = None
+    elements: List[WebElement] = field(default_factory=list)
+
+    _css_selector: str = ""
+    _full_css: str = ""
+
+    _negate: bool = False
+
+    _actions: List[ActionChains] = field(default_factory=list)
+
+
+    NEGATE_OUTCOME: ClassVar[Tuple[Callable,Callable]] = (lambda _:_), (lambda v: not v)
+
+
+    def __repr__(self):
+        return f"{ self.__class__.__name__ }({self._full_css!r}, n_elements={ len(self.elements) })"
+
+
+    @negate_output
+    def exists(self):
+        return bool(self.elements)
+    # __bool__ = exists     # Dropped (mostly causing a mess: not possible to check instance definition against None)
+
+
+    @negate_output
+    def count(self):
+        return len(self.elements)
+    __len__ = count
+
+
+    def __iter__(self):
+        return ( self.__class__.from_(self, [elt]) for elt in self.elements )
+
+
+    def __getitem__(self, idx:int):
+        return self.__class__.from_(self, [self.elements[idx]])
+
+
+    def find(self, css_selector:str, *, in_page=False) -> 'Getter':
+        """
+        Find all children element matching the given css selector.
+        If @in_page is true, starts searching from the top of the page instead of starting
+        with the current element/Getter.
+        @key: ordering key function, if given.
+        """
+        if not in_page and not self.elements:
+            raise ValueError(
+                f"Inconsistent `find` request: the current selection is empty.\n{ self }"
+            )
+        if in_page:
+            elements = self.driver.find_elements(By.CSS_SELECTOR, css_selector)
+        else:
+            elements = []
+            for elt in self.elements:
+                children = elt.find_elements(By.CSS_SELECTOR, css_selector)
+                elements.extend(children)
+
+        full_css_path = f'{self._full_css} -> "{css_selector}"' if self._full_css else f'"{css_selector}"'
+
+        return self.__class__.from_(self, elements, css_selector, full_css_path)
+
+
+    def run_js(self, code:str, *args, async_=False, with_promise=True):
+        """
+        Use driver.execute_script on the given code.
+
+        * `@args` are arguments that will be passed in the JS environment (available through the
+        `arguments` array).
+        * `@async_=False`: if True, JS script will run async?. An error is raised if `with_promise`
+        is False and `done` is not present in the code (a call to it is needed to resume execution).
+        * `@with_promise=True`: if True and the script is supposed to be run async, `code` is
+        expected to be a Promise (aka, no await in the source!) and `'.then(done, console.error)'`
+        is automatically added at the end of `code` to consume the promise and resume executions.
+        In that case, the `done` call is not needed in the source code.
+        """
+        method = 'execute_script'
+        if async_:
+            method = 'execute_async_script'
+            if not with_promise and 'done' not in code:
+                raise ValueError("Invalid async script: a call to the `done` callback is needed")
+            code = f"""
+            var done = arguments[arguments.length - 1];
+            { code }{ '.then(done, console.error)' * with_promise }
+            """
+
+        return getattr(self.driver, method)(code, *args)
+
+
+    def wait_for_element(self, css_selector):
+        if self._actions:
+            raise ValueError(f"Cannot use `wait_until(...)` on objects with defined ActionChains.")
+
+        def finder(_):
+            elt = self.find(css_selector, in_page=True)
+            return elt.exists() and elt
+
+        return self.waiter.until(finder)
+
+
+    def wait_until(self, bool_provider):
+        if self._actions:
+            raise ValueError(f"Cannot use `wait_until(...)` on objects with defined ActionChains.")
+        return self.waiter.until(bool_provider)
+
+    def wait_prompt_or_alert(self):
+        def _wait(*_):
+            try:
+                return self.driver.switch_to.alert
+            except:
+                return None
+        return self.waiter.until(_wait)
+
+    def clear(self):
+        """
+        Clear the content of editable and resettable elements (no validation -> raise at runtime).
+        """
+        for elt in self.elements:
+            elt.clear()
+
+
+    #-----------------------------------------------------
+
+
+    @classmethod
+    def from_(cls, getter:'Getter', elements=None, _css_selector=None, _full_css=None):
+        """
+        Build a new Getter instance (from the given class/subclass) based on the current
+        object, updating various values on the fly.
+        """
+        return cls(
+            getter.driver,
+            getter.waiter,
+            getter.elements if elements is None else elements, # no nee dto copy the list: never mutated
+            getter._css_selector if _css_selector is None else _css_selector,
+            getter._full_css if _full_css is None else _full_css,
+        )

selenium_query/_basics/boolean_getter.py

@@ -0,0 +1,36 @@
+
+
+from typing import Any, Callable, ClassVar
+from operator import eq, ne
+
+from .base_getter import negate_output
+from .generic_value_getter import ComparerGetter
+
+
+
+class BooleanGetter(ComparerGetter):
+    """
+    Common/default behavior, equivalent to `Getter.all...`
+    """
+
+    COMBINER: ClassVar[Callable] = all
+
+    _negate_outside = False
+    """ If True, apply a negation inside the COMBINER function (aka, for each element). """
+
+    def _default_is_ok(self, is_ok: Callable[[Any,Any],bool]):
+        if self._negate:
+            return (lambda a,b: not is_ok(a,b)) if is_ok else ne
+        return is_ok or eq
+
+    @negate_output
+    def _check_elements(
+        self, ref_items, value_getter, *, is_ok = None, **_,
+    ):
+        is_ok = self._default_is_ok(is_ok)
+        out = self.COMBINER(
+            is_ok(exp, value_getter(element, prop))
+                for element in self.elements
+                for prop, exp in ref_items
+        )
+        return  not out if self._negate_outside else out