pydoll-python 2.9.3__tar.gz → 2.10.0__tar.gz

{pydoll_python-2.9.3 → pydoll_python-2.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pydoll-python
-Version: 2.9.3
+Version: 2.10.0
 Summary: Pydoll is a library for automating chromium-based browsers without a WebDriver, offering realistic interactions.
 License-File: LICENSE
 Author: Thalison Fernandes
@@ -52,37 +52,35 @@ Built from scratch with a different philosophy, Pydoll connects directly to the
 
 We believe that powerful automation shouldn't require you to become an expert in configuration or constantly fight with bot protection systems. With Pydoll, you can focus on what really matters: your automation logic, not the underlying complexity or protection systems.
 
-### 🚀 Major Update in Development: Enhanced Stealth and Humanization Capabilities
+## 🌟 What makes Pydoll special?
 
-Pydoll is undergoing a significant development phase focused on incorporating advanced techniques for bot detection evasion and more realistic user interaction simulation.
+- **Zero Webdrivers**: Say goodbye to webdriver compatibility issues
+- **Human-like Interaction Engine**: Capable of passing behavioral CAPTCHAs like reCAPTCHA v3 or Turnstile, depending on IP reputation and interaction patterns
+- **Asynchronous Performance**: For high-speed automation and multiple simultaneous tasks
+- **Humanized Interactions**: Mimic real user behavior
+- **Simplicity**: With Pydoll, you install and you're ready to automate.
 
-This update is based on extensive technical research and will include both substantial documentation improvements and new library features.
+## 🆕 What's New
 
-**Highlights of the Upcoming Release:**
+### Human-Like Page Scrolling: Scroll Like a Real User!
 
-* **Integrated Humanization Features:** Native implementations for:
-    * **Mouse Interaction:** Simulation of cursor paths using Bezier curves, variable speeds based on Fitts's Law principles, and randomized click offsets. Event sequences (`mousemove`, `mousedown`, `mouseup`, `click`) will be handled automatically.
-    * **Keyboard Input:** Character-by-character typing with randomized `Dwell` (key press duration) and `Flight` (time between keys) times. Optional simulation of typing errors and corrections.
-    * **Scroll Simulation:** Physics-based scrolling mimicking momentum and inertia.
-    * **Timing Variations:** Introduction of randomized delays ("cognitive time") before and after actions to avoid predictable automation patterns.
-* **Comprehensive Documentation Overhaul:** A new series of in-depth technical guides ("Deep Dives") covering:
-    * **Network Fingerprinting:** Analysis of TCP/IP, TLS/JA3, and HTTP/2 characteristics. Includes practical examples like **building custom HTTP and SOCKS5 proxy servers** and discussing proxy detection techniques.
-    * **Browser Fingerprinting:** Detailed exploration of `navigator` properties, Client Hints, Canvas/WebGL rendering, font detection, and screen attributes.
-    * **Behavioral Fingerprinting:** Analysis of mouse dynamics, keystroke patterns (including bigram timing), scroll physics, and event sequencing.
-    * **Advanced Browser Control:** Extensive documentation on using `browser_preferences` to modify hundreds of internal Chromium settings for granular control over performance, privacy, and fingerprinting.
-    * **Practical Examples:** Including configurations for **Docker environments** and common evasion scenarios.
+Now you can control page scrolling with smooth animations and automatic completion waiting:
 
-The aim is to provide users with both the theoretical understanding and the practical tools within Pydoll to create automation flows that are significantly harder to detect.
+```python
+from pydoll.constants import ScrollPosition
 
-**Follow the progress by starring the repository ⭐!**
+# Scroll down with smooth animation (waits for completion)
+await tab.scroll.by(ScrollPosition.DOWN, 500, smooth=True)
 
-## 🌟 What makes Pydoll special?
+# Navigate to specific positions
+await tab.scroll.to_bottom(smooth=True)
+await tab.scroll.to_top(smooth=True)
 
-- **Zero Webdrivers**: Say goodbye to webdriver compatibility issues
-- **Human-like Interaction Engine**: Capable of passing behavioral CAPTCHAs like reCAPTCHA v3 or Turnstile, depending on IP reputation and interaction patterns
-- **Asynchronous Performance**: For high-speed automation and multiple simultaneous tasks
-- **Humanized Interactions**: Mimic real user behavior
-- **Simplicity**: With Pydoll, you install and you're ready to automate.
+# Instant scroll for speed when realism isn't critical
+await tab.scroll.by(ScrollPosition.UP, 300, smooth=False)
+```
+
+Unlike `execute_script("window.scrollBy(...)")` which returns immediately, the scroll API uses CDP's `awaitPromise` to wait for the browser's `scrollend` event, ensuring your next actions only execute after scrolling completely finishes. Perfect for taking screenshots, loading lazy content, or creating realistic reading patterns.
 
 ## 📦 Installation
 

{pydoll_python-2.9.3 → pydoll_python-2.10.0}/README.md

@@ -32,37 +32,35 @@ Built from scratch with a different philosophy, Pydoll connects directly to the
 
 We believe that powerful automation shouldn't require you to become an expert in configuration or constantly fight with bot protection systems. With Pydoll, you can focus on what really matters: your automation logic, not the underlying complexity or protection systems.
 
-### 🚀 Major Update in Development: Enhanced Stealth and Humanization Capabilities
+## 🌟 What makes Pydoll special?
 
-Pydoll is undergoing a significant development phase focused on incorporating advanced techniques for bot detection evasion and more realistic user interaction simulation.
+- **Zero Webdrivers**: Say goodbye to webdriver compatibility issues
+- **Human-like Interaction Engine**: Capable of passing behavioral CAPTCHAs like reCAPTCHA v3 or Turnstile, depending on IP reputation and interaction patterns
+- **Asynchronous Performance**: For high-speed automation and multiple simultaneous tasks
+- **Humanized Interactions**: Mimic real user behavior
+- **Simplicity**: With Pydoll, you install and you're ready to automate.
 
-This update is based on extensive technical research and will include both substantial documentation improvements and new library features.
+## 🆕 What's New
 
-**Highlights of the Upcoming Release:**
+### Human-Like Page Scrolling: Scroll Like a Real User!
 
-* **Integrated Humanization Features:** Native implementations for:
-    * **Mouse Interaction:** Simulation of cursor paths using Bezier curves, variable speeds based on Fitts's Law principles, and randomized click offsets. Event sequences (`mousemove`, `mousedown`, `mouseup`, `click`) will be handled automatically.
-    * **Keyboard Input:** Character-by-character typing with randomized `Dwell` (key press duration) and `Flight` (time between keys) times. Optional simulation of typing errors and corrections.
-    * **Scroll Simulation:** Physics-based scrolling mimicking momentum and inertia.
-    * **Timing Variations:** Introduction of randomized delays ("cognitive time") before and after actions to avoid predictable automation patterns.
-* **Comprehensive Documentation Overhaul:** A new series of in-depth technical guides ("Deep Dives") covering:
-    * **Network Fingerprinting:** Analysis of TCP/IP, TLS/JA3, and HTTP/2 characteristics. Includes practical examples like **building custom HTTP and SOCKS5 proxy servers** and discussing proxy detection techniques.
-    * **Browser Fingerprinting:** Detailed exploration of `navigator` properties, Client Hints, Canvas/WebGL rendering, font detection, and screen attributes.
-    * **Behavioral Fingerprinting:** Analysis of mouse dynamics, keystroke patterns (including bigram timing), scroll physics, and event sequencing.
-    * **Advanced Browser Control:** Extensive documentation on using `browser_preferences` to modify hundreds of internal Chromium settings for granular control over performance, privacy, and fingerprinting.
-    * **Practical Examples:** Including configurations for **Docker environments** and common evasion scenarios.
+Now you can control page scrolling with smooth animations and automatic completion waiting:
 
-The aim is to provide users with both the theoretical understanding and the practical tools within Pydoll to create automation flows that are significantly harder to detect.
+```python
+from pydoll.constants import ScrollPosition
 
-**Follow the progress by starring the repository ⭐!**
+# Scroll down with smooth animation (waits for completion)
+await tab.scroll.by(ScrollPosition.DOWN, 500, smooth=True)
 
-## 🌟 What makes Pydoll special?
+# Navigate to specific positions
+await tab.scroll.to_bottom(smooth=True)
+await tab.scroll.to_top(smooth=True)
 
-- **Zero Webdrivers**: Say goodbye to webdriver compatibility issues
-- **Human-like Interaction Engine**: Capable of passing behavioral CAPTCHAs like reCAPTCHA v3 or Turnstile, depending on IP reputation and interaction patterns
-- **Asynchronous Performance**: For high-speed automation and multiple simultaneous tasks
-- **Humanized Interactions**: Mimic real user behavior
-- **Simplicity**: With Pydoll, you install and you're ready to automate.
+# Instant scroll for speed when realism isn't critical
+await tab.scroll.by(ScrollPosition.UP, 300, smooth=False)
+```
+
+Unlike `execute_script("window.scrollBy(...)")` which returns immediately, the scroll API uses CDP's `awaitPromise` to wait for the browser's `scrollend` event, ensuring your next actions only execute after scrolling completely finishes. Perfect for taking screenshots, loading lazy content, or creating realistic reading patterns.
 
 ## 📦 Installation
 

{pydoll_python-2.9.3 → pydoll_python-2.10.0}/pydoll/browser/tab.py

@@ -50,6 +50,7 @@ from pydoll.exceptions import (
     TopLevelTargetRequired,
     WaitElementTimeout,
 )
+from pydoll.interactions.scroll import ScrollAPI
 from pydoll.protocol.browser.types import DownloadBehavior, DownloadProgressState
 from pydoll.protocol.page.events import PageEvent
 from pydoll.protocol.page.types import ScreenshotFormat
@@ -131,6 +132,7 @@ class Tab(FindElementsMixin):
         self._intercept_file_chooser_dialog_enabled = False
         self._cloudflare_captcha_callback_id: Optional[int] = None
         self._request: Optional[Request] = None
+        self._scroll: Optional[ScrollAPI] = None
         logger.debug(
             (
                 f'Tab initialized: target_id={self._target_id}, '
@@ -176,6 +178,18 @@ class Tab(FindElementsMixin):
             self._request = Request(self)
         return self._request
 
+    @property
+    def scroll(self) -> ScrollAPI:
+        """
+        Get the scroll API for controlling page scroll behavior.
+
+        Returns:
+            ScrollAPI: An instance of the ScrollAPI class for scroll operations.
+        """
+        if self._scroll is None:
+            self._scroll = ScrollAPI(self)
+        return self._scroll
+
     @property
     def intercept_file_chooser_dialog_enabled(self) -> bool:
         """Whether file chooser dialog interception is active."""

{pydoll_python-2.9.3 → pydoll_python-2.10.0}/pydoll/constants.py

@@ -15,6 +15,13 @@ class PageLoadState(str, Enum):
     INTERACTIVE = 'interactive'
 
 
+class ScrollPosition(str, Enum):
+    UP = 'up'
+    DOWN = 'down'
+    LEFT = 'left'
+    RIGHT = 'right'
+
+
 class Scripts:
     ELEMENT_VISIBLE = """
     function() {
@@ -268,6 +275,87 @@ class Scripts:
 }})();
 """
 
+    SCROLL_BY = """
+new Promise((resolve) => {{
+    const behavior = '{behavior}';
+    if (behavior === 'auto') {{
+        window.scrollBy({{
+            {axis}: {distance},
+            behavior: 'auto'
+        }});
+        resolve();
+    }} else {{
+        const onScrollEnd = () => {{
+            window.removeEventListener('scrollend', onScrollEnd);
+            resolve();
+        }};
+        window.addEventListener('scrollend', onScrollEnd);
+        window.scrollBy({{
+            {axis}: {distance},
+            behavior: 'smooth'
+        }});
+        setTimeout(() => {{
+            window.removeEventListener('scrollend', onScrollEnd);
+            resolve();
+        }}, 2000);
+    }}
+}});
+"""
+
+    SCROLL_TO_TOP = """
+new Promise((resolve) => {{
+    const behavior = '{behavior}';
+    if (behavior === 'auto') {{
+        window.scrollTo({{
+            top: 0,
+            behavior: 'auto'
+        }});
+        resolve();
+    }} else {{
+        const onScrollEnd = () => {{
+            window.removeEventListener('scrollend', onScrollEnd);
+            resolve();
+        }};
+        window.addEventListener('scrollend', onScrollEnd);
+        window.scrollTo({{
+            top: 0,
+            behavior: 'smooth'
+        }});
+        setTimeout(() => {{
+            window.removeEventListener('scrollend', onScrollEnd);
+            resolve();
+        }}, 2000);
+    }}
+}});
+"""
+
+    SCROLL_TO_BOTTOM = """
+new Promise((resolve) => {{
+    const behavior = '{behavior}';
+    if (behavior === 'auto') {{
+        window.scrollTo({{
+            top: document.body.scrollHeight,
+            behavior: 'auto'
+        }});
+        resolve();
+    }} else {{
+        const onScrollEnd = () => {{
+            window.removeEventListener('scrollend', onScrollEnd);
+            resolve();
+        }};
+        window.addEventListener('scrollend', onScrollEnd);
+        window.scrollTo({{
+            top: document.body.scrollHeight,
+            behavior: 'smooth'
+        }});
+        setTimeout(() => {{
+            window.removeEventListener('scrollend', onScrollEnd);
+            resolve();
+        }}, 2000);
+    }}
+}});
+"""
+
 
 class Key(tuple[str, int], Enum):
     BACKSPACE = ('Backspace', 8)

pydoll_python-2.10.0/pydoll/interactions/__init__.py

@@ -0,0 +1,3 @@
+from pydoll.interactions.scroll import ScrollAPI
+
+__all__ = ['ScrollAPI']

pydoll_python-2.10.0/pydoll/interactions/scroll.py

@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from pydoll.commands import RuntimeCommands
+from pydoll.constants import Scripts, ScrollPosition
+
+if TYPE_CHECKING:
+    from pydoll.browser.tab import Tab
+
+
+class ScrollAPI:
+    """
+    API for controlling page scroll behavior.
+
+    Provides methods for scrolling the page in different directions,
+    to specific positions, or by relative distances.
+    """
+
+    def __init__(self, tab: Tab):
+        """
+        Initialize the ScrollAPI with a tab instance.
+
+        Args:
+            tab: Tab instance to execute scroll commands on.
+        """
+        self._tab = tab
+
+    async def by(
+        self,
+        position: ScrollPosition,
+        distance: int | float,
+        smooth: bool = True,
+    ):
+        """
+        Scroll the page by a relative distance in the specified direction.
+
+        Args:
+            position: Direction to scroll (UP, DOWN, LEFT, RIGHT).
+            distance: Number of pixels to scroll.
+            smooth: Use smooth scrolling animation if True, instant if False.
+        """
+        axis, scroll_distance = self._get_axis_and_distance(position, distance)
+        behavior = self._get_behavior(smooth)
+
+        script = Scripts.SCROLL_BY.format(
+            axis=axis,
+            distance=scroll_distance,
+            behavior=behavior,
+        )
+
+        await self._execute_script_await_promise(script)
+
+    async def to_top(self, smooth: bool = True):
+        """
+        Scroll to the top of the page (Y=0).
+
+        Args:
+            smooth: Use smooth scrolling animation if True, instant if False.
+        """
+        behavior = self._get_behavior(smooth)
+        script = Scripts.SCROLL_TO_TOP.format(behavior=behavior)
+        await self._execute_script_await_promise(script)
+
+    async def to_bottom(self, smooth: bool = True):
+        """
+        Scroll to the bottom of the page (Y=document.body.scrollHeight).
+
+        Args:
+            smooth: Use smooth scrolling animation if True, instant if False.
+        """
+        behavior = self._get_behavior(smooth)
+        script = Scripts.SCROLL_TO_BOTTOM.format(behavior=behavior)
+        await self._execute_script_await_promise(script)
+
+    @staticmethod
+    def _get_axis_and_distance(
+        position: ScrollPosition, distance: int | float
+    ) -> tuple[str, int | float]:
+        """
+        Convert scroll position to axis and signed distance.
+
+        Args:
+            position: Direction to scroll.
+            distance: Absolute distance to scroll.
+
+        Returns:
+            Tuple of (axis, signed_distance) where axis is 'left' or 'top'
+            and signed_distance is positive or negative based on direction.
+        """
+        if position in {ScrollPosition.UP, ScrollPosition.DOWN}:
+            axis = 'top'
+            scroll_distance = -distance if position == ScrollPosition.UP else distance
+            return axis, scroll_distance * 10
+
+        axis = 'left'
+        scroll_distance = -distance if position == ScrollPosition.LEFT else distance
+        return axis, scroll_distance * 10
+
+    @staticmethod
+    def _get_behavior(smooth: bool) -> str:
+        """
+        Convert smooth boolean to CSS scroll behavior value.
+
+        Args:
+            smooth: Whether to use smooth scrolling.
+
+        Returns:
+            'smooth' if smooth is True, 'auto' otherwise.
+        """
+        return 'smooth' if smooth else 'auto'
+
+    async def _execute_script_await_promise(self, script: str):
+        """
+        Execute JavaScript and await promise resolution.
+
+        Args:
+            script: JavaScript code that returns a Promise.
+        """
+        command = RuntimeCommands.evaluate(expression=script, await_promise=True)
+        return await self._tab._execute_command(command)

{pydoll_python-2.9.3 → pydoll_python-2.10.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "pydoll-python"
-version = "2.9.3"
+version = "2.10.0"
 description = "Pydoll is a library for automating chromium-based browsers without a WebDriver, offering realistic interactions."
 authors = ["Thalison Fernandes <thalissfernandes99@gmail.com>"]
 readme = "README.md"