wcp-library 1.6.3__py3-none-any.whl → 1.6.5__py3-none-any.whl

wcp_library/__init__.py

@@ -1,14 +1,27 @@
+import asyncio
+import logging
+import random
 import sys
+import time
+from functools import wraps
 from pathlib import Path
-from typing import Generator
+from typing import Callable, Generator, Optional, Type
 
 # PyInstaller import
 import pip_system_certs.wrapt_requests
 import cryptography.hazmat.primitives.kdf.pbkdf2
 
+logger = logging.getLogger(__name__)
+
+# For retry logic
+MAX_ATTEMPTS = 5
+DELAY = 2
+BACKOFF = 2
+JITTER = 3
+
 
 # Application Path
-if getattr(sys, 'frozen', False):
+if getattr(sys, "frozen", False):
     application_path = sys.executable
     application_path = Path(application_path).parent
 else:
@@ -25,4 +38,94 @@ def divide_chunks(list_obj: list, size: int) -> Generator:
     """
 
     for i in range(0, len(list_obj), size):
-        yield list_obj[i:i + size]
+        yield list_obj[i : i + size]
+
+
+def retry(
+    exceptions: tuple[Type[Exception]],
+    max_attempts: Optional[int] = MAX_ATTEMPTS,
+    delay: Optional[int] = DELAY,
+    backoff: Optional[int] = BACKOFF,
+    jitter: Optional[int] = JITTER,
+) -> Callable:
+    """
+    Decorator to retry a synchronous function on a specified exception with exponential backoff and jitter.
+
+    :param exceptions: Tuple of exception types to catch and retry on.
+    :param max_attempts: Maximum number of retry attempts.
+    :param delay: Initial delay between retries (in seconds).
+    :param backoff: Multiplier to increase delay after each failure.
+    :param jitter: Maximum number of seconds to add randomly to each delay.
+    :return: The decorated function with retry logic.
+    """
+
+    def decorator(func: Callable) -> Callable:
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            wait_time = delay
+
+            for attempt in range(0, max_attempts):
+                try:
+                    return func(*args, **kwargs)
+                except exceptions as error:
+                    if attempt == max_attempts:
+                        logger.error("Retry failed after %d attempts.", max_attempts)
+                        raise
+
+                    randomized_delay = wait_time + random.uniform(0, jitter)
+                    logger.warning(
+                        "Attempt %d failed: %s. Retrying in %.2f seconds...",
+                        attempt,
+                        error,
+                        randomized_delay,
+                    )
+                    time.sleep(randomized_delay)
+                    wait_time *= backoff
+            return None
+        return wrapper
+    return decorator
+
+
+def async_retry(
+    exceptions: tuple[Type[Exception]],
+    max_attempts: Optional[int] = MAX_ATTEMPTS,
+    delay: Optional[int] = DELAY,
+    backoff: Optional[int] = BACKOFF,
+    jitter: Optional[int] = JITTER,
+) -> Callable:
+    """
+    Decorator to retry an async function on a specified exception with exponential backoff and jitter.
+
+    :param exceptions: Tuple of exception types to catch and retry on.
+    :param max_attempts: Maximum number of retry attempts.
+    :param delay: Initial delay between retries (in seconds).
+    :param backoff: Multiplier to increase delay after each failure.
+    :param jitter: Maximum number of seconds to add randomly to each delay.
+    :return: The decorated async function with retry logic.
+    """
+
+    def decorator(func: Callable) -> Callable:
+        @wraps(func)
+        async def wrapper(*args, **kwargs):
+            wait_time = delay
+
+            for attempt in range(0, max_attempts):
+                try:
+                    return await func(*args, **kwargs)
+                except exceptions as error:
+                    if attempt == max_attempts:
+                        logger.error("Retry failed after %d attempts.", max_attempts)
+                        raise
+
+                    randomized_delay = wait_time + random.uniform(0, jitter)
+                    logger.warning(
+                        "Attempt %d failed: %s. Retrying in %.2f seconds...",
+                        attempt,
+                        error,
+                        randomized_delay,
+                    )
+                    await asyncio.sleep(randomized_delay)
+                    wait_time *= backoff
+            return None
+        return wrapper
+    return decorator

wcp_library/browser_automation/browser.py

@@ -0,0 +1,299 @@
+"""
+This module provides a framework for browser automation using Selenium WebDriver.
+
+It defines a base class `BaseSelenium` that encapsulates shared functionality for browser setup,
+option configuration, and lifecycle management. Subclasses for specific browsers—`Chrome`,
+`Firefox`, and `Edge`—extend this base to implement browser-specific driver creation.
+
+Additionally, the `Browser` context manager simplifies the use of these classes by managing
+initialization and cleanup of browser sessions.
+
+Classes:
+    BaseSelenium: Abstract base class for browser automation.
+    Chrome: Chrome-specific WebDriver implementation.
+    Firefox: Firefox-specific WebDriver implementation.
+    Edge: Edge-specific WebDriver implementation.
+    Browser: Context manager for browser session lifecycle.
+
+Usage:
+    with Browser(Firefox) as browser:
+        browser.go_to("https://example.com")
+"""
+
+import logging
+from typing import Dict, Optional
+
+from selenium import webdriver
+from selenium.webdriver.chrome.options import Options as ChromeOptions
+from selenium.webdriver.firefox.options import Options as FirefoxOptions
+from selenium.webdriver.edge.options import Options as EdgeOptions
+from yarl import URL
+
+from wcp_library.browser_automation.interactions import UIInteractions, WEInteractions
+
+logger = logging.getLogger(__name__)
+
+# +--------------------------------------------------------------------------------------------------------------------------------------------------------+
+# |                                                    ===  Browser options and usage  ===                                                                 |
+# +--------------+--------------------------------------------+-----------------------------------------------+--------------------------------------------+
+# | Browser      | Description                                | JSON Configuration                            | Possible Permutations                      |
+# +--------------+--------------------------------------------+-----------------------------------------------+--------------------------------------------+
+# | All Browsers | Set browser timeouts (in ms)               | {"timeouts": {"implicit": 5000, ...}}         | implicit, pageLoad, script                 |
+# | All Browsers | Name of the browser (e.g., 'chrome', ...)  | {"browserName": "chrome"}                     | chrome, firefox, edge, safari              |
+# | All Browsers | Specific version of the browser to use.    | {"browserVersion": "latest"}                  | latest, 91.0, 90.0                         |
+# | All Browsers | OS platform (e.g., 'Windows 10', 'Linux')  | {"platformName": "Windows 10"}                | Windows 10, Linux, macOS                   |
+# | All Browsers | Strategy for page loads: normal, eager...  | {"pageLoadStrategy": "normal"}                | normal, eager, none                        |
+# | All Browsers | Accept self-signed or invalid certs        | {"acceptInsecureCerts": true}                 | true, false                                |
+# | Chrome       | Run browser in headless mode               | {"args": ["--headless"]}                      | --headless                                 |
+# | Chrome       | Disable GPU acceleration                   | {"args": ["--disable-gpu"]}                   | --disable-gpu                              |
+# | Chrome       | Set experimental options                   | {"prefs": {"download.default_directory":...}} | profile.default_content_settings.popups... |
+# | Chrome       | Set path to Chrome binary                  | {"binary": "/path/to/chrome"}                 | /path/to/chrome                            |
+# | Chrome       | Set Chrome extensions                      | {"extensions": ["/path/to/extension"]}        | /path/to/extension                         |
+# | Chrome       | Exclude switches                           | {"excludeSwitches": ["enable-automation"]}    | enable-automation                          |
+# | Chrome       | Use automation extension                   | {"useAutomationExtension": false}             | true, false                                |
+# | Firefox      | Set download folder list                   | {"prefs": {"browser.download.folderList": 2}} | 1(Download folder), 2(User set directory)  |
+# | Firefox      | Set download directory                     | {"prefs": {"browser.download.dir": "/tmp"}}   | /tmp                                       |
+# | Firefox      | Run Firefox in headless mode               | {"args": ["-headless"]}                       | -headless                                  |
+# | Firefox      | Set Firefox log level                      | {"log": {"level": "trace"}}                   | trace, debug, info, warn, error            |
+# | Firefox      | Set Firefox profile                        | {"profile": "/path/to/profile"}               | /path/to/profile                           |
+# | Firefox      | Set path to Firefox binary                 | {"binary": "/path/to/firefox"}                | /path/to/firefox                           |
+# | Edge         | Run Edge in headless mode                  | {"args": ["--headless"]}                      | --headless                                 |
+# | Edge         | Set path to Edge binary                    | {"binary": "/path/to/edge"}                   | /path/to/edge                              |
+# | Edge         | Use Chromium-based Edge                    | {"useChromium": true}                         | true, false                                |
+# | Edge         | Set Edge Chromium driver                   | {"edgeChromiumDriver": "/path/to/driver"}     | /path/to/driver                            |
+# | Chrome/Edge  | Set initial window size                    | {"args": ["--window-size=1920,1080"]}         | --window-size=int,int                      |
+# | Firefox      | Launch in private browsing mode            | {"args": ["-private"]}                        | -private                                   |
+# +--------------+--------------------------------------------+-----------------------------------------------+--------------------------------------------+
+
+
+class BaseSelenium(UIInteractions, WEInteractions):
+    """
+    Base class for Selenium-based browser automation.
+
+    This class provides common functionality for initializing and managing Selenium
+    WebDriver instances, as well as adding custom options to the WebDriver.
+
+    :param browser_options: Dictionary containing custom options for the WebDriver.
+    :param driver: Selenium WebDriver instance (optional, defaults to None).
+    """
+
+    def __init__(self, browser_options: dict = None):
+        self.browser_options = browser_options or {}
+        self.driver = None
+
+    def __enter__(self) -> "BaseSelenium":
+        self.driver = self._create_driver()
+        super().__init__(self.driver)
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        if exc_type:
+            logger.error(f"Exception occurred: {exc_type.__name__}: {exc_val}\nTraceback: {exc_tb}")
+        if self.driver:
+            self.driver.quit()
+
+    def _create_driver(self) -> webdriver:
+        """
+        Abstract method to create a Selenium WebDriver instance.
+
+        This method must be implemented by subclasses to instantiate and return
+        a specific browser WebDriver (e.g., Chrome, Firefox, Edge).
+
+        :return: Selenium WebDriver instance for the specified browser.
+        :raises: NotImplementedError
+        """
+
+        raise NotImplementedError("Subclasses must implement this method")
+
+    def _add_options(
+        self, options: ChromeOptions | FirefoxOptions | EdgeOptions
+    ) -> None:
+        """
+        Add custom options to the Selenium WebDriver.
+
+        This method applies custom options such as headless mode, download paths,
+        and command-line arguments to the WebDriver options.
+
+        :param options: ChromeOptions | FirefoxOptions | EdgeOptions
+        """
+
+        if not self.browser_options:
+            return
+
+        # Apply standard Selenium options
+        for key, value in self.browser_options.items():
+            if hasattr(options, key) and "args" not in key:
+                setattr(options, key, value)
+
+        # Apply command-line arguments
+        args = self.browser_options.get("args", [])
+        for arg in args:
+            options.add_argument(arg)
+
+        # Handle download path
+        download_path = self.browser_options.get("download_path")
+        if download_path:
+            if isinstance(options, FirefoxOptions):
+                options.set_preference("browser.download.folderList", 2)
+                options.set_preference("browser.download.dir", str(download_path))
+                options.set_preference(
+                    "browser.helperApps.neverAsk.saveToDisk", "application/octet-stream"
+                )
+            elif isinstance(options, (ChromeOptions, EdgeOptions)):
+                prefs = {
+                    "download.default_directory": str(download_path),
+                    "download.prompt_for_download": False,
+                    "directory_upgrade": True,
+                }
+                options.add_experimental_option("prefs", prefs)
+
+    def go_to(self, url: str | URL):
+        """Navigate to the specified URL.
+
+        :param url: The URL to navigate to.
+        :raises RuntimeError: If the WebDriver is not initialized.
+        """
+
+        if self.driver:
+            self.driver.get(str(url))
+        else:
+            raise RuntimeError("WebDriver is not initialized.")
+
+    def get_url(self) -> str:
+        """Get the current URL of the page.
+
+        :return: The current URL of the page.
+        :raises RuntimeError: If the WebDriver is not initialized.
+        """
+
+        if self.driver:
+            return self.driver.current_url
+        raise RuntimeError("WebDriver is not initialized.")
+
+    def get_title(self) -> str:
+        """Get the title of the current page.
+
+        :return: The title of the current page.
+        :raises RuntimeError: If the WebDriver is not initialized.
+        """
+
+        if self.driver:
+            return self.driver.title
+        raise RuntimeError("WebDriver is not initialized.")
+
+    def switch_to_window(
+        self, window_handle: Optional[str] = None
+    ) -> Optional[Dict[str, list]]:
+        """
+        Switches the browser context to a new window.
+
+        If a specific window handle is provided, the driver will switch to that window.
+        Otherwise, it will attempt to switch to a newly opened window that is different
+        from the current one.
+
+        :param window_handle: The handle of the window to switch to. If None, the method will search for a new window handle.
+        :return: A dictionary containing the original window handle, the new window handle, and a list of all window handles at the time of switching.
+        :raises RuntimeError: If the WebDriver is not initialized.
+        """
+
+        if window_handle:
+            self.driver.switch_to.window(window_handle)
+            return None
+
+        original_window = self.driver.current_window_handle
+        all_windows = self.driver.window_handles
+
+        for new_window in all_windows:
+            if new_window != original_window:
+                self.driver.switch_to.window(new_window)
+                return {
+                    "original_window": original_window,
+                    "new_window": new_window,
+                    "all_windows": all_windows,
+                }
+        return None
+
+    def close_window(self, window_handle: Optional[str] = None) -> None:
+        """
+        Closes the specified browser window.
+
+        If a window handle is provided, that window will be closed.
+        Otherwise, the currently active window will be closed.
+
+        :param window_handle: The handle of the window to close. If None, the current window will be closed.
+        """
+
+        self.driver.close(window_handle or self.driver.current_window_handle)
+
+
+class Firefox(BaseSelenium):
+    """
+    Class for Firefox browser automation using Selenium.
+
+    This class extends the BaseSelenium class and provides functionality for creating
+    and managing Firefox WebDriver instances.
+    """
+
+    def create_driver(self) -> webdriver.Firefox:
+        options = FirefoxOptions()
+        self._add_options(options)
+        return webdriver.Firefox(options=options)
+
+
+class Edge(BaseSelenium):
+    """
+    Class for Edge browser automation using Selenium.
+
+    This class extends the BaseSelenium class and provides functionality for creating
+    and managing Edge WebDriver instances.
+    """
+
+    def create_driver(self) -> webdriver.Edge:
+        options = EdgeOptions()
+        self._add_options(options)
+        return webdriver.Edge(options=options)
+
+
+class Chrome(BaseSelenium):
+    """
+    Class for Chrome browser automation using Selenium.
+
+    This class extends the BaseSelenium class and provides functionality for creating
+    and managing Chrome WebDriver instances.
+    """
+
+    def create_driver(self) -> webdriver.Chrome:
+        options = ChromeOptions()
+        self._add_options(options)
+        return webdriver.Chrome(options=options)
+
+
+class Browser(BaseSelenium):
+    """
+    Class for managing browser automation using Selenium.
+
+    This class provides functionality for initializing and managing browser instances
+    using the specified browser class and options.
+
+    It acts as a context manager, allowing for easy setup and teardown of browser sessions.
+
+    :param browser_class: The class of the browser to be used (e.g., Firefox, Edge, Chrome).
+    :param browser_options: Dictionary containing custom options for the browser.
+    """
+
+    def __init__(self, browser_class: type, browser_options: dict = None):
+        super().__init__(browser_options)
+        self.browser_class = browser_class
+        self.browser_options = browser_options or {}
+        self.browser_instance = None
+
+    def __enter__(self) -> BaseSelenium:
+        self.browser_instance = self.browser_class(self.browser_options)
+        self.browser_instance.driver = self.browser_instance.create_driver()
+        return self.browser_instance
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        if exc_type:
+            logger.error(f"Exception occurred: {exc_type.__name__}: {exc_val}\nTraceback: {exc_tb}")
+        if self.browser_instance and self.browser_instance.driver:
+            self.browser_instance.driver.quit()

wcp_library/browser_automation/interactions.py

@@ -0,0 +1,739 @@
+"""
+This module provides classes and methods for interacting with web elements using Selenium WebDriver.
+
+The module contains the following classes:
+- Interactions: A base class for common web interactions.
+- UIInteractions: A subclass of Interactions for interacting with web elements using locators.
+- WEInteractions: A subclass of Interactions for interacting with web elements directly.
+
+Each class provides methods for performing various web interactions such as navigating to a URL,
+taking screenshots, waiting for elements, clicking buttons, entering text, and more.
+"""
+
+import logging
+from datetime import datetime
+from io import StringIO
+from typing import List, Optional, Union
+
+import pandas as pd
+from selenium.common.exceptions import (
+    NoSuchElementException,
+    TimeoutException,
+    WebDriverException,
+)
+from selenium.webdriver.common.by import By
+from selenium.webdriver.remote.webelement import WebElement
+from selenium.webdriver.support import expected_conditions as EC
+from selenium.webdriver.support.ui import Select, WebDriverWait
+
+EXECUTION_ERROR_SCREENSHOT_FOLDER = "P:/Python/RPA/Execution Error Screenshots"
+
+
+class Interactions:
+    """Class for interacting with web elements using Selenium WebDriver.
+
+    Attributes:
+        driver: The Selenium WebDriver instance.
+    """
+
+    def __init__(self, driver):
+        self.driver = driver
+        logging.basicConfig(level=logging.INFO)
+
+    def take_screenshot(self, file_path: str):
+        """Take a screenshot of the current page and save it to the specified file path.
+
+        :param file_path: The path where the screenshot will be saved.
+        :raises RuntimeError: If the WebDriver is not initialized.
+        """
+
+        if self.driver:
+            self.driver.save_screenshot(file_path)
+        else:
+            raise RuntimeError("WebDriver is not initialized.")
+
+    def _take_error_screenshot(self) -> None:
+        """
+        Take a screenshot of the current page and save it to the P drive.
+
+        :return: None
+        :raises RuntimeError: If the WebDriver is not initialized.
+        """
+
+        self.take_screenshot(
+            f"{EXECUTION_ERROR_SCREENSHOT_FOLDER}/Failure Screenshot - {datetime.now().strftime('%Y-%m-%d_%H-%M')}.png"
+        )
+
+    def _get_expect_condition_multiple(self, expected_condition: Optional[str]) -> EC:
+        """Get the expected condition for multiple elements based on the provided string.
+
+        :param expected_condition: The expected condition type.
+        :return: The expected condition object for multiple elements.
+        :raises RuntimeError: If the WebDriver is not initialized.
+        """
+
+        return (
+            EC.presence_of_all_elements_located
+            if expected_condition == "present"
+            else EC.visibility_of_all_elements_located
+        )
+
+    def _get_wait_time(self, wait_time: float) -> float:
+        """If a wait time has been specified it is returned. Otherwise, the wait time comes from
+        the implicit timeout set when initializing the browser. That value is in milliseconds so
+        it is divided by 1000 (WebDriverWait expects a float number in seconds)
+
+        :param wait_time: The wait time in milliseconds.
+        :return: The wait time in seconds.
+        :raises RuntimeError: If the WebDriver is not initialized.
+        """
+
+        return (
+            wait_time
+            or (
+                getattr(self, "browser_options", {})
+                .get("timeouts", {})
+                .get("implicit", 0)
+            )
+            / 1000
+        )  # Timeouts are in ms
+
+
+class UIInteractions(Interactions):
+    """Class for interacting with UI elements using Selenium WebDriver."""
+
+    def _get_locator(self, locator: str) -> str:
+        """Get the locator type based on the provided string.
+
+        :param locator: The locator type.
+        :return: The locator type.
+        :raises RuntimeError: If the WebDriver is not initialized.
+        """
+
+        match locator:
+            case "id":
+                by = By.ID
+            case "name":
+                by = By.NAME
+            case "class":
+                by = By.CLASS_NAME
+            case "tag":
+                by = By.TAG_NAME
+            case "xpath":
+                by = By.XPATH
+            case "link_text":
+                by = By.LINK_TEXT
+            case "partial_link_text":
+                by = By.PARTIAL_LINK_TEXT
+            case _:
+                by = By.CSS_SELECTOR
+        return by
+
+    def _get_expected_condition(self, expected_condition: Optional[str]) -> EC:
+        """Get the expected condition based on the provided string.
+
+        :param expected_condition: The expected condition type.
+        :return: The expected condition object.
+        :raises RuntimeError: If the WebDriver is not initialized.
+        """
+
+        match expected_condition:
+            case "present":
+                expected_condition = EC.presence_of_element_located
+            case "visible":
+                expected_condition = EC.visibility_of_element_located
+            case "selected":
+                expected_condition = EC.element_located_to_be_selected
+            case "frame_available":
+                expected_condition = EC.frame_to_be_available_and_switch_to_it
+            case _:
+                expected_condition = EC.element_to_be_clickable
+        return expected_condition
+
+    def get_element(
+        self,
+        element_value: str,
+        locator: Optional[str] = None,
+        expected_condition: Optional[str] = None,
+        wait_time: Optional[float] = 0,
+    ) -> WebElement:
+        """Get a single WebElement based on the expected condition, locator, and element_value.
+
+        :param element_value: The expected element value.
+        :param locator: The locator type.
+            Options: 'css'(Default), 'id', 'name', 'class', 'tag',
+            'xpath', 'link_text', 'partial_link_text'
+        :param expected_condition: The expected condition type.
+            Options: 'clickable'(Default), 'present', 'visible',
+            'selected', 'frame_available'
+        :param wait_time: Time to wait for the condition.
+        :return: The located WebElement.
+        :raises RuntimeError: If the WebDriver is not initialized.
+        :raises TimeoutException: If the element is not found within the wait time.
+        :raises NoSuchElementException: If the element is not found.
+        :raises WebDriverException: If a WebDriverException occurs.
+        """
+
+        try:
+            return WebDriverWait(self.driver, self._get_wait_time(wait_time)).until(
+                self._get_expected_condition(expected_condition)(
+                    (self._get_locator(locator), element_value)
+                )
+            )
+        except TimeoutException as exc:
+            self._take_error_screenshot()
+            raise TimeoutException(
+                f"Timeout exception for element with locator {locator} and value {element_value}"
+            ) from exc
+        except NoSuchElementException as exc:
+            self._take_error_screenshot()
+            raise NoSuchElementException(
+                f"Element with locator {locator} and value {element_value} not found."
+            ) from exc
+        except WebDriverException as exc:
+            self._take_error_screenshot()
+            raise WebDriverException(f"WebDriverException occurred: {exc}") from exc
+
+    def get_multiple_elements(
+        self,
+        element_value: str,
+        locator: Optional[str] = None,
+        expected_condition: Optional[str] = None,
+        wait_time: Optional[float] = 0,
+    ) -> List[WebElement]:
+        """Get a list of WebElements based on the expected condition, locator, and element_value.
+
+        :param element_value: The expected element value.
+        :param locator: The locator type.
+            Options: 'css'(Default), 'id', 'name', 'class', 'tag',
+            'xpath', 'link_text', 'partial_link_text'
+        :param expected_condition: The expected condition type.
+            Options: 'clickable'(Default), 'present', 'visible',
+            'selected', 'frame_available'
+        :param wait_time: Time to wait for the condition.
+        :return: A list of located WebElements.
+        :raises RuntimeError: If the WebDriver is not initialized.
+        :raises TimeoutException: If the elements are not found within the wait time.
+        :raises NoSuchElementException: If the elements are not found.
+        :raises WebDriverException: If a WebDriverException occurs.
+        """
+
+        try:
+            return WebDriverWait(self.driver, self._get_wait_time(wait_time)).until(
+                self._get_expect_condition_multiple(expected_condition)(
+                    (self._get_locator(locator), element_value)
+                )
+            )
+        except TimeoutException as exc:
+            self._take_error_screenshot()
+            raise TimeoutException(
+                f"Timeout exception for element with locator {locator} and value {element_value} not found."
+            ) from exc
+        except NoSuchElementException as exc:
+            self._take_error_screenshot()
+            raise NoSuchElementException(
+                f"Element with locator {locator} and value {element_value} not found."
+            ) from exc
+        except WebDriverException as exc:
+            self._take_error_screenshot()
+            raise WebDriverException(f"WebDriverException occurred: {exc}") from exc
+
+    def get_text(
+        self,
+        element_value: str,
+        locator: Optional[str] = None,
+        expected_condition: Optional[str] = None,
+    ) -> str:
+        """Get the text of the WebElement based on the locator and expected condition.
+
+        :param element_value: The value used to identify the element.
+        :param locator: The locator type.
+            Options: 'css'(Default), 'id', 'name', 'class', 'tag',
+            'xpath', 'link_text', 'partial_link_text'
+        :param expected_condition: The expected condition type.
+            Options: 'clickable'(Default), 'present', 'visible',
+            'selected', 'frame_available'
+        :return: The text of the located WebElement.
+        :raises RuntimeError: If the WebDriver is not initialized.
+        """
+
+        return self.get_element(element_value, locator, expected_condition).text
+
+    def get_table(
+        self,
+        element_value: str,
+        locator: Optional[str] = None,
+        expected_condition: Optional[str] = None,
+    ) -> pd.DataFrame:
+        """Get the data from a table element.
+
+        :param element_value: The value used to identify the element.
+        :param locator: The locator type.
+            Options: 'css'(Default), 'id', 'name', 'class', 'tag',
+            'xpath', 'link_text', 'partial_link_text'
+        :param expected_condition: The expected condition type.
+            Options: 'clickable'(Default), 'present', 'visible',
+            'selected', 'frame_available'
+        :return: The data from the table element.
+        :raises RuntimeError: If the WebDriver is not initialized.
+        """
+
+        element = self.get_element(element_value, locator, expected_condition)
+        return pd.read_html(StringIO(element.get_attribute("outerHTML")))[0]
+
+    def get_value(
+        self,
+        element_value: str,
+        locator: Optional[str] = None,
+        expected_condition: Optional[str] = None,
+    ) -> str:
+        """Get the value attribute of the WebElement based on the locator and expected condition.
+
+        :param element_value: The value used to identify the element.
+        :param locator: The locator type.
+            Options: 'css'(Default), 'id', 'name', 'class', 'tag',
+            'xpath', 'link_text', 'partial_link_text'
+        :param expected_condition: The expected condition type.
+            Options: 'clickable'(Default), 'present', 'visible',
+            'selected', 'frame_available'
+        :return: The value of the located WebElement.
+        :raises RuntimeError: If the WebDriver is not initialized.
+        """
+
+        return self.get_element(
+            element_value, locator, expected_condition
+        ).get_attribute("value")
+
+    def press_button(
+        self,
+        element_value: str,
+        locator: Optional[str] = None,
+        expected_condition: Optional[str] = None,
+    ) -> None:
+        """Click on the WebElement based on the locator and expected condition.
+
+        :param element_value: The value used to identify the element.
+        :param locator: The locator type.
+            Options: 'css'(Default), 'id', 'name', 'class', 'tag',
+            'xpath', 'link_text', 'partial_link_text'
+        :param expected_condition: The expected condition type.
+            Options: 'clickable'(Default), 'present', 'visible',
+            'selected', 'frame_available'
+        :return:
+        :raises RuntimeError: If the WebDriver is not initialized.
+        """
+
+        element = self.get_element(element_value, locator, expected_condition)
+        element.click()
+
+    def enter_text(
+        self,
+        text: str,
+        element_value: str,
+        locator: Optional[str] = None,
+        expected_condition: Optional[str] = None,
+    ) -> None:
+        """Populate the text field with the provided text.
+
+        :param text: The text to enter.
+        :param element_value: The value used to identify the element.
+        :param locator: The locator type.
+            Options: 'css'(Default), 'id', 'name', 'class', 'tag',
+            'xpath', 'link_text', 'partial_link_text'
+        :param expected_condition: The expected condition type.
+            Options: 'clickable'(Default), 'present', 'visible',
+            'selected', 'frame_available'
+        :return:
+        :raises RuntimeError: If the WebDriver is not initialized.
+        """
+
+        element = self.get_element(element_value, locator, expected_condition)
+        element.clear()
+        element.send_keys(text)
+
+    def set_checkbox_state(
+        self,
+        state: bool,
+        element_value: str,
+        locator: Optional[str] = None,
+        expected_condition: Optional[str] = None,
+    ) -> None:
+        """Set the state of a checkbox.
+
+        :param state: The state to set.
+        :param element_value: The value used to identify the element.
+        :param locator: The locator type.
+            Options: 'css'(Default), 'id', 'name', 'class', 'tag',
+            'xpath', 'link_text', 'partial_link_text'
+        :param expected_condition: The expected condition type.
+            Options: 'clickable'(Default), 'present', 'visible',
+            'selected', 'frame_available'
+        :return:
+        :raises RuntimeError: If the WebDriver is not initialized.
+        """
+
+        element = self.get_element(element_value, locator, expected_condition)
+        if element.is_selected() != state:
+            element.click()
+
+    def set_select_option(
+        self,
+        option: str,
+        element_value: str,
+        select_type: str = None,
+        locator: Optional[str] = None,
+        expected_condition: Optional[str] = None,
+    ) -> None:
+        """Select an option from a dropdown.
+
+        :param option: The option to select. This can be the visible text,
+        :param element_value: The value used to identify the element.
+        :param select_type: The type of selection to perform.
+        :param locator: The locator type.
+            Options: 'css'(Default), 'id', 'name', 'class', 'tag',
+            'xpath', 'link_text', 'partial_link_text'
+        :param expected_condition: The expected condition type.
+            Options: 'clickable'(Default), 'present', 'visible',
+            'selected', 'frame_available'
+        :return:
+        :raises RuntimeError: If the WebDriver is not initialized.
+        """
+
+        element = self.get_element(element_value, locator, expected_condition)
+        select = Select(element)
+        if select_type == "index":
+            select.select_by_index(int(option))
+        elif select_type == "visible_text":
+            select.select_by_visible_text(option)
+        else:
+            select.select_by_value(option)
+
+    def web_page_contains(
+        self,
+        element_value: str,
+        locator: Optional[str] = None,
+        expected_condition: Optional[str] = None,
+        wait_time: Optional[float] = 0,
+    ) -> Union[WebElement, bool]:
+        """
+        Determine whether a web element is present on the page based on
+        the provided locator and expected condition.
+
+        :param element_value: The value used to identify the element.
+        :param locator: The locator type.
+            Options: 'css'(Default), 'id', 'name', 'class', 'tag',
+            'xpath', 'link_text', 'partial_link_text'
+        :param expected_condition: The expected condition type.
+            Options: 'clickable'(Default), 'present', 'visible',
+            'selected', 'frame_available'
+        :param wait_time: Time to wait for the condition.
+        :return: The located WebElement if found; otherwise, False if the element is not present
+        or an exception occurs.
+        :raises RuntimeError: If the WebDriver is not initialized.
+        """
+
+        try:
+            return self.get_element(
+                element_value, locator, expected_condition, wait_time
+            )
+        except (TimeoutException, NoSuchElementException):
+            return False
+
+    def text_is_present(
+        self,
+        text: str,
+        element_value: str,
+        locator: Optional[str] = None,
+        text_location: Optional[str] = None,
+        wait_time: Optional[float] = 0,
+    ) -> bool:
+        """
+        Checks whether the specified text is present within a web element.
+
+        :param text: The text to verify within the element.
+        :param element_value: The value used to identify the element.
+        :param locator: The locator type.
+            Options: 'css'(Default), 'id', 'name', 'class', 'tag',
+            'xpath', 'link_text', 'partial_link_text'
+        :param text_location: Where in the element to look for the text.
+            Options: 'anywhere'(Default), 'attribute', 'value'
+        :param wait_time: Time to wait for the condition.
+        :return: True if the text is found within the element, False otherwise.
+        :raises RuntimeError: If the WebDriver is not initialized.
+        """
+
+        expected_condition = EC.text_to_be_present_in_element
+        if text_location == "attribute":
+            expected_condition = EC.text_to_be_present_in_element_attribute
+        elif text_location == "value":
+            expected_condition = EC.text_to_be_present_in_element_value
+
+        return WebDriverWait(self.driver, self._get_wait_time(wait_time)).until(
+            expected_condition((self._get_locator(locator), element_value), text)
+        )
+
+    def wait_for_element(
+        self,
+        element_value: str,
+        locator: Optional[str] = None,
+        expected_condition: Optional[str] = None,
+        wait_time: Optional[float] = 0,
+    ) -> WebElement:
+        """
+        Wait for an element to be present based on the locator and expected condition.
+
+        :param element_value: The value used to identify the element.
+        :param locator: The locator type.
+            Options: 'css'(Default), 'id', 'name', 'class', 'tag',
+            'xpath', 'link_text', 'partial_link_text'
+        :param expected_condition: The expected condition type.
+            Options: 'clickable'(Default), 'present', 'visible',
+            'selected', 'frame_available'
+        :param wait_time: Time to wait for the element.
+        :return: The located WebElement.
+        :raises RuntimeError: If the WebDriver is not initialized.
+        """
+
+        return self.get_element(
+            element_value, locator, expected_condition, self._get_wait_time(wait_time)
+        )
+
+
+class WEInteractions(Interactions):
+    """Class for interacting with web elements directly using WebElement instances."""
+
+    def _get_expected_condition_we(self, expected_condition: Optional[str] = None):
+        """
+        Return an expected condition that accepts a WebElement.
+
+        :param expected_condition: The expected condition type.
+            Options: 'clickable'(Default), 'visible', 'selected', 'staleness'
+        :return: A Selenium expected condition function.
+        :raises RuntimeError: If the WebDriver is not initialized.
+        """
+
+        match expected_condition:
+            case "visible":
+                expected_condition = EC.visibility_of
+            case "invisible":
+                expected_condition = EC.invisibility_of_element
+            case "selected":
+                expected_condition = EC.element_to_be_selected
+            case "staleness":
+                expected_condition = EC.staleness_of
+            case _:
+                expected_condition = EC.element_to_be_clickable
+        return expected_condition
+
+    def wait_for_element_we(
+        self,
+        web_element: WebElement,
+        expected_condition: Optional[str] = None,
+        wait_time: Optional[float] = 0,
+    ) -> WebElement:
+        """
+        Wait for an element to be present directly using WebElement and expected condition.
+
+        :param web_element: The WebElement to wait for.
+        :param expected_condition: The expected condition type.
+            Options: 'clickable'(Default), 'visible', 'selected', 'staleness'
+        :param wait_time: Time to wait for the element.
+        :return: The WebElement if it meets the expected condition.
+        :raises RuntimeError: If the WebDriver is not initialized.
+        """
+
+        condition = self._get_expected_condition_we(expected_condition)
+        WebDriverWait(self.driver, self._get_wait_time(wait_time)).until(
+            condition(web_element)
+        )
+        return web_element
+
+    def get_text_we(
+        self,
+        web_element: WebElement,
+        expected_condition: Optional[str] = None,
+        wait_time: Optional[float] = 0,
+    ) -> str:
+        """
+        Get the text of the WebElement directly.
+
+        :param web_element: The WebElement to get text from.
+        :param expected_condition: The expected condition type.
+            Options: 'clickable'(Default), 'visible', 'selected', 'staleness'
+        :param wait_time: Time to wait for the element.
+        :return: The text of the WebElement.
+        :raises RuntimeError: If the WebDriver is not initialized.
+        """
+
+        web_element = self.wait_for_element_we(
+            web_element, expected_condition, wait_time
+        )
+        return web_element.text
+
+    def get_table_we(
+        self,
+        web_element: WebElement,
+        expected_condition: Optional[str] = None,
+        wait_time: Optional[float] = 0,
+    ) -> pd.DataFrame:
+        """
+        Get the data from a table element directly.
+
+        :param web_element: The WebElement representing the table.
+        :param expected_condition: The expected condition type.
+            Options: 'clickable'(Default), 'visible', 'selected', 'staleness'
+        :param wait_time: Time to wait for the element.
+        :return: A DataFrame containing the table data.
+        :raises RuntimeError: If the WebDriver is not initialized.
+        """
+
+        web_element = self.wait_for_element_we(
+            web_element, expected_condition, wait_time
+        )
+        return pd.read_html(StringIO(web_element.get_attribute("outerHTML")))[0]
+
+    def get_value_we(
+        self,
+        web_element: WebElement,
+        expected_condition: Optional[str] = None,
+        wait_time: Optional[float] = 0,
+    ) -> str:
+        """
+        Get the value attribute of the WebElement directly.
+
+        :param web_element: The WebElement to get value from.
+        :param expected_condition: The expected condition type.
+            Options: 'clickable'(Default), 'visible', 'selected', 'staleness'
+        :param wait_time: Time to wait for the element.
+        :return: The value attribute of the WebElement.
+        :raises RuntimeError: If the WebDriver is not initialized.
+        """
+
+        web_element = self.wait_for_element_we(
+            web_element, expected_condition, wait_time
+        )
+        return web_element.get_attribute("value")
+
+    def press_button_we(
+        self,
+        web_element: WebElement,
+        expected_condition: Optional[str] = None,
+        wait_time: Optional[float] = 0,
+    ) -> None:
+        """Click on the WebElement directly.
+
+        :param web_element: The WebElement to click.
+        :param expected_condition: The expected condition type.
+            Options: 'clickable'(Default), 'visible', 'selected', 'staleness'
+        :param wait_time: Time to wait for the element.
+        :raises RuntimeError: If the WebDriver is not initialized.
+        """
+
+        web_element = self.wait_for_element_we(
+            web_element, expected_condition, wait_time
+        )
+        web_element.click()
+
+    def enter_text_we(
+        self,
+        text: str,
+        web_element: WebElement,
+        expected_condition: Optional[str] = None,
+        wait_time: Optional[float] = 0,
+    ) -> None:
+        """Populate the text field with the provided text directly.
+
+        :param text: The text to enter.
+        :param web_element: The WebElement to populate.
+        :param expected_condition: The expected condition type.
+            Options: 'clickable'(Default), 'visible', 'selected', 'staleness'
+        :param wait_time: Time to wait for the element.
+        :raises RuntimeError: If the WebDriver is not initialized.
+        """
+
+        web_element = self.wait_for_element_we(
+            web_element, expected_condition, wait_time
+        )
+        web_element.clear()
+        web_element.send_keys(text)
+
+    def set_checkbox_state_we(
+        self,
+        state: bool,
+        web_element: WebElement,
+        expected_condition: Optional[str] = None,
+        wait_time: Optional[float] = 0,
+    ) -> None:
+        """Set the state of a checkbox directly.
+
+        :param state: The state to set. True to check the checkbox, False to uncheck it.
+        :param web_element: The WebElement representing the checkbox.
+        :param expected_condition: The expected condition type.
+            Options: 'clickable'(Default), 'visible', 'selected', 'staleness'
+        :param wait_time: Time to wait for the element.
+        :raises RuntimeError: If the WebDriver is not initialized.
+        """
+
+        web_element = self.wait_for_element_we(
+            web_element, expected_condition, wait_time
+        )
+        if web_element.is_selected() != state:
+            web_element.click()
+
+    def set_select_option_we(
+        self,
+        option: str,
+        web_element: WebElement,
+        select_type: str = None,
+        expected_condition: Optional[str] = None,
+        wait_time: Optional[float] = 0,
+    ) -> None:
+        """Select an option from a dropdown directly.
+
+        :param option: The option to select.
+            This can be the visible text, index, or value of the option.
+            Default is by value.
+        :param web_element: The WebElement representing the dropdown.
+        :param select_type: The type of selection to perform.
+            Options: 'value' (default), 'index', 'visible_text'
+        :param expected_condition: The expected condition type.
+            Options: 'clickable'(Default), 'visible', 'selected', 'staleness'
+        :param wait_time: Time to wait for the element.
+        :raises RuntimeError: If the WebDriver is not initialized.
+        """
+
+        web_element = self.wait_for_element_we(
+            web_element, expected_condition, wait_time
+        )
+        select = Select(web_element)
+        if select_type == "index":
+            select.select_by_index(int(option))
+        elif select_type == "visible_text":
+            select.select_by_visible_text(option)
+        else:
+            select.select_by_value(option)
+
+    def web_page_contains_we(
+        self,
+        web_element: WebElement,
+        expected_condition: Optional[str] = None,
+        wait_time: Optional[float] = 0,
+    ) -> WebElement | bool:
+        """Check if the web page contains an element directly using WebElement
+        and expected condition.
+
+        :param web_element: The WebElement to check.
+        :param expected_condition: The expected condition type.
+            Options: 'clickable'(Default), 'visible', 'selected', 'staleness'
+        :param wait_time: Time to wait for the condition.
+        :return: The located WebElement if found; otherwise, False if the element is not present
+        or an exception occurs.
+        :raises RuntimeError: If the WebDriver is not initialized.
+        """
+
+        try:
+            return self.wait_for_element_we(
+                web_element, expected_condition, self._get_wait_time(wait_time)
+            )
+        except (TimeoutException, NoSuchElementException):
+            return False

wcp_library/emailing.py

@@ -32,6 +32,31 @@ def send_email(sender: str, recipients: list, subject: str, message: str=None) -
     server.quit()
 
 
+def send_html_email(sender: str, recipients: list, subject: str, html_content: str) -> None:
+    """
+    Function to send an HTML email
+
+    :param sender:
+    :param recipients:
+    :param subject:
+    :param html_content:
+    :return:
+    """
+
+    msg = MIMEMultipart('alternative')
+    msg['From'] = sender
+    msg['To'] = ", ".join(recipients)
+    msg['Date'] = formatdate(localtime=True)
+    msg['Subject'] = subject
+    msg.attach(MIMEText(html_content, 'html'))
+
+    smtpServer = 'mail.wcap.ca'
+    server = smtplib.SMTP(smtpServer, 25)
+    server.ehlo()
+    server.sendmail(sender, recipients, msg.as_string())
+    server.quit()
+
+
 def email_reporting(subject: str, message: str) -> None:
     """
     Function to email the reporting team from the Python email

{wcp_library-1.6.3.dist-info → wcp_library-1.6.5.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: wcp-library
-Version: 1.6.3
+Version: 1.6.5
 Summary: Common utilites for internal development at WCP
 Author: Mitch-Petersen
 Author-email: mitch.petersen@wcap.ca

{wcp_library-1.6.3.dist-info → wcp_library-1.6.5.dist-info}/RECORD

@@ -1,4 +1,7 @@
-wcp_library/__init__.py,sha256=bdNwVRQugYLeKlJFj3kE0U1LvqlK1O0k8CjF-_xqrEE,625
+wcp_library/__init__.py,sha256=kfv5jNFXKn_iHjGUOp_UDtqAFiogpVRcn4Tpmkho52o,4242
+wcp_library/browser_automation/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+wcp_library/browser_automation/browser.py,sha256=06xKu_lLifRzfj1TBlpZmKUeBoMqa7ye8kj0Aoy27uI,14551
+wcp_library/browser_automation/interactions.py,sha256=YTYyII81M9qoVU_iYXoF5vHCc1PSj60hStPU-nT-qyA,28941
 wcp_library/credentials/__init__.py,sha256=cfClJuFs9E3o_-5IPSKVJrkhQTiC3S2HhnZdrab9L6U,1856
 wcp_library/credentials/_credential_manager_asynchronous.py,sha256=A7OJkBsNJ5fzNKoMih8GyLCIQytLViQgwccOrtdBOL8,6392
 wcp_library/credentials/_credential_manager_synchronous.py,sha256=QUF3OOUgx0gu2PKFykkB69C-Kf_-9lyo2RIVA2JYvyc,5764
@@ -7,7 +10,7 @@ wcp_library/credentials/ftp.py,sha256=lSjOlfU68j9PsOCaoWJSdjbR1QmjTxjVmSxOpMdMG7
 wcp_library/credentials/internet.py,sha256=z9tihFddTJcX2pt-iHFP_rkCoheLhTdFgn4ksc2sYYE,2239
 wcp_library/credentials/oracle.py,sha256=OV02op95LNUT21cNDM4zDbD63C1ldiq--vYofDpU-zU,2869
 wcp_library/credentials/postgres.py,sha256=B5qNPKYzuzOJZ5S4M3MCN4xUelvZ6AgyR6QJc4z0Cgo,2573
-wcp_library/emailing.py,sha256=xqNly6Tmj-pvwl5bdys3gauZFDd4SuWCQYzGFNemv2Q,2496
+wcp_library/emailing.py,sha256=g6g9ZHIMBq6fzUFEjhB54WnJOj0cZFVbjLsB29zAVlY,3135
 wcp_library/ftp/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 wcp_library/ftp/ftp.py,sha256=Zg8WMYfzUGnpqimLjtCuKyrtNGtv0Syupgi-rh_al00,3985
 wcp_library/ftp/sftp.py,sha256=hykXGLGdxe7DYAxFdTwjPjTEOYuIpSMyK3NOiTQNUK0,4176
@@ -20,6 +23,6 @@ wcp_library/sql/__init__.py,sha256=f0JyVyFyUjueQ1XdVmCgmRjzkFENmFKl3BOzrvv3i1I,2
 wcp_library/sql/oracle.py,sha256=GpqUn7srm4mGxeJAU06tHaMR37zxASSdMZJ3h8KTC-U,19240
 wcp_library/sql/postgres.py,sha256=cLOurfmad3WqJcE7FiSxUyzo_0patpfMcTfQAoiteuU,18525
 wcp_library/time.py,sha256=ktSzhK7SZnGPNXobFexnhFGQAcriLCJQKxnO0fed8fQ,1740
-wcp_library-1.6.3.dist-info/METADATA,sha256=gxtA32HYQk2IqRVKtnTLOQS3WDJvxP_5-HWNCVg2whw,1393
-wcp_library-1.6.3.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
-wcp_library-1.6.3.dist-info/RECORD,,
+wcp_library-1.6.5.dist-info/METADATA,sha256=CzgY0bCG4iFsZJhG4Y6Ff2mIaEgJX8QXmBqFqGtO988,1393
+wcp_library-1.6.5.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
+wcp_library-1.6.5.dist-info/RECORD,,