selenium-query 0.1.0__py3-none-any.whl

selenium_query/_basics/generic_value_getter.py

@@ -0,0 +1,119 @@
+
+from typing import Any, Callable, Optional, Sequence, Tuple
+
+from selenium.webdriver.remote.webelement import WebElement
+
+from .._types_and_tools import Expected, Actual
+from .base_getter import BaseGetter
+
+
+
+
+# Value getters:
+def element_is_as_method(elt:WebElement, prop:str):
+    return getattr(elt, prop)()
+
+def element_rect_value(elt:WebElement, prop:str):
+    return elt.rect[prop]
+
+# is_ok:
+def contains(exp:Expected, act:Actual):
+    return act is not None and exp in act
+
+def contains_as_list(exp:Expected, act:Actual):
+    return act is not None and exp in act.split()
+
+# feedback:
+def should_contain(exp:Expected, act:Actual, with_neg:bool):
+    return f"{act!r} should { ' not'*with_neg }contain {exp!r}"
+
+def should_be(exp:Expected, act:Actual, with_neg:bool):
+    return f"{act!r} should { ' not'*with_neg }be {exp!r}"
+
+
+
+class ComparerGetter(BaseGetter):
+    """
+    Verify that all the elements are matching the given arguments (css, data, props, ...),
+    returning a boolean.
+    """
+
+    def id(self, txt:str):
+        expectations = ( ("id",txt), )
+        return self._check_elements(expectations, WebElement.get_attribute)
+
+    def has_class(self, txt:str):
+        expectations = ( ("class",txt), )
+        return self._check_elements(
+            expectations, WebElement.get_attribute,
+            is_ok = contains_as_list,
+            feedback = should_contain
+        )
+
+    def tag_name(self, txt:str):
+        expectations = ( ("tag_name",txt), )
+        return self._check_elements(expectations, getattr)
+
+    def text(self, txt:str):
+        expectations = ( ("text",txt), )
+        return self._check_elements(expectations, getattr)
+
+    def has_text(self, txt:str):
+        expectations = ( ("text",txt), )
+        return self._check_elements(expectations, getattr, is_ok=contains, feedback=should_contain)
+
+    def is_enabled(self, expected:bool=True):
+        expectations = ( ("is_enabled",expected), )
+        return self._check_elements(expectations, element_is_as_method)
+
+    def is_selected(self, expected:bool=True):
+        expectations = ( ("is_selected",expected), )
+        return self._check_elements(expectations, element_is_as_method)
+
+    def is_displayed(self, expected:bool=True):
+        expectations = ( ("is_displayed",expected), )
+        return self._check_elements(expectations, element_is_as_method)
+
+    def css(self, dct=None, **kwargs:Any):
+        expectations = self._merge_args(dct,kwargs).items()
+        return self._check_elements(expectations, WebElement.value_of_css_property)
+
+    def data(self, dct=None, **kwargs:Any):
+        expectations = {'data'+s: v for s,v in self._merge_args(dct,kwargs).items()}
+        return self.props(expectations)
+
+    def props(self, dct=None, **kwargs:Any):
+        expectations = self._merge_args(dct,kwargs).items()
+        return self._check_elements(expectations, WebElement.get_attribute)
+
+    def rect(self, *, x:float=None, y:float=None, width:float=None, height:float=None):
+        items = (('x',x), ('y',y), ('width',width), ('height',height))
+        expectations = tuple( (prop,exp) for prop,exp in items if exp is not None ),
+        return self._check_elements(expectations, element_rect_value)
+
+
+    #----------------------------------------------------------------------------
+
+
+    def _merge_args(self, dct:Optional[dict], kwargs:dict):
+        if dct:
+            kwargs.update(dct)
+        return kwargs
+
+    def _check_elements(
+        self,
+        ref_items:    Sequence[Tuple[str,Expected]],
+        value_getter: Callable[[WebElement,str],Any],
+        *,
+        is_ok:        Callable[[Expected,Actual],bool] = None,
+        feedback:     Callable[[Any,Any],bool] = None,
+    ):
+        """
+        Method applying the logic of the child class to each of the properties/values/...
+
+        @ref_items: Sequence/Iterable (NOT a generator) of tuples `(prop_or_attr, expected_value)`.
+        @value_getter: Access the value for the given string on the WebElement.
+        @is_ok: if needed, compare expected value with the value coming from the value_getter.
+        @feedback: build a string for assertion messages (see AssertGetter).
+        """
+        raise NotImplementedError()

selenium_query/_filter_getter.py

@@ -0,0 +1,53 @@
+from typing import Any, Callable
+
+from selenium.webdriver.remote.webelement import WebElement
+
+from .getter import Getter
+
+
+class FilterGetter(Getter, accessor="filter"):
+    """
+    Accessible through `Getter.filter`.
+    Transform the css, data, props, ... methods into filters: each of them now returns a
+    new FilterGetter instance whose the elements are only containing those which match the
+    desired values.
+
+    Basic usage:
+
+        Getter(...).filter.has_class('this')  ->  FilterGetter
+
+    FilterGetter instances can use custom predicates when called. The predicate takes a
+    Getter object as argument (one per `self.elements`):
+
+        Getter.filter(predicate)  ->  FilterGetter
+    """
+
+    def __call__(self, getter_ok:Callable[[Getter],bool]):
+        out = [g.elements[0] for g in self if getter_ok(g)]
+        return self.from_(self, elements=out)
+
+
+    def _check_elements(
+        self,
+        ref_items,
+        value_getter: Callable[[WebElement,str],Any],
+        *,
+        is_ok:        Callable[[Any,Any],bool] = None,
+        **_,
+    ) -> 'FilterGetter':
+        """
+        The method now returns a new Getter instance whose the elements list only contains those
+        which match the criteria given to the calling method (css, data, props, ...).
+        """
+        is_ok = self._default_is_ok(is_ok)
+        out = [
+            element
+            for element in self.elements
+            if all( is_ok(exp, value_getter(element, prop)) for prop, exp in ref_items)
+        ]
+        return self.from_(self, elements=out)
+
+    @classmethod
+    def from_(cls, getter:'Getter', elements=None, _css_selector=None, _full_css=None):
+        return super().from_(getter, elements, _css_selector, (_full_css or getter._full_css)+"[filtered]")
+

selenium_query/_mapper_getter.py

@@ -0,0 +1,226 @@
+from dataclasses import dataclass, field
+from types import MethodType
+from typing import Any, Dict, List, Optional, Tuple
+
+
+from ._types_and_tools import MAPPER_GETTER_FOLLOW_UP, TGetter
+from ._basics.base_getter import forbid_negation
+from .getter import Getter
+
+
+
+_FORBIDDEN_FOLLOW_UP = 'go', 'perform', 'scroll_to', 'map', 'not_'
+
+
+
+@dataclass
+class MapperTransmitter(Getter):
+    """
+    Extends Getter for auto completion purpose only: the actual interface is different.
+    """
+    _source: TGetter = None
+    _prop: str = None
+    _call_args: Optional[Tuple[Any]] = None
+
+
+    def __getattribute__(self, k:str):
+        _getattr = super().__getattribute__
+
+        if k in MAPPER_GETTER_FOLLOW_UP:
+            source: MapperGetter = _getattr('_source')
+            return source._apply(k, transmitter=self)
+
+        kls = _getattr('__class__')
+        is_mapper_getter_attribute = k in _getattr('__dict__') or k in kls.__dict__
+        if is_mapper_getter_attribute:
+            return _getattr(k)
+
+        raise ValueError(f"Cannot use `{k}` on { kls.__name__ } objects.")
+
+
+    def __call__(self, *a, **kw):
+        """
+        Relay to standardize TransmitterGetters for `.check(...)` or `.order_by(...)`.
+        """
+        self._call_args = a, kw
+        return self
+
+
+    def _apply(self, mapped:'Getter'):
+        out = getattr(mapped, self._prop)
+        if self._call_args:
+            a, kw = self._call_args
+            out = out(*a, **kw)
+        return out
+
+
+
+
+
+
+
+@dataclass(repr=False)
+class MapperGetter(Getter, accessor="map"):
+    """
+    Allow to work with a Getter "behaving like a list": the attributes/methods calls are
+    transferred to the elements (as Getters) instead of being applied to the current Getter.
+
+    Some methods or attributes accesses are forbidden on MapperGetter objects:
+        'go', 'perform', 'scroll_to', 'map'
+
+    Any subsequent "Getter" related method call (see `_GETTERS`) whose arguments are lists will
+    automatically map the lists elements to each internal `MapperGetter.elements` when transmitting
+    the methods call. The length of the lists and the one of `MapperGetter.elements` are check up
+    front and have to match, or ValueError is raised.
+
+    Other methods or property calls are working directly applying to the MapperGetter instance.
+
+    Examples:
+
+        G = Getter(...)
+        G.check.count(3)
+
+        mapped = G.map('li.that-class')             # Equivalent to applying `find` to each element
+        mapped.count() == [1,4,6]                   # Gives the number of `li.that-class` elements
+                                                    # held by each of the original G elements.
+
+    Note this class is really helpful only when testing hierarchical DOM structures, otherwise,
+    assertions with different expectations for each elements can already be done through
+    AsserterGetter objects, passing in lists or tuples, instead of values.
+    """
+
+    elements: List[Getter] = field(default_factory=list)
+    """ Override """
+
+
+    @classmethod
+    def from_(cls, getter:Getter, _css_selector=None, _full_css=None):
+        return super().from_(getter, [*getter], _css_selector, _full_css)
+
+
+    def __call__(self, css_selector:str=None):
+        if css_selector is not None:
+            self.elements = [g.find(css_selector) for g in self.elements]
+        return self
+
+
+
+    def __iter__(self):
+        yield from self.elements
+
+    def __getitem__(self, idx:int):
+        return self.elements[idx]
+
+
+    def __getattribute__(self, k:str):
+        _getattr = super().__getattribute__
+        if k in _FORBIDDEN_FOLLOW_UP:
+            raise ValueError(f"Cannot use {k} on MapperGetter objects.")
+
+        if _getattr('subclass').is_getter_property(k):
+            return MapperTransmitter(driver=None, waiter=None, _source=self, _prop=k)
+
+        if k in MAPPER_GETTER_FOLLOW_UP:
+            return super().__getattribute__('_apply')(k)
+
+        # Using "normal" methods/logic: just use the basic "get" logic
+        return _getattr(k)
+
+
+    @forbid_negation
+    def _apply(self, prop:str, transmitter:Optional[MapperTransmitter]=None):
+        if not self.elements:
+            raise ValueError(f"Cannot `_apply` on an empty MapperGetter instance.")
+
+        out = []
+        for g in self.elements:
+            if transmitter is not None:
+                g = transmitter._apply(g)
+            out.append(getattr(g, prop))
+
+        # If the values are actually bound methods, the next operation will be a method call:
+        if isinstance(out[0], MethodType):
+            return self._apply_caller(out)
+        return out
+
+
+    def _apply_caller(self, bound_methods:List[MethodType]):
+        def call(*a, zip_args=True, non_existent_at_idxs=(), **kw):
+            """
+            If @zip_args=False, directly transfer *args and ù**kwargs to the bound methods, without
+            applying any zipping/mapping logic on values given as lists.
+
+            If @non_existent_at_idxs is given, it must be a tuple of indices. The bound method at these
+            indices won't be called and their source Getter have to be non existent, otherwise an
+            error will be raised.
+            """
+            self._validate_non_existent_elements(bound_methods, non_existent_at_idxs)
+
+            if zip_args:
+                args = self._validate_and_standardize_args(a)
+                kwargs = self._validate_and_standardize_kwargs(kw)
+                out = [
+                    method.__self__ if i in non_existent_at_idxs else method(*aa, **kkw)
+                    for i,(method, aa, kkw) in enumerate(zip(bound_methods, args, kwargs))
+                ]
+
+            else:
+                out = [
+                    method.__self__ if i in non_existent_at_idxs else method(*a,**kw)
+                    for i,method in enumerate(bound_methods)
+                ]
+
+            if isinstance(out[0], Getter):
+                # elements are already Getters, no need to convert again:
+                return super(self.__class__, self).from_(self, elements=out)
+            return out
+
+        return call
+
+
+    #------------------------------------------------------------------------------------------------
+
+
+    def _validate_non_existent_elements(self, bound_methods, non_existent_at_idxs):
+        if non_existent_at_idxs and (existents := [
+            bound_methods[i].__self__
+                for i in non_existent_at_idxs if len(bound_methods[i].__self__.elements)
+        ]):
+            raise ValueError(
+                f"These Getters should have zero elements:\n  "+'\n  '.join(map(str,existents))
+            )
+
+
+    def _validate_and_standardize_args(self, args: Tuple[Any]):
+        wrong_indices = [
+            i for i,v in enumerate(args)
+              if isinstance(v, (list,tuple)) and len(v) != len(self.elements)
+        ]
+        if wrong_indices:
+            raise ValueError(
+                f"Mismatched list or tuple argument length at indices {wrong_indices} in {args} "
+                f"(expected length: {len(self.elements)})"
+            )
+
+        out_args = tuple(
+            tuple( arg[i] if isinstance(arg, (list,tuple)) else arg for arg in args)
+            for i in range(len(self.elements))
+        )
+        return out_args
+
+
+    def _validate_and_standardize_kwargs(self, kw: Dict[str,Any] ):
+        lists_or_tuples_kw = tuple((k,v) for k,v in kw.items() if isinstance(v,(list,tuple)))
+        if lists_or_tuples_kw and (wrong_keys := [
+            k for k,v in lists_or_tuples_kw if len(v) != len(self.elements)
+        ]):
+            raise ValueError(
+                f"Mismatched list or tuple value length for kwargs (keys: {wrong_keys}. "
+                f"Expected length: {len(self.elements)})"
+            )
+
+        out_kw = (kw,)*len(self.elements) if not lists_or_tuples_kw else tuple(
+            {k: v[i] if isinstance(v,(tuple,list)) else v for k,v in kw.items()}
+            for i in range(len(self.elements))
+        )
+        return out_kw

selenium_query/_negation_transmitter.py

@@ -0,0 +1,40 @@
+from dataclasses import dataclass
+
+from ._types_and_tools import TGetter
+from .getter import Getter
+
+
+FORBIDDEN_NOT_FOLLOW_UP = set("""
+    map order_by
+""".strip().split())
+
+
+@dataclass
+class NotTransmitter(Getter, accessor='not_'):
+    """
+    Extends Getter mostly for auto completion purpose.
+    """
+    source: TGetter = None
+
+
+    def __getattribute__(self, k:str):
+        src: TGetter = super().__getattribute__('source')
+        out = src.from_(src)
+
+        if k in FORBIDDEN_NOT_FOLLOW_UP:
+            raise ValueError(f"Cannot use `{k}` attribute access after the `not_` attribute.")
+
+        elif k in ('any', 'all'):
+            out._negate_outside = not out._negate_outside
+
+        elif k != 'not_':
+            out._negate =  not out._negate
+
+        return getattr(out, k)
+
+
+    @classmethod
+    def from_(cls, getter, elements=None, _css_selector=None, _full_css=None):
+        out = super().from_(getter, elements, _css_selector, _full_css)
+        out.source = getter
+        return out

selenium_query/_order_getter.py

@@ -0,0 +1,70 @@
+from typing import Any, Callable, List
+
+from selenium.webdriver.remote.webelement import WebElement
+
+from .getter import Getter
+from ._values_getter import ValuesGetter
+
+
+
+
+class OrderGetter(ValuesGetter, accessor="order_by"):
+    """
+    Enable to sort the inner `elements` in various ways, returning a new instance of
+    the original class.
+
+        Getter(...).order_by.id  ->  Getter
+        Getter(...).order_by.has_class("xxx")  ->  Getter
+
+    It is possible to sort the elements with a custom key function by calling the OrderGetter
+    instance. The key function takes a Getter argument:
+
+        Getter(...).order_by(custom_key_as_getter)  ->  Getter
+    """
+
+    _src_getter: Getter
+
+    # Autocompletion helpers: override the types WITHOUT assigning any actual value:
+    id: Getter
+    class_: Getter
+    tag_name: Getter
+    text: Getter
+    rect: Getter
+    is_enabled: Getter                  # WARNING: use as property!!
+    is_selected: Getter                 # WARNING: use as property!!
+    is_displayed: Getter                # WARNING: use as property!!
+    css: Callable[[Getter],Getter]
+    data: Callable[[Getter],Getter]
+    props: Callable[[Getter],Getter]
+
+
+    @classmethod
+    def from_(cls, getter, elements=None, _css_selector=None, _full_css=None):
+        orderer = super().from_(getter, elements, _css_selector, _full_css)
+        orderer._src_getter = getter
+        return orderer
+
+
+    def __call__(self, keyer: Callable[[Getter],Any]):
+        keys = [ keyer(g) for g in self ]
+        return self.__order(keys)
+
+
+    def _get_values(self, names, value_getter):
+        keys = super()._get_values(names, value_getter)
+        return self.__order(keys)
+
+
+    def __order(self, keys:List[Any]):
+        # Avoid any trouble (output types changing when only one element) + speed up:
+        if len(self.elements) == 1:
+            return self._src_getter
+
+        # Standardization if some elements returned list and others returned bare values (this
+        # may happen because of the ValueGetter logistic), to avoid crashes during comparisons:
+        if 0 < sum(isinstance(v, list) for v in keys) < len(keys):
+            keys = [ v if isinstance(v, list) else [v] for v in keys ]
+
+        by_idx  = sorted(range(len(self.elements)), key=keys.__getitem__)
+        ordered = [self.elements[i] for i in by_idx]
+        return self._src_getter.from_(self._src_getter, elements=ordered)

selenium_query/_types_and_tools.py

@@ -0,0 +1,93 @@
+from functools import cached_property
+from dataclasses import dataclass, fields
+from contextlib import _GeneratorContextManager
+from typing import Any, Dict, Literal, Type, TypeVar, Union, TYPE_CHECKING
+
+
+if TYPE_CHECKING:
+    from ._any_all_getters import BoolAnyGetter, BoolAllGetter
+    from ._values_getter import ValuesGetter
+    from ._asserter_getter import AsserterGetter
+    from ._filter_getter import FilterGetter
+    from ._negation_transmitter import NotTransmitter
+    from ._order_getter import OrderGetter
+    from ._mapper_getter import MapperGetter
+    from .getter import Getter
+
+
+
+Expected = Any
+Actual = Any
+GetterOrCss = Union['Getter',str]
+Rect = Dict[Literal['x','y','width','height'],float]
+WaitingContext = _GeneratorContextManager[None, None, None]
+
+
+TGetter = TypeVar('TGetter', bound='Getter')
+
+
+
+@dataclass
+class _GetterSubClassesAsProperties:
+
+    all:      Type['BoolAllGetter'] = None
+    any:      Type['BoolAnyGetter'] = None
+    check:    Type['AsserterGetter'] = None
+    filter:   Type['FilterGetter'] = None
+    get:      Type['ValuesGetter'] = None
+    order_by: Type['OrderGetter'] = None
+    map:      Type['MapperGetter'] = None
+    not_:     Type['NotTransmitter'] = None
+
+    @cached_property
+    def fields(self):
+        return {f.name for f in fields(self.__class__)}
+
+    def is_getter_property(self, prop:str):
+        return prop in self.fields
+
+
+
+
+def center_of(g:'Getter'):
+    d = g.get.rect
+    return d['x'] + d['width']/2, d['y'] + d['height']/2
+
+
+
+MAPPER_GETTER_FOLLOW_UP = set("""
+exists
+count
+find
+__getitem__
+id
+class_
+has_class
+tag_name
+text
+has_text
+is_enabled
+is_selected
+is_displayed
+css
+data
+props
+rect
+reset_actions
+click
+click_and_hold
+context_click
+double_click
+drag_and_drop
+drag_and_drop_by_offset
+key_down
+key_up
+moved_by_offset
+move_to
+move_to_element
+move_to_element_with_offset
+pause
+release
+send_keys_to_element
+send_keys
+""".split())

selenium_query/_values_getter.py

@@ -0,0 +1,78 @@
+from dataclasses import dataclass
+from typing import Any, Callable, Collection
+
+from selenium.webdriver.remote.webelement import WebElement
+
+
+
+from ._types_and_tools import Rect
+from ._basics.base_getter import forbid_negation
+from ._basics.generic_value_getter import element_is_as_method
+from .getter import Getter
+
+
+
+
+
+
+@dataclass(repr=False)
+class ValueNameSetter:
+
+    value_getter: Callable[[WebElement,str],Any]
+    name: str = None
+
+    def __set_name__(self, _, prop):
+        self.name = (self.name or prop).rstrip("_")         # Stripping because of `class_`
+
+    def __get__(self, obj:'ValuesGetter', kls):
+        return obj._get_values((self.name,), self.value_getter)
+
+
+
+
+class ValuesGetter(Getter, accessor="get"):
+    """
+    Extract the corresponding value(s) from the current Getter. The output type may change,
+    depending on the way the call is done and on what Getter object.
+
+    Depending on the number of elements:
+    * If the getter has only one element, the output is the value's) matching that element.
+    * If there are several elements, the output is a list of this/those value(s).
+
+    Depending on the number of values asked for (may happen when using css, data or props):
+    * If there are several kind of values asked for, the corresponding output value is a dict
+    (hence, a list of dicts, is several elements).
+    * If only one kind of value is asked for, the output is the value itself (hence, a list of
+    values if several elements).
+    """
+
+    @forbid_negation
+    def _get_values(self, names:Collection[str], value_getter: Callable[[WebElement,str],Any]):
+        if len(names)==1:
+            name = names[0]
+            out = [ value_getter(element, name) for element in self.elements ]
+        else:
+            out =[
+                { prop: value_getter(element, prop) for prop in names }
+                for element in self.elements
+            ]
+        return out if len(self.elements) != 1 else out[0]
+
+    id: str = ValueNameSetter(WebElement.get_attribute)
+    class_: str = ValueNameSetter(WebElement.get_attribute)
+    tag_name: str = ValueNameSetter(getattr)
+    text: str = ValueNameSetter(getattr)
+    rect: Rect = ValueNameSetter(getattr)
+    is_enabled: bool = ValueNameSetter(element_is_as_method)      # WARNING: use as property!!
+    is_selected: bool = ValueNameSetter(element_is_as_method)     # WARNING: use as property!!
+    is_displayed: bool = ValueNameSetter(element_is_as_method)    # WARNING: use as property!!
+
+    def css(self, *args:str):
+        return self._get_values(args, WebElement.value_of_css_property)
+
+    def data(self, *args:str):
+        args = tuple( "data-"+s for s in args )
+        return self._get_values(args, WebElement.get_attribute)
+
+    def props(self, *args:str):
+        return self._get_values(args, WebElement.get_attribute)