selmate 1.0.0__py3-none-any.whl

selmate/utils.py

@@ -0,0 +1,165 @@
+import math
+import random
+import re
+from typing import Tuple, List, Optional
+from urllib.parse import urlparse, urlunparse, urljoin
+
+from rapidfuzz import fuzz
+
+from selmate.constants import WHITESPACE_PATTERN, CONFIRMATIONS
+
+
+def normalize_url(href, base_url, save_query=True, save_fragment=False, save_params=False):
+    """Normalizes a URL relative to a base URL.
+    :param href: The URL to normalize.
+    :param base_url: The base URL for relative URLs.
+    :param save_query: Whether to keep the query string.
+    :param save_fragment: Whether to keep the fragment.
+    :param save_params: Whether to keep URL parameters.
+    :return: The normalized URL or None if invalid.
+    """
+    href = href.strip()
+    if not href:
+        return None
+
+    parsed_base = urlparse(base_url)
+    if not parsed_base.scheme:
+        base_url = 'https://' + base_url.lstrip('/')
+        parsed_base = urlparse(base_url)
+
+    parsed_href = urlparse(href)
+    if parsed_href.scheme:
+        absolute_url = href
+    else:
+        if href.startswith('//'):
+            href = parsed_base.scheme + ':' + href
+        absolute_url = urljoin(base_url, href)
+
+    parsed_url = urlparse(absolute_url)
+    if not parsed_url.scheme or not parsed_url.netloc:
+        return None
+
+    cleaned_url = urlunparse((
+        parsed_url.scheme,
+        parsed_url.netloc,
+        parsed_url.path,
+        parsed_url.params if save_params else '',
+        parsed_url.query if save_query else '',
+        parsed_url.fragment if save_fragment else ''
+    ))
+
+    return cleaned_url
+
+
+def is_webpage(url):
+    """Checks if a URL points to a webpage.
+    :param url: The URL to check.
+    :return: True if the URL is a webpage, False otherwise.
+    """
+    webpage_extensions = (
+        '.html', '.htm', '.php', '.asp', '.aspx', '.jsp', '.jspx',
+        '.shtml', '.cfm', '.pl', '.py', '.erb', '.rhtml', '.do',
+        '.action', '.cshtml', '.vbhtml', '.phtml', '.cfc', '.ghtml'
+    )
+
+    parsed_url = urlparse(url)
+    path = parsed_url.path.lower()
+
+    if not path or path.endswith('/'):
+        return True
+
+    if path.endswith(webpage_extensions):
+        return True
+
+    last_segment = path.split('/')[-1]
+    if '.' in last_segment:
+        return False
+
+    return True
+
+
+def is_confirmation_text(text, threshold=0.75) -> Optional[float]:
+    """Determines if text resembles a confirmation action.
+    :param text: The text to check.
+    :param threshold: Similarity threshold for confirmation.
+    :return: Similarity score if above threshold, None otherwise.
+    """
+    max_sim = None
+    for confirmation in CONFIRMATIONS:
+        sim = fuzz.ratio(confirmation, text, processor=norm_string) / 100
+        if sim < threshold:
+            continue
+
+        if max_sim is None or sim > max_sim:
+            max_sim = sim
+
+    return max_sim
+
+
+def latency_time(min_time, max_time):
+    """Generates a random latency time within a range.
+    :param min_time: Minimum latency time.
+    :param max_time: Maximum latency time.
+    :return: Random latency time.
+    """
+    return random.uniform(min_time, max_time)
+
+
+def norm_string(s):
+    """Normalizes a string by stripping and lowercasing.
+    :param s: The string to normalize.
+    :return: Normalized string.
+    """
+    s = s.strip().lower()
+    return re.sub(WHITESPACE_PATTERN, ' ', s)
+
+
+def generate_parabolic_path(x1, y1, x2, y2, step_length=10.0) -> List[Tuple[float, float]]:
+    """Generates a parabolic path between two points.
+    :param x1: Starting x-coordinate.
+    :param y1: Starting y-coordinate.
+    :param x2: Ending x-coordinate.
+    :param y2: Ending y-coordinate.
+    :param step_length: Length of each step.
+    :return: List of (x, y) coordinates.
+    """
+    dist = math.sqrt((x1 - x2) ** 2 + (y1 - y2) ** 2) * math.pi / 1.5
+    steps = math.ceil(dist / step_length)
+    path = []
+    for i in range(steps + 1):
+        t = i / steps
+        x = x1 + (x2 - x1) * t
+        y_offset = steps * 4 * t * (1 - t)
+        y = y1 + (y2 - y1) * t + y_offset
+        path.append((x, y))
+    return path
+
+
+def generate_curved_path(x1, y1, x2, y2, step_length=10.0):
+    """Generates a curved path between two points.
+    :param x1: Starting x-coordinate.
+    :param y1: Starting y-coordinate.
+    :param x2: Ending x-coordinate.
+    :param y2: Ending y-coordinate.
+    :param step_length: Length of each step.
+    :return: List of (x, y) coordinates.
+    """
+    points = [(x1, y1)]
+
+    dx = x2 - x1
+    total_dist = ((x2 - x1) ** 2 + (y2 - y1) ** 2) ** 0.5
+
+    num_steps = max(1, int(total_dist / step_length))
+    height = abs(y2 - y1) * 0.5 + 0.5
+
+    for i in range(1, num_steps):
+        t = i / num_steps
+        x = x1 + t * dx
+        arc = height * (1 - ((2 * t - 1) ** 2))
+        y = y1 + t * (y2 - y1) + arc
+
+        points.append((x, y))
+
+    points.append((x2, y2))
+
+    return points

selmate-1.0.0.dist-info/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 FINWAX
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

selmate-1.0.0.dist-info/METADATA

@@ -0,0 +1,133 @@
+Metadata-Version: 2.3
+Name: selmate
+Version: 1.0.0
+Summary: 
+License: MIT License
+         
+         Copyright (c) 2025 FINWAX
+         
+         Permission is hereby granted, free of charge, to any person obtaining a copy
+         of this software and associated documentation files (the "Software"), to deal
+         in the Software without restriction, including without limitation the rights
+         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+         copies of the Software, and to permit persons to whom the Software is
+         furnished to do so, subject to the following conditions:
+         
+         The above copyright notice and this permission notice shall be included in all
+         copies or substantial portions of the Software.
+         
+         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+         SOFTWARE.
+Author: FINWAX
+Author-email: waxbid@gmail.com
+Requires-Python: >=3.10
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: beautifulsoup4 (>=4.13.4,<5.0.0)
+Requires-Dist: lxml (>=5.4.0,<6.0.0)
+Requires-Dist: rapidfuzz (>=3.13.0,<4.0.0)
+Requires-Dist: selenium (>=4.33.0,<5.0.0)
+Description-Content-Type: text/markdown
+
+# Selmate
+
+Selmate is a Python utility library designed to enhance Selenium WebDriver automation by providing human-like
+interactions, robust exception handling, and utilities for common web automation tasks. It simplifies interactions with
+web elements, handles popups, normalizes URLs, and simulates natural user behavior like mouse movements and scrolling.
+
+## Features
+
+- **Safe Element Interactions**: Wrappers for Selenium operations (clicks, scrolls, etc.) with built-in exception
+  handling for stale elements, timeouts, and more.
+- **Human-Like Behavior**: Simulates realistic mouse movements, scrolling, and latency to mimic human interactions.
+- **Popup Handling**: Automatically detects and handles popup banners, including those within iframes, with options to
+  accept or close them.
+- **URL Normalization**: Utilities to normalize URLs relative to a base URL, with configurable handling of query
+  strings, fragments, and parameters.
+- **JavaScript Integration**: Execute JavaScript for advanced interactions like smooth scrolling, element removal, and
+  visibility checks.
+- **Text Similarity**: Identify confirmation buttons or close buttons using fuzzy text matching.
+
+## Installation
+
+Install Selmate via pip:
+
+```bash
+pip install selmate
+```
+
+## Usage
+
+Here are some examples of using Selmate's core functionalities:
+
+### Example 1: Safe Element Click
+
+```python
+from selenium import webdriver
+from selmate.composites import complex_click
+from selmate.selenium_primitives import find_element_safely
+from selenium.webdriver.common.by import By
+
+driver = webdriver.Chrome()
+driver.get("https://example.com")
+
+# Safely find and click a button
+button = find_element_safely(By.ID, "submit-button", driver)
+if button and complex_click(button, driver):
+    print("Button clicked successfully")
+
+driver.quit()
+```
+
+### Example 2: Handling Popup Banners
+
+```python
+from selenium import webdriver
+from selmate.composites import bypass_popup_banners
+
+driver = webdriver.Chrome()
+driver.get("https://example.com")
+
+# Automatically handle popup banners
+bypass_popup_banners(driver, observation_capacity=50, success_capacity=3, try_close=True)
+print("Popups handled")
+
+driver.quit()
+```
+
+### Example 3: Human-Like Mouse Movement
+
+```python
+from selenium import webdriver
+from selmate.composites import wander_between_2_elements
+from selmate.selenium_primitives import find_element_safely
+from selenium.webdriver.common.by import By
+
+driver = webdriver.Chrome()
+driver.get("https://example.com")
+
+# Find two elements and simulate mouse movement between them
+element1 = find_element_safely(By.ID, "element1", driver)
+element2 = find_element_safely(By.ID, "element2", driver)
+if element1 and element2:
+    wander_between_2_elements(element1, element2, driver)
+
+driver.quit()
+```
+
+## License
+
+Selmate is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
+
+## Contact
+
+For questions or support, open an issue or contact the maintainer at waxbid@gmail.com.

selmate-1.0.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+selmate/__init__.py,sha256=ndpiwSMdcqh1TZO1pEdZ-pIzngdSoa-cXIhHeJxAeRw,79
+selmate/composites.py,sha256=gIgFTu0TGExmlS0ptN-NRYPhizf8O8ROZSFkkL3yi8U,25442
+selmate/constants.py,sha256=8ZeIZ0v_lWx7_-lN0rYlTNnOCj2zMih1ePQVgtKUsp4,6978
+selmate/humanity/constants.py,sha256=YYRtMlLapqm1DBCuhdJHFH1Hq4bDSgeXMcpbX-uedoA,234
+selmate/humanity/latency.py,sha256=xJ2JWtmgxmkqDsTvCMihmuM3KKVP8Crf2YaH2LP7qEs,1263
+selmate/js_primitives.py,sha256=4-etOV4ftYwPE9hAOkyS84W19mjzcjYE7enpwdeESEo,6158
+selmate/safe_exceptions.py,sha256=L2RPD6TSHCIMsyYxiSHbS0EzCaXsyavUi4NvZZqXf7w,1425
+selmate/selenium_primitives.py,sha256=hKYPFtQCOSuNt3_S1U2Ce9sDhtFe5bhvHwgMChRuUdE,2667
+selmate/utils.py,sha256=NWImi_DuM9JmsN1E8br2YjCMaWte-mdFbWAPuFHObsY,5012
+selmate-1.0.0.dist-info/LICENSE,sha256=7Ivo3S2GrdGr_wc98qnPyERQMV4wxZULNMzgk09S758,1082
+selmate-1.0.0.dist-info/METADATA,sha256=yn7YjRHTIcZANF1cEetSBwzZ0OowU6y6gLXmyoNbHvY,4878
+selmate-1.0.0.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
+selmate-1.0.0.dist-info/RECORD,,

selmate-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.1.3
+Root-Is-Purelib: true
+Tag: py3-none-any