pomcorn 0.3.1__tar.gz → 0.5.0__tar.gz

{pomcorn-0.3.1 → pomcorn-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pomcorn
-Version: 0.3.1
+Version: 0.5.0
 Summary: Base implementation of Page Object Model
 Home-page: https://pypi.org/project/pomcorn/
 License: MIT
@@ -112,8 +112,6 @@ Below is the code that opens ``PyPI.org``, searches for packages by name and pri
 packages to the terminal. The script contains all base classes contained in ``pomcorn``: **Page**,
 **ComponentWithBaseLocator**, **ListComponent** and **Element**.
 
-.. /* yaspeller ignore:start */
-
 .. code-block:: python
 
   from typing import Self
@@ -131,11 +129,11 @@ packages to the terminal. The script contains all base classes contained in ``po
       APP_ROOT = "https://pypi.org"
 
       def check_page_is_loaded(self) -> bool:
-          return self.init_element(locator=locators.TagNameLocator("main")).is_displayed
+          return self.init_element(locators.TagNameLocator("main")).is_displayed
 
       @property
       def search(self) -> Element[locators.XPathLocator]:
-          return self.init_element(locator=locators.IdLocator("search"))
+          return self.init_element(locators.IdLocator("search"))
 
 
   # Prepare components
@@ -185,8 +183,6 @@ packages to the terminal. The script contains all base classes contained in ``po
   search_page = SearchPage.open(webdriver=Chrome())
   print(search_page.find("saritasa").names)
 
-.. /* yaspeller ignore:end */
-
 For more information about package classes, you can read in `Object Hierarchy <https://pomcorn.readthedocs.io/en/latest/objects_hierarchy.html>`_
 and `Developer Interface <https://pomcorn.readthedocs.io/en/latest/developer_interface.html>`_.
 

{pomcorn-0.3.1 → pomcorn-0.5.0}/README.rst

@@ -86,8 +86,6 @@ Below is the code that opens ``PyPI.org``, searches for packages by name and pri
 packages to the terminal. The script contains all base classes contained in ``pomcorn``: **Page**,
 **ComponentWithBaseLocator**, **ListComponent** and **Element**.
 
-.. /* yaspeller ignore:start */
-
 .. code-block:: python
 
   from typing import Self
@@ -105,11 +103,11 @@ packages to the terminal. The script contains all base classes contained in ``po
       APP_ROOT = "https://pypi.org"
 
       def check_page_is_loaded(self) -> bool:
-          return self.init_element(locator=locators.TagNameLocator("main")).is_displayed
+          return self.init_element(locators.TagNameLocator("main")).is_displayed
 
       @property
       def search(self) -> Element[locators.XPathLocator]:
-          return self.init_element(locator=locators.IdLocator("search"))
+          return self.init_element(locators.IdLocator("search"))
 
 
   # Prepare components
@@ -159,8 +157,6 @@ packages to the terminal. The script contains all base classes contained in ``po
   search_page = SearchPage.open(webdriver=Chrome())
   print(search_page.find("saritasa").names)
 
-.. /* yaspeller ignore:end */
-
 For more information about package classes, you can read in `Object Hierarchy <https://pomcorn.readthedocs.io/en/latest/objects_hierarchy.html>`_
 and `Developer Interface <https://pomcorn.readthedocs.io/en/latest/developer_interface.html>`_.
 

{pomcorn-0.3.1 → pomcorn-0.5.0}/pomcorn/component.py

@@ -1,4 +1,3 @@
-import abc
 from typing import Generic, TypeVar, overload
 
 from . import locators
@@ -34,10 +33,12 @@ class ComponentWithBaseLocator(Generic[TPage], Component[TPage]):
 
     """
 
+    base_locator: locators.XPathLocator
+
     def __init__(
         self,
         page: TPage,
-        base_locator: locators.XPathLocator,
+        base_locator: locators.XPathLocator | None = None,
         wait_until_visible: bool = True,
     ):
         """Initialize component.
@@ -46,14 +47,14 @@ class ComponentWithBaseLocator(Generic[TPage], Component[TPage]):
             page: An instance of the page that uses this component.
             base_locator: locator: Instance of a class to locate the element in
                 the browser. Used in relative element initialization methods
-                and visibility waits.
+                and visibility waits. You also can specify it as attribute.
             wait_until_visible: Whether to wait for the component to become
                 visible before completing initialization or not.
 
         """
         super().__init__(page)
-        self.base_locator = base_locator
-        self.body = self.init_element(locator=base_locator)
+        self.base_locator = base_locator or self.base_locator
+        self.body = self.init_element(locator=self.base_locator)
 
         if wait_until_visible:
             self.wait_until_visible()
@@ -194,14 +195,44 @@ class ListComponent(
     Waits for `base_item_locator` property to be implemented and value of
     `item_class` to be set.
 
+    Waits for `base_item_locator` property  to be overridden or one of the
+    attributes (`item_locator` or `relative_item_locator`) to be specified.
+
+    The `item_class` attribute is also required.
+
     """
 
     item_class: type[ListItemType]
 
-    @abc.abstractproperty
+    item_locator: locators.XPathLocator | None = None
+    relative_item_locator: locators.XPathLocator | None = None
+
+    @property
     def base_item_locator(self) -> locators.XPathLocator:
-        """Get the base locator of list item."""
-        raise NotImplementedError
+        """Get the base locator of list item.
+
+        Raises:
+            ValueError: If both attributes are specified.
+            NotImplementedError: If no attribute has been specified,
+
+        """
+        if self.relative_item_locator and self.item_locator:
+            raise ValueError(
+                "You only need to specify one of the attributes: "
+                "`relative_item_locator` - if you want locator nested within "
+                "`base_locator`, `item_locator` - otherwise. "
+                "Or override `base_item_locator` property.",
+            )
+        if not self.relative_item_locator:
+            if not self.item_locator:
+                raise NotImplementedError(
+                    "You need to specify one of the arguments: "
+                    "`relative_item_locator` - if you want locator nested "
+                    "within `base_locator`, `item_locator` - otherwise. "
+                    "Or override `base_item_locator` property.",
+                )
+            return self.item_locator
+        return self.base_locator // self.relative_item_locator
 
     @property
     def count(self) -> int:

{pomcorn-0.3.1 → pomcorn-0.5.0}/pomcorn/exceptions.py

@@ -32,3 +32,7 @@ class AttributeDoesNotContainError(TimeoutError):
 
 class FailedFormSubmissionError(Exception):
     """Raised when there an error on form submission."""
+
+
+class PageDidNotLoadedError(Exception):
+    """Raised when page load timeout has expired."""

{pomcorn-0.3.1 → pomcorn-0.5.0}/pomcorn/locators/base_locators.py

@@ -127,6 +127,21 @@ class XPathLocator(Locator):
         """Override `//` operator to implement nested XPath locators."""
         return XPathLocator(query=f"{self.query}//{other.related_query}")
 
+    def __or__(self, other: XPathLocator) -> XPathLocator:
+        r"""Override `|` operator to implement variant XPath locators.
+
+        Example:
+            span = XPathLocator("//span")
+            div = XPathLocator("//div")
+            img = XPathLocator("//img")
+
+            (span | div) // img == XPathLocator("(//span | //div)//img")
+
+            span | div // img == XPathLocator("(//span | //div//img)")
+
+        """
+        return XPathLocator(query=f"({self.query} | {other.query})")
+
     def extend_query(self, extra_query: str) -> XPathLocator:
         """Return new XPathLocator with extended query."""
         return XPathLocator(query=self.query + extra_query)

{pomcorn-0.3.1 → pomcorn-0.5.0}/pomcorn/page.py

@@ -1,7 +1,10 @@
 from typing import Self
 
+from selenium.common.exceptions import TimeoutException
 from selenium.webdriver.remote.webdriver import WebDriver
 
+from . import locators
+from .exceptions import PageDidNotLoadedError
 from .web_view import WebView
 
 
@@ -116,7 +119,13 @@ class Page(WebView):
 
     def wait_until_loaded(self) -> None:
         """Wait until page is loaded."""
-        self.wait.until(lambda _: self.check_page_is_loaded())
+        try:
+            self.wait.until(lambda _: self.check_page_is_loaded())
+        except TimeoutException:
+            raise PageDidNotLoadedError(
+                f"Page didn't loaded in {self.wait_timeout} seconds! "
+                "Didn't wait for `True` from `check_page_is_loaded` method.",
+            )
 
     def navigate(self, url: str) -> None:
         """Navigate absolute URL.
@@ -137,6 +146,15 @@ class Page(WebView):
             self._get_full_relative_url(self.app_root, relative_url),
         )
 
+    def click_on_page(self):
+        """Click on page `html` tag.
+
+        Allows you to move focus away from an element, for example, if it
+        is currently unavailable for interaction.
+
+        """
+        self.init_element(locator=locators.TagNameLocator("html")).click()
+
     @staticmethod
     def _get_full_relative_url(app_root: str, relative_url: str) -> str:
         """Add relative URL to application root URL.

{pomcorn-0.3.1 → pomcorn-0.5.0}/pomcorn/web_view.py

@@ -47,6 +47,10 @@ class WebView:
     def init_element(self, locator: TInitLocator) -> Element[TInitLocator]:
         """Shortcut for initializing Element instances.
 
+        Note: To be consistent with the method of the same name in
+        ``ComponentWithBaseLocator``, try to use keyword when specifying
+        the ``locator`` argument whenever possible.
+
         Args:
             locator: Instance of a class to locate the element in the browser.
 
@@ -61,6 +65,10 @@ class WebView:
 
         Note: Only supports Xpath locators.
 
+        Note: To be consistent with the method of the same name in
+        ``ComponentWithBaseLocator``, try to use keyword when specifying the
+        ``locator`` argument whenever possible.
+
         Args:
             locator: Instance of a class to locate the element in the browser.
 
@@ -88,9 +96,10 @@ class WebView:
 
         For example, there are multiple elements on the page that matches
         `XPathLocator("//a")`.
+
         This method return the set of locators like:
-        * `XPathLocator("//a[1]")`
-        * `XPathLocator("//a[2]")`
+        * `XPathLocator("(//a)[1]")`
+        * `XPathLocator("(//a)[2]")`
 
         Args:
             locator: Instance of a class to locate the element in the browser.
@@ -344,11 +353,22 @@ class WebView:
     def scroll_to(self, target: WebElement):
         """Scroll page to target.
 
+        Scroll to the center of target vertically and to the center of target
+        horizontally.
+
         Args:
             target: The web element instance to scroll to.
 
         """
-        self.webdriver.execute_script("arguments[0].scrollIntoView();", target)
+        # behavior="instant" - to scroll without animation
+        # block="center" - vertical scrolling up to center
+        # inline="center"- horizontal scrolling up to center
+        script = (
+            "arguments[0].scrollIntoView("
+            "{behavior: 'instant', block: 'center', inline: 'center'}"
+            ");"
+        )
+        self.webdriver.execute_script(script, target)
 
     def scroll_to_top(self):
         """Scroll browser to top."""

{pomcorn-0.3.1 → pomcorn-0.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "pomcorn"
-version = "0.3.1"
+version = "0.5.0"
 description = "Base implementation of Page Object Model"
 authors = [
   "Saritasa <pypi@saritasa.com>",
@@ -70,13 +70,13 @@ pytest = ">= 7.4.2"
 # Flake dependencies are added so that VSCode extension for flake8
 # would work properly
 # https://marketplace.visualstudio.com/items?itemName=ms-python.flake8&ssr=false#overview
-flake8 = "^6.1.0"
+flake8 = ">=6.1,<8.0"
 # A flake8 plugin that warn about backslashes usage.
 # https://github.com/wemake-services/flake8-broken-line
 flake8-broken-line = "^1.0.0"
 # A plugin for Flake8 finding likely bugs and design problems in your program.
 # https://github.com/PyCQA/flake8-bugbear
-flake8-bugbear = "^23.9.16"
+flake8-bugbear = ">=23.9.16,<25.0.0"
 # A simple module that adds an extension for the fantastic pydocstyle tool to flake8.
 # https://github.com/PyCQA/flake8-docstrings
 flake8-docstrings = "^1.7.0"