pomcorn 0.7.0__tar.gz → 0.7.1__tar.gz

{pomcorn-0.7.0 → pomcorn-0.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pomcorn
-Version: 0.7.0
+Version: 0.7.1
 Summary: Base implementation of Page Object Model
 Home-page: https://pypi.org/project/pomcorn/
 License: MIT

pomcorn-0.7.1/pomcorn/descriptors/element.py

@@ -0,0 +1,141 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, NoReturn, overload
+
+from pomcorn import locators
+
+if TYPE_CHECKING:
+    from pomcorn import WebView, XPathElement
+
+
+class Element:
+    """Descriptor for init `PomcornElement` as attribute by locator.
+
+    .. code-block:: python
+
+        # Example
+        from pomcorn import Page, Element
+
+        class MainPage(Page):
+            title_element = Element(locators.ClassLocator("page-title"))
+
+    """
+
+    cache_attribute_name = "cached_elements"
+
+    @overload
+    def __init__(
+        self,
+        locator: locators.XPathLocator | None = None,
+    ) -> None:
+        ...
+
+    @overload
+    def __init__(
+        self,
+        *,
+        relative_locator: locators.XPathLocator | None = None,
+    ) -> None:
+        ...
+
+    def __init__(
+        self,
+        locator: locators.XPathLocator | None = None,
+        *,
+        relative_locator: locators.XPathLocator | None = None,
+    ) -> None:
+        """Initialize descriptor.
+
+        Use `relative_locator` if you need to include `base_locator` of
+        instance, otherwise use `locator`.
+
+        If descriptor is used for instance of ``Page``, then
+        ``relative_locator`` is not needed, since element will be searched
+        across the entire page, not within some component.
+
+        """
+        self.locator = locator
+        self.relative_locator = relative_locator
+
+    def __set_name__(self, _owner: type, name: str) -> None:
+        """Save attribute name for which descriptor is created."""
+        self.attribute_name = name
+
+    def __get__(
+        self,
+        instance: WebView | None,
+        _type: type[WebView],
+    ) -> XPathElement:
+        """Get element with stored locator."""
+        if not instance:
+            raise AttributeError("This descriptor is for instances only!")
+        return self.prepare_element(instance)
+
+    def prepare_element(self, instance: WebView) -> XPathElement:
+        """Init and cache element in instance.
+
+        Initiate element only once, and then store it in an instance and
+        return it each subsequent time. This is to avoid calling
+        `wait_until_visible` multiple times in the init of component.
+
+        If the instance doesn't already have an attribute to store cache, it
+        will be set.
+
+        If descriptor is used for ``Component`` and
+        ``self.is_relative_locator=True``, element will be found by sum of
+        ``base_locator`` of that component and passed locator of descriptor.
+
+        """
+        if not getattr(instance, self.cache_attribute_name, None):
+            setattr(instance, self.cache_attribute_name, {})
+
+        cache = getattr(instance, self.cache_attribute_name, {})
+        if cached_element := cache.get(self.attribute_name):
+            return cached_element
+
+        element = instance.init_element(
+            locator=self._prepare_locator(instance),
+        )
+        cache[self.attribute_name] = element
+
+        return element
+
+    def _prepare_locator(self, instance: WebView) -> locators.XPathLocator:
+        """Prepare a locator by arguments.
+
+        Check that only one locator argument is passed, or none.
+        If only `relative_locator` was passed, `base_locator` of instance will
+        be added to specified in descriptor arguments. If only `locator` was
+        passed, it will return only specified one.
+
+        Raises:
+            ValueError: If both arguments were passed or neither or
+                ``relative_locator`` used not in ``Component``.
+
+        """
+        if self.relative_locator and self.locator:
+            raise ValueError(
+                "You need to pass only one of the arguments: "
+                "`locator` or `relative_locator`.",
+            )
+
+        if not self.relative_locator:
+            if not self.locator:
+                raise ValueError(
+                    "You need to pass one of the arguments: "
+                    "`locator` or `relative_locator`.",
+                )
+            return self.locator
+
+        from pomcorn import Component
+
+        if self.relative_locator and isinstance(instance, Component):
+            return instance.base_locator // self.relative_locator
+
+        raise ValueError(
+            f"`relative_locator` should be used only if descriptor used in "
+            f"component. `{instance}` is not a component.",
+        )
+
+    def __set__(self, *args, **kwargs) -> NoReturn:
+        raise ValueError("You can't reset an element attribute value!")

{pomcorn-0.7.0 → pomcorn-0.7.1}/pomcorn/locators/base_locators.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from collections.abc import Iterator
-from typing import TypeVar
+from typing import Literal, TypeVar
 
 from selenium.webdriver.common.by import By
 
@@ -120,16 +120,22 @@ class XPathLocator(Locator):
         super().__init__(by=By.XPATH, query=query)
 
     def __truediv__(self, other: XPathLocator) -> XPathLocator:
-        """Override `/` operator to implement following XPath locators."""
-        return XPathLocator(
-            query=f"//{self.related_query}/{other.related_query}",
-        )
+        """Override `/` operator to implement following XPath locators.
+
+        "/" used to select the nearest children of the current node.
+
+        """
+        return self.prepare_relative_locator(other=other, separator="/")
 
     def __floordiv__(self, other: XPathLocator) -> XPathLocator:
-        """Override `//` operator to implement nested XPath locators."""
-        return XPathLocator(
-            query=f"//{self.related_query}//{other.related_query}",
-        )
+        """Override `//` operator to implement nested XPath locators.
+
+        "//" used to select all descendants (children, grandchildren,
+        great-grandchildren, etc.) of current node, regardless of their level
+        in hierarchy.
+
+        """
+        return self.prepare_relative_locator(other=other, separator="//")
 
     def __or__(self, other: XPathLocator) -> XPathLocator:
         r"""Override `|` operator to implement variant XPath locators.
@@ -146,6 +152,10 @@ class XPathLocator(Locator):
         """
         return XPathLocator(query=f"({self.query} | {other.query})")
 
+    def __bool__(self) -> bool:
+        """Return whether query of current locator is empty or not."""
+        return bool(self.related_query)
+
     def extend_query(self, extra_query: str) -> XPathLocator:
         """Return new XPathLocator with extended query."""
         return XPathLocator(query=self.query + extra_query)
@@ -165,3 +175,49 @@ class XPathLocator(Locator):
         partial_query = f"[contains(., '{text}')]"
         exact_query = f"[./text()='{text}']"
         return self.extend_query(exact_query if exact else partial_query)
+
+    def prepare_relative_locator(
+        self,
+        other: XPathLocator,
+        separator: Literal["/", "//"] = "/",
+    ) -> XPathLocator:
+        """Prepare relative locator base on queries of two locators.
+
+        If one of parent and other locator queries is empty, the method will
+        return only the filled one.
+
+        Args:
+            other: Child locator object.
+            separator: Literal which will placed between locators queries - "/"
+                used to select nearest children of current node and "//" used
+                to select all descendants (children, grandchildren,
+                great-grandchildren, etc.) of current node, regardless of their
+                level in hierarchy.
+
+        Raises:
+            ValueError: If parent and child locators queries are empty.
+
+        """
+        related_query = self.related_query
+        if not related_query.startswith("("):
+            # Parent query can be bracketed, in which case we don't need to use
+            # `//`
+            # Example:
+            #   (//li)[3] -> valid
+            #   //(//li)[3] -> invalid
+            related_query = f"//{self.related_query}"
+
+        locator = XPathLocator(
+            query=f"{related_query}{separator}{other.related_query}",
+        )
+
+        if self and other:
+            return locator
+
+        if not (self or other):
+            raise ValueError(
+                f"Both of locators have empty query. The `{locator.query}` is "
+                "not a valid locator.",
+            )
+
+        return other if not self else self

{pomcorn-0.7.0 → pomcorn-0.7.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "pomcorn"
-version = "0.7.0"
+version = "0.7.1"
 description = "Base implementation of Page Object Model"
 authors = [
   "Saritasa <pypi@saritasa.com>",

pomcorn-0.7.0/pomcorn/descriptors/element.py

@@ -1,95 +0,0 @@
-from __future__ import annotations
-
-from typing import TYPE_CHECKING, NoReturn
-
-from pomcorn import locators
-
-if TYPE_CHECKING:
-    from pomcorn import WebView, XPathElement
-
-
-class Element:
-    """Descriptor for init `PomcornElement` as attribute by locator.
-
-    .. code-block:: python
-
-        # Example
-        from pomcorn import Page, Element
-
-        class MainPage(Page):
-            title_element = Element(locators.ClassLocator("page-title"))
-
-    """
-
-    cache_attribute_name = "cached_elements"
-
-    def __init__(
-        self,
-        locator: locators.XPathLocator,
-        is_relative_locator: bool = True,
-    ) -> None:
-        """Initialize descriptor.
-
-        Args:
-            locator: Instance of a class to locate the element in
-                the browser.
-            is_relative_locator: Whether add parent ``base_locator`` to the
-                current descriptors's `base_locator` or not. If descriptor is
-                used for ``Page``, the value of this argument will not be used.
-
-        """
-        self.is_relative_locator = is_relative_locator
-        self.locator = locator
-
-    def __set_name__(self, _owner: type, name: str) -> None:
-        """Save attribute name for which descriptor is created."""
-        self.attribute_name = name
-
-    def __get__(
-        self,
-        instance: WebView | None,
-        _type: type[WebView],
-    ) -> XPathElement:
-        """Get element with stored locator."""
-        if not instance:
-            raise AttributeError("This descriptor is for instances only!")
-        return self.prepare_element(instance)
-
-    def prepare_element(self, instance: WebView) -> XPathElement:
-        """Init and cache element in instance.
-
-        Initiate element only once, and then store it in an instance and
-        return it each subsequent time. This is to avoid calling
-        `wait_until_visible` multiple times in the init of component.
-
-        If the instance doesn't already have an attribute to store cache, it
-        will be set.
-
-        If descriptor is used for ``Component`` and
-        ``self.is_relative_locator=True``, element will be found by sum of
-        ``base_locator`` of that component and passed locator of descriptor.
-
-        If descriptor is used for instance of ``Page``, then ``base_locator``
-        is not needed, since element will be searched across the entire page,
-        not within some component.
-
-        """
-        if not getattr(instance, self.cache_attribute_name, None):
-            setattr(instance, self.cache_attribute_name, {})
-
-        cache = getattr(instance, self.cache_attribute_name, {})
-        if cached_element := cache.get(self.attribute_name):
-            return cached_element
-
-        from pomcorn import Component
-
-        if self.is_relative_locator and isinstance(instance, Component):
-            self.locator = instance.base_locator // self.locator
-
-        element = instance.init_element(locator=self.locator)
-        cache[self.attribute_name] = element
-
-        return element
-
-    def __set__(self, *args, **kwargs) -> NoReturn:
-        raise ValueError("You can't reset an element attribute value!")