pomcorn 0.7.0__py3-none-any.whl → 0.7.1__py3-none-any.whl

pomcorn/descriptors/element.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, NoReturn
+from typing import TYPE_CHECKING, NoReturn, overload
 
 from pomcorn import locators
 
@@ -23,23 +23,39 @@ class Element:
 
     cache_attribute_name = "cached_elements"
 
+    @overload
     def __init__(
         self,
-        locator: locators.XPathLocator,
-        is_relative_locator: bool = True,
+        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.
 
-        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.
+        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.is_relative_locator = is_relative_locator
         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."""
@@ -69,10 +85,6 @@ class Element:
         ``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, {})
@@ -81,15 +93,49 @@ class Element:
         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)
+        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/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.dist-info → pomcorn-0.7.1.dist-info}/METADATA

@@ -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.0.dist-info → pomcorn-0.7.1.dist-info}/RECORD

@@ -1,17 +1,17 @@
 pomcorn/__init__.py,sha256=V8v_V3wgKbao1KAQkcVTMnpGwyslw0nHfuTp-DwWTXg,318
 pomcorn/component.py,sha256=7nRt-A20Psm0Xl7Rm6tRUK8yOhIh4t2Bdm1fwmJ0MjA,8385
 pomcorn/descriptors/__init__.py,sha256=5q_d5GtcaFlIIyHdsUnE9UNbz3g40qJCHKNaWGvcC6s,72
-pomcorn/descriptors/element.py,sha256=hde1dcKqKXH9DPKEHfaGyyYlDYlpOf4an-PulZQhxvI,3147
+pomcorn/descriptors/element.py,sha256=4g_4ay5f00AXzCT4xHN1i7mTrlsECoUHh1Ph_TFPBDs,4502
 pomcorn/element.py,sha256=uxcqf3EK1TzDgdjQzhP2Ovf8GDsdas_tsJs_xPt62gI,12400
 pomcorn/exceptions.py,sha256=8ZOmrybDwvEVZRLQzyozjRNhJvSLbablaFwGFUVMhrU,1131
 pomcorn/locators/__init__.py,sha256=hNSlfmz3y-LI4PXF5VIwX8J5WSalyE2wmzuYc6kNxMA,708
-pomcorn/locators/base_locators.py,sha256=fk70jn87jOWx7eladEW7a9Vo4slYJnizW7yoLXijefU,5140
+pomcorn/locators/base_locators.py,sha256=B4SDSKi5j7kqwbxllnMHU9BKBJzn_dzNRphPQ2hTuss,7065
 pomcorn/locators/xpath_locators.py,sha256=OjwTdHwqDfX_5aP0N6YeFwRl2gPr8ZNQny8yLxBrVCo,7264
 pomcorn/page.py,sha256=JdCDDVP4q2r5HwxSRnD9Sg43tgpCyrqu_jEux2E4ARY,5475
 pomcorn/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 pomcorn/waits_conditions.py,sha256=E8sLfBvIV2EO91Mm5KyKXB5IGEB9gUWza3XPE4_aCQE,3528
 pomcorn/web_view.py,sha256=PlwEVgdOwFZXJY2WuUT2C2wyK1xOBJne5-A_FOuwsQI,14209
-pomcorn-0.7.0.dist-info/LICENSE,sha256=1vmhQNp1dDH8ksJ199LuG4oKz5D4ZvNccPcFckiG2S4,1091
-pomcorn-0.7.0.dist-info/METADATA,sha256=jnkNjl4KfqhRHNr55CLycO3VWp-s0T-8Yh4ey29abGo,5949
-pomcorn-0.7.0.dist-info/WHEEL,sha256=d2fvjOD7sXsVzChCqf0Ty0JbHKBaLYwDbGQDwQTnJ50,88
-pomcorn-0.7.0.dist-info/RECORD,,
+pomcorn-0.7.1.dist-info/LICENSE,sha256=1vmhQNp1dDH8ksJ199LuG4oKz5D4ZvNccPcFckiG2S4,1091
+pomcorn-0.7.1.dist-info/METADATA,sha256=plUXXe1KZnwCkzQm8M7XmRUMK0iSt1t11AW5LDfsMHo,5949
+pomcorn-0.7.1.dist-info/WHEEL,sha256=d2fvjOD7sXsVzChCqf0Ty0JbHKBaLYwDbGQDwQTnJ50,88
+pomcorn-0.7.1.dist-info/RECORD,,