pydoll-python 2.12.3__tar.gz → 2.13.0__tar.gz

{pydoll_python-2.12.3 → pydoll_python-2.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pydoll-python
-Version: 2.12.3
+Version: 2.13.0
 Summary: Pydoll is a library for automating chromium-based browsers without a WebDriver, offering realistic interactions.
 License-File: LICENSE
 Author: Thalison Fernandes
@@ -59,6 +59,56 @@ pip install pydoll-python
 ```
 That's it. No `webdrivers`. No external dependencies.
 
+<details>
+<summary><b>🆕 What's New</b></summary>
+<br>
+
+### Humanized Keyboard Input (`humanize=True`)
+
+Pydoll now includes a **humanized typing engine** that simulates realistic human typing behavior:
+
+- **Variable keystroke timing**: 30-120ms between keys (not fixed intervals)
+- **Realistic typos**: ~2% error rate with automatic correction behavior
+- **No more `interval` parameter**: Just use `humanize=True` for anti-bot evasion
+
+```python
+# Old way (detectable)
+await element.type_text("hello", interval=0.1)
+
+# New way (human-like, anti-bot)
+await element.type_text("hello", humanize=True)
+```
+
+---
+
+### Humanized Scroll with Physics Engine (`humanize=True`)
+
+The scroll API now features a **Cubic Bezier curve physics engine** for realistic scrolling:
+
+- **Momentum & friction**: Natural acceleration and deceleration
+- **Micro-pauses**: Brief stops during long scrolls (simulates reading)
+- **Jitter injection**: Small random variations in scroll path
+- **Overshoot correction**: Occasionally scrolls past target and corrects back
+
+```python
+# Smooth scroll (CSS animation, predictable timing)
+await tab.scroll.by(ScrollPosition.DOWN, 500, smooth=True)
+
+# Humanized scroll (physics engine, anti-bot)
+await tab.scroll.by(ScrollPosition.DOWN, 500, humanize=True)
+await tab.scroll.to_bottom(humanize=True)
+```
+
+| Mode | Parameter | Use Case |
+|------|-----------|----------|
+| **Instant** | `smooth=False` | Speed-critical operations |
+| **Smooth** | `smooth=True` | General browsing simulation |
+| **Humanized** | `humanize=True` | **Anti-bot evasion** |
+
+[**📖 Human-Like Interactions Docs**](https://pydoll.tech/docs/features/automation/human-interactions/)
+
+</details>
+
 ## 🚀 Getting Started in 60 Seconds
 
 Thanks to its `async` architecture and context managers, Pydoll is clean and efficient.

{pydoll_python-2.12.3 → pydoll_python-2.13.0}/README.md

@@ -39,6 +39,56 @@ pip install pydoll-python
 ```
 That's it. No `webdrivers`. No external dependencies.
 
+<details>
+<summary><b>🆕 What's New</b></summary>
+<br>
+
+### Humanized Keyboard Input (`humanize=True`)
+
+Pydoll now includes a **humanized typing engine** that simulates realistic human typing behavior:
+
+- **Variable keystroke timing**: 30-120ms between keys (not fixed intervals)
+- **Realistic typos**: ~2% error rate with automatic correction behavior
+- **No more `interval` parameter**: Just use `humanize=True` for anti-bot evasion
+
+```python
+# Old way (detectable)
+await element.type_text("hello", interval=0.1)
+
+# New way (human-like, anti-bot)
+await element.type_text("hello", humanize=True)
+```
+
+---
+
+### Humanized Scroll with Physics Engine (`humanize=True`)
+
+The scroll API now features a **Cubic Bezier curve physics engine** for realistic scrolling:
+
+- **Momentum & friction**: Natural acceleration and deceleration
+- **Micro-pauses**: Brief stops during long scrolls (simulates reading)
+- **Jitter injection**: Small random variations in scroll path
+- **Overshoot correction**: Occasionally scrolls past target and corrects back
+
+```python
+# Smooth scroll (CSS animation, predictable timing)
+await tab.scroll.by(ScrollPosition.DOWN, 500, smooth=True)
+
+# Humanized scroll (physics engine, anti-bot)
+await tab.scroll.by(ScrollPosition.DOWN, 500, humanize=True)
+await tab.scroll.to_bottom(humanize=True)
+```
+
+| Mode | Parameter | Use Case |
+|------|-----------|----------|
+| **Instant** | `smooth=False` | Speed-critical operations |
+| **Smooth** | `smooth=True` | General browsing simulation |
+| **Humanized** | `humanize=True` | **Anti-bot evasion** |
+
+[**📖 Human-Like Interactions Docs**](https://pydoll.tech/docs/features/automation/human-interactions/)
+
+</details>
+
 ## 🚀 Getting Started in 60 Seconds
 
 Thanks to its `async` architecture and context managers, Pydoll is clean and efficient.

{pydoll_python-2.12.3 → pydoll_python-2.13.0}/pydoll/constants.py

@@ -382,6 +382,22 @@ new Promise((resolve) => {{
 }});
 """
 
+    GET_SCROLL_Y = 'window.scrollY || window.pageYOffset || 0'
+
+    GET_REMAINING_SCROLL_TO_BOTTOM = """
+(function() {
+    const scrollHeight = Math.max(
+        document.body.scrollHeight,
+        document.documentElement.scrollHeight
+    );
+    const clientHeight = window.innerHeight;
+    const scrollTop = window.scrollY || window.pageYOffset || 0;
+    return Math.max(0, scrollHeight - clientHeight - scrollTop);
+})()
+"""
+
+    GET_VIEWPORT_CENTER = 'JSON.stringify([window.innerWidth / 2, window.innerHeight / 2])'
+
     INSERT_TEXT = """
     function() {
         const el = this;
@@ -562,3 +578,66 @@ class Key(tuple[str, int], Enum):
 class BrowserType(Enum):
     CHROME = auto()
     EDGE = auto()
+
+
+class TypoType(str, Enum):
+    """Types of realistic typing errors."""
+
+    ADJACENT = 'adjacent'
+    TRANSPOSE = 'transpose'
+    DOUBLE = 'double'
+    SKIP = 'skip'
+    MISSED_SPACE = 'missed_space'
+
+
+DEFAULT_TYPO_PROBABILITY = 0.02
+
+
+QWERTY_NEIGHBORS: dict[str, list[str]] = {
+    '1': ['2', 'q'],
+    '2': ['1', '3', 'q', 'w'],
+    '3': ['2', '4', 'w', 'e'],
+    '4': ['3', '5', 'e', 'r'],
+    '5': ['4', '6', 'r', 't'],
+    '6': ['5', '7', 't', 'y'],
+    '7': ['6', '8', 'y', 'u'],
+    '8': ['7', '9', 'u', 'i'],
+    '9': ['8', '0', 'i', 'o'],
+    '0': ['9', '-', 'o', 'p'],
+    '-': ['0', '=', 'p', '['],
+    '=': ['-', '[', ']'],
+    'q': ['1', '2', 'w', 'a', 's'],
+    'w': ['q', '2', '3', 'e', 'a', 's', 'd'],
+    'e': ['w', '3', '4', 'r', 's', 'd', 'f'],
+    'r': ['e', '4', '5', 't', 'd', 'f', 'g'],
+    't': ['r', '5', '6', 'y', 'f', 'g', 'h'],
+    'y': ['t', '6', '7', 'u', 'g', 'h', 'j'],
+    'u': ['y', '7', '8', 'i', 'h', 'j', 'k'],
+    'i': ['u', '8', '9', 'o', 'j', 'k', 'l'],
+    'o': ['i', '9', '0', 'p', 'k', 'l', ';'],
+    'p': ['o', '0', '-', '[', 'l', ';', "'"],
+    '[': ['p', '-', '=', ']', ';', "'"],
+    ']': ['[', '=', "'"],
+    'a': ['q', 'w', 's', 'z', 'x'],
+    's': ['q', 'w', 'e', 'a', 'd', 'z', 'x', 'c'],
+    'd': ['w', 'e', 'r', 's', 'f', 'x', 'c', 'v'],
+    'f': ['e', 'r', 't', 'd', 'g', 'c', 'v', 'b'],
+    'g': ['r', 't', 'y', 'f', 'h', 'v', 'b', 'n'],
+    'h': ['t', 'y', 'u', 'g', 'j', 'b', 'n', 'm'],
+    'j': ['y', 'u', 'i', 'h', 'k', 'n', 'm', ','],
+    'k': ['u', 'i', 'o', 'j', 'l', 'm', ',', '.'],
+    'l': ['i', 'o', 'p', 'k', ';', ',', '.', '/'],
+    ';': ['o', 'p', '[', 'l', "'", '.', '/'],
+    "'": ['p', '[', ']', ';', '/'],
+    'z': ['a', 's', 'x'],
+    'x': ['z', 'a', 's', 'd', 'c'],
+    'c': ['x', 's', 'd', 'f', 'v'],
+    'v': ['c', 'd', 'f', 'g', 'b'],
+    'b': ['v', 'f', 'g', 'h', 'n'],
+    'n': ['b', 'g', 'h', 'j', 'm'],
+    'm': ['n', 'h', 'j', 'k', ','],
+    ',': ['m', 'j', 'k', 'l', '.'],
+    '.': [',', 'k', 'l', ';', '/'],
+    '/': ['.', 'l', ';', "'"],
+    ' ': ['c', 'v', 'b', 'n', 'm'],
+}

{pydoll_python-2.12.3 → pydoll_python-2.13.0}/pydoll/elements/mixins/find_elements_mixin.py

@@ -11,11 +11,13 @@ from pydoll.commands import (
 from pydoll.connection.connection_handler import ConnectionHandler
 from pydoll.constants import By, Scripts
 from pydoll.exceptions import ElementNotFound, WaitElementTimeout
+from pydoll.utils import normalize_synthetic_xpath
 
 if TYPE_CHECKING:
     from typing import Literal, Optional, Union
 
-    from pydoll.elements.web_element import WebElement, _IFrameContext
+    from pydoll.elements.web_element import WebElement
+    from pydoll.interactions.iframe import IFrameContext
     from pydoll.protocol.base import Command, T_CommandParams, T_CommandResponse
     from pydoll.protocol.dom.methods import DescribeNodeResponse
     from pydoll.protocol.dom.types import Node
@@ -56,6 +58,35 @@ class FindElementsMixin:
     if TYPE_CHECKING:
         _connection_handler: ConnectionHandler
 
+    @staticmethod
+    def _build_text_expression(selector: str, method: str) -> Optional[str]:
+        """
+        Build JS expression using Scripts to extract textContent based on selector type.
+        """
+        raw = str(selector)
+        method_lc = (method or '').lower()
+
+        if 'xpath' in method_lc:
+            normalized_xpath = normalize_synthetic_xpath(raw)
+            escaped_xpath = normalized_xpath.replace('"', '\\"')
+            return Scripts.GET_TEXT_BY_XPATH.replace('{escaped_value}', escaped_xpath)
+
+        if method_lc == 'name':
+            escaped_name = raw.replace('"', '\\"')
+            xpath = f'//*[@name="{escaped_name}"]'
+            return Scripts.GET_TEXT_BY_XPATH.replace('{escaped_value}', xpath)
+
+        escaped = raw.replace('\\', '\\\\').replace('"', '\\"')
+        if method_lc == 'id':
+            css = f'#{escaped}'
+        elif method_lc == 'class_name':
+            css = f'.{escaped}'
+        elif method_lc == 'tag_name':
+            css = escaped
+        else:
+            css = escaped
+        return Scripts.GET_TEXT_BY_CSS.replace('{selector}', css)
+
     @overload
     async def find(
         self,
@@ -583,7 +614,7 @@ class FindElementsMixin:
         return response.get('result', {}).get('node', {})
 
     def _apply_iframe_context_to_element(
-        self, element: WebElement, iframe_context: _IFrameContext | None
+        self, element: WebElement, iframe_context: IFrameContext | None
     ) -> None:
         """
         Propagate iframe context to the newly created element.