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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pydoll-python
-Version: 2.10.0
+Version: 2.11.0
 Summary: Pydoll is a library for automating chromium-based browsers without a WebDriver, offering realistic interactions.
 License-File: LICENSE
 Author: Thalison Fernandes
@@ -82,6 +82,36 @@ 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.
 
+### Keyboard API: Complete Control Over Keyboard Input
+
+The new `KeyboardAPI` provides a clean, centralized interface for all keyboard interactions at the page level:
+
+```python
+from pydoll.constants import Key
+
+# Press individual keys
+await tab.keyboard.press(Key.ENTER)
+await tab.keyboard.press(Key.TAB)
+
+# Use hotkeys/shortcuts with up to 3 keys  
+await tab.keyboard.hotkey(Key.CONTROL, Key.A)  # Select all (works!)
+await tab.keyboard.hotkey(Key.CONTROL, Key.C)  # Copy (works!)
+await tab.keyboard.hotkey(Key.CONTROL, Key.SHIFT, Key.ARROWRIGHT)  # Select word right
+
+# Manual control for complex sequences
+await tab.keyboard.down(Key.SHIFT)
+await tab.keyboard.press(Key.ARROWRIGHT)  # Select text while holding Shift
+await tab.keyboard.up(Key.SHIFT)
+```
+
+**Key improvements:**
+- **Centralized**: All keyboard operations accessible via `tab.keyboard`
+- **Smart modifier detection**: Hotkeys automatically detect and apply modifiers (Ctrl, Shift, Alt, Meta)
+- **Complete key support**: 26 letters (A-Z), 10 digits (0-9), all function keys, numpad, and special keys
+- **Page-level shortcuts**: Works for Ctrl+C, Ctrl+V, Ctrl+A, etc.
+
+> **⚠️ CDP Limitation:** Browser UI shortcuts (like Ctrl+T for new tab, F12 for DevTools) don't work via CDP. Use Pydoll's methods instead: `await browser.new_tab()`, `await tab.close()`.
+
 ## 📦 Installation
 
 ```bash

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

@@ -62,6 +62,36 @@ 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.
 
+### Keyboard API: Complete Control Over Keyboard Input
+
+The new `KeyboardAPI` provides a clean, centralized interface for all keyboard interactions at the page level:
+
+```python
+from pydoll.constants import Key
+
+# Press individual keys
+await tab.keyboard.press(Key.ENTER)
+await tab.keyboard.press(Key.TAB)
+
+# Use hotkeys/shortcuts with up to 3 keys  
+await tab.keyboard.hotkey(Key.CONTROL, Key.A)  # Select all (works!)
+await tab.keyboard.hotkey(Key.CONTROL, Key.C)  # Copy (works!)
+await tab.keyboard.hotkey(Key.CONTROL, Key.SHIFT, Key.ARROWRIGHT)  # Select word right
+
+# Manual control for complex sequences
+await tab.keyboard.down(Key.SHIFT)
+await tab.keyboard.press(Key.ARROWRIGHT)  # Select text while holding Shift
+await tab.keyboard.up(Key.SHIFT)
+```
+
+**Key improvements:**
+- **Centralized**: All keyboard operations accessible via `tab.keyboard`
+- **Smart modifier detection**: Hotkeys automatically detect and apply modifiers (Ctrl, Shift, Alt, Meta)
+- **Complete key support**: 26 letters (A-Z), 10 digits (0-9), all function keys, numpad, and special keys
+- **Page-level shortcuts**: Works for Ctrl+C, Ctrl+V, Ctrl+A, etc.
+
+> **⚠️ CDP Limitation:** Browser UI shortcuts (like Ctrl+T for new tab, F12 for DevTools) don't work via CDP. Use Pydoll's methods instead: `await browser.new_tab()`, `await tab.close()`.
+
 ## 📦 Installation
 
 ```bash

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

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

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

@@ -356,6 +356,66 @@ new Promise((resolve) => {{
 }});
 """
 
+    INSERT_TEXT = """
+    function() {
+        const el = this;
+        const text = arguments[0];
+
+        // Standard input/textarea
+        if (el.tagName === 'INPUT' || el.tagName === 'TEXTAREA') {
+            const start = el.selectionStart || el.value.length;
+            const end = el.selectionEnd || el.value.length;
+            const before = el.value.substring(0, start);
+            const after = el.value.substring(end);
+            el.value = before + text + after;
+            el.selectionStart = el.selectionEnd = start + text.length;
+            el.dispatchEvent(new Event('input', { bubbles: true }));
+            el.dispatchEvent(new Event('change', { bubbles: true }));
+            return true;
+        }
+
+        // ContentEditable elements
+        if (el.isContentEditable) {
+            el.focus();
+            const selection = window.getSelection();
+            const range = selection.getRangeAt(0);
+            range.deleteContents();
+            const textNode = document.createTextNode(text);
+            range.insertNode(textNode);
+            range.setStartAfter(textNode);
+            range.setEndAfter(textNode);
+            selection.removeAllRanges();
+            selection.addRange(range);
+            el.dispatchEvent(new Event('input', { bubbles: true }));
+            return true;
+        }
+
+        return false;
+    }
+    """
+
+    IS_EDITABLE = """
+    function() {
+        const el = this;
+
+        // Check standard input elements
+        if (el.tagName === 'INPUT' || el.tagName === 'TEXTAREA') {
+            return !el.disabled && !el.readOnly;
+        }
+
+        // Check contenteditable (including inherited)
+        let current = el;
+        while (current) {
+            if (current.isContentEditable) {
+                return true;
+            }
+            current = current.parentElement;
+        }
+
+        return false;
+    }
+    """
+
 
 class Key(tuple[str, int], Enum):
     BACKSPACE = ('Backspace', 8)
@@ -379,11 +439,64 @@ class Key(tuple[str, int], Enum):
     PRINTSCREEN = ('PrintScreen', 44)
     INSERT = ('Insert', 45)
     DELETE = ('Delete', 46)
+
+    DIGIT0 = ('0', 48)
+    DIGIT1 = ('1', 49)
+    DIGIT2 = ('2', 50)
+    DIGIT3 = ('3', 51)
+    DIGIT4 = ('4', 52)
+    DIGIT5 = ('5', 53)
+    DIGIT6 = ('6', 54)
+    DIGIT7 = ('7', 55)
+    DIGIT8 = ('8', 56)
+    DIGIT9 = ('9', 57)
+
+    A = ('A', 65)
+    B = ('B', 66)
+    C = ('C', 67)
+    D = ('D', 68)
+    E = ('E', 69)
+    F = ('F', 70)
+    G = ('G', 71)
+    H = ('H', 72)
+    I = ('I', 73)  # noqa: E741
+    J = ('J', 74)
+    K = ('K', 75)
+    L = ('L', 76)
+    M = ('M', 77)
+    N = ('N', 78)
+    O = ('O', 79)  # noqa: E741
+    P = ('P', 80)
+    Q = ('Q', 81)
+    R = ('R', 82)
+    S = ('S', 83)
+    T = ('T', 84)
+    U = ('U', 85)
+    V = ('V', 86)
+    W = ('W', 87)
+    X = ('X', 88)
+    Y = ('Y', 89)
+    Z = ('Z', 90)
+
     META = ('Meta', 91)
     METARIGHT = ('MetaRight', 92)
     CONTEXTMENU = ('ContextMenu', 93)
-    NUMLOCK = ('NumLock', 144)
-    SCROLLLOCK = ('ScrollLock', 145)
+
+    NUMPAD0 = ('Numpad0', 96)
+    NUMPAD1 = ('Numpad1', 97)
+    NUMPAD2 = ('Numpad2', 98)
+    NUMPAD3 = ('Numpad3', 99)
+    NUMPAD4 = ('Numpad4', 100)
+    NUMPAD5 = ('Numpad5', 101)
+    NUMPAD6 = ('Numpad6', 102)
+    NUMPAD7 = ('Numpad7', 103)
+    NUMPAD8 = ('Numpad8', 104)
+    NUMPAD9 = ('Numpad9', 105)
+    NUMPADMULTIPLY = ('NumpadMultiply', 106)
+    NUMPADADD = ('NumpadAdd', 107)
+    NUMPADSUBTRACT = ('NumpadSubtract', 109)
+    NUMPADDECIMAL = ('NumpadDecimal', 110)
+    NUMPADDIVIDE = ('NumpadDivide', 111)
 
     F1 = ('F1', 112)
     F2 = ('F2', 113)
@@ -398,6 +511,9 @@ class Key(tuple[str, int], Enum):
     F11 = ('F11', 122)
     F12 = ('F12', 123)
 
+    NUMLOCK = ('NumLock', 144)
+    SCROLLLOCK = ('ScrollLock', 145)
+
     SEMICOLON = ('Semicolon', 186)
     EQUALSIGN = ('EqualSign', 187)
     COMMA = ('Comma', 188)

{pydoll_python-2.10.0 → pydoll_python-2.11.0}/pydoll/elements/web_element.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 import asyncio
 import json
 import logging
+import warnings
 from pathlib import Path
 from typing import TYPE_CHECKING
 
@@ -36,6 +37,7 @@ from pydoll.protocol.input.types import (
     MouseEventType,
 )
 from pydoll.protocol.page.types import ScreenshotFormat, Viewport
+from pydoll.protocol.runtime.types import CallArgument
 from pydoll.utils import (
     decode_base64_to_bytes,
     extract_text_from_html,
@@ -457,13 +459,31 @@ class WebElement(FindElementsMixin):  # noqa: PLR0904
 
     async def insert_text(self, text: str):
         """
-        Insert text in single operation (faster but less realistic than typing).
+        Insert text into element using JavaScript.
+
+        Supports standard inputs, textareas, contenteditable elements, and rich text editors.
+        Inserts text at cursor position or replaces selected text.
+
+        Args:
+            text: Text to insert.
+
+        Raises:
+            ElementNotInteractable: If element does not accept text input.
 
         Note:
-            Element should already be focused for text to be inserted correctly.
+            Uses JavaScript for maximum compatibility with all input types.
+            Automatically handles input/textarea and contenteditable elements.
         """
-        logger.info(f'Inserting text on element (length={len(text)})')
-        await self._execute_command(InputCommands.insert_text(text))
+        logger.info(f'Inserting text (length={len(text)})')
+        result = await self.execute_script(
+            Scripts.INSERT_TEXT, return_by_value=True, arguments=[CallArgument(value=text)]
+        )
+        logger.debug(f'Insert text result: {result}')
+        success = result['result'].get('result', {}).get('value', False)
+
+        if not success:
+            logger.error('Element does not accept text input')
+            raise ElementNotInteractable('Element does not accept text input')
 
     async def set_input_files(self, files: str | Path | list[str | Path]):
         """
@@ -507,9 +527,18 @@ class WebElement(FindElementsMixin):  # noqa: PLR0904
         """
         Send key down event.
 
+        .. deprecated::
+            This method is deprecated. Use ``tab.keyboard.down()`` instead.
+
         Note:
             Only sends key down without release. Pair with key_up() for complete keypress.
         """
+        warnings.warn(
+            'WebElement.key_down() is deprecated. '
+            'Use tab.keyboard API instead: await tab.keyboard.down(key, modifiers)',
+            DeprecationWarning,
+            stacklevel=2,
+        )
         key_name, code = key
         logger.info(f'Key down: key={key_name} code={code} modifiers={modifiers}')
         await self._execute_command(
@@ -523,7 +552,18 @@ class WebElement(FindElementsMixin):  # noqa: PLR0904
         )
 
     async def key_up(self, key: Key):
-        """Send key up event (should follow corresponding key_down())."""
+        """
+        Send key up event (should follow corresponding key_down()).
+
+        .. deprecated::
+            This method is deprecated. Use ``tab.keyboard.up()`` instead.
+        """
+        warnings.warn(
+            'WebElement.key_up() is deprecated. '
+            'Use tab.keyboard API instead: await tab.keyboard.up(key)',
+            DeprecationWarning,
+            stacklevel=2,
+        )
         key_name, code = key
         logger.info(f'Key up: key={key_name} code={code}')
         await self._execute_command(
@@ -544,12 +584,33 @@ class WebElement(FindElementsMixin):  # noqa: PLR0904
         """
         Press and release keyboard key with configurable timing.
 
+        .. deprecated::
+            This method is deprecated. Use ``tab.keyboard.press()`` instead.
+
         Better for special keys (Enter, Tab, etc.) than type_text().
         """
+        warnings.warn(
+            'WebElement.press_keyboard_key() is deprecated. '
+            'Use tab.keyboard API instead: await tab.keyboard.press(key, modifiers, interval)',
+            DeprecationWarning,
+            stacklevel=2,
+        )
         await self.key_down(key, modifiers)
         await asyncio.sleep(interval)
         await self.key_up(key)
 
+    async def is_editable(self) -> bool:
+        """
+        Check if element can accept text input.
+
+        Returns:
+            True if element is editable (input, textarea, or contenteditable).
+        """
+        result = await self.execute_script(Scripts.IS_EDITABLE, return_by_value=True)
+        is_editable = result['result']['result']['value']
+        logger.debug(f'Element editable check: {is_editable}')
+        return is_editable
+
     async def _click_option_tag(self):
         """Specialized method for clicking <option> elements in dropdowns."""
         await self._execute_command(
@@ -575,20 +636,34 @@ class WebElement(FindElementsMixin):  # noqa: PLR0904
         result = await self.execute_script(Scripts.ELEMENT_INTERACTIVE, return_by_value=True)
         return result['result']['result']['value']
 
-    async def execute_script(self, script: str, return_by_value: bool = False):
+    async def execute_script(
+        self,
+        script: str,
+        return_by_value: bool = False,
+        arguments: Optional[list[CallArgument]] = None,
+    ):
         """
         Execute JavaScript in element context.
 
-        Element is available as 'this' within the script.
+        Args:
+            script: JavaScript function to execute.
+            return_by_value: Whether to return result by value.
+            arguments: Optional list of arguments to pass to the function.
+
+        Note:
+            Element is available as 'this' within the script.
+            Arguments are accessible via 'arguments' array in JavaScript.
         """
         logger.debug(
-            f'Executing script on element: return_by_value={return_by_value}, length={len(script)}'
+            f'Executing script on element: return_by_value={return_by_value}, '
+            f'length={len(script)}, args={len(arguments) if arguments else 0}'
         )
         return await self._execute_command(
             RuntimeCommands.call_function_on(
                 object_id=self._object_id,
                 function_declaration=script,
                 return_by_value=return_by_value,
+                arguments=arguments,
             )
         )
 

pydoll_python-2.11.0/pydoll/interactions/__init__.py

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

pydoll_python-2.11.0/pydoll/interactions/keyboard.py

@@ -0,0 +1,178 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import TYPE_CHECKING, Optional, cast
+
+from pydoll.commands import InputCommands
+from pydoll.constants import Key
+from pydoll.protocol.input.types import KeyEventType, KeyModifier
+
+if TYPE_CHECKING:
+    from pydoll.browser.tab import Tab
+
+logger = logging.getLogger(__name__)
+
+
+class KeyboardAPI:
+    """
+    API for controlling keyboard input at page level.
+
+    Provides methods for simulating keyboard input, key combinations,
+    and realistic typing using CDP Input domain.
+    """
+
+    def __init__(self, tab: Tab):
+        """
+        Initialize the KeyboardAPI with a tab instance.
+
+        Args:
+            tab: Tab instance to execute keyboard commands on.
+        """
+        logger.debug(f'Initializing KeyboardAPI for tab: {tab}')
+        self._tab = tab
+
+    async def press(
+        self,
+        key: Key,
+        modifiers: Optional[KeyModifier] = None,
+        interval: float = 0.1,
+    ):
+        """
+        Press and release a key (down + wait + up).
+
+        Args:
+            key: Key to press (from Key enum).
+            modifiers: Optional key modifiers (Alt=1, Ctrl=2, Meta=4, Shift=8).
+            interval: Time to hold the key down in seconds.
+
+        Example:
+            await tab.keyboard.press(Key.ENTER)
+            await tab.keyboard.press(Key.A, modifiers=KeyModifier.CTRL)
+        """
+        logger.info(f'Pressing key: {key} with modifiers: {modifiers} and interval: {interval}')
+        await self.down(key, modifiers)
+        await asyncio.sleep(interval)
+        await self.up(key)
+
+    async def down(self, key: Key, modifiers: Optional[KeyModifier] = None):
+        """
+        Press a key down (without releasing).
+
+        Args:
+            key: Key to press down (from Key enum).
+            modifiers: Optional key modifiers (Alt=1, Ctrl=2, Meta=4, Shift=8).
+
+        Example:
+            await tab.keyboard.down(Key.SHIFT)
+        """
+        key_name, code = key
+        logger.info(f'Pressing key down: {key_name} with modifiers: {modifiers}')
+        command = InputCommands.dispatch_key_event(
+            type=KeyEventType.KEY_DOWN,
+            key=key_name,
+            windows_virtual_key_code=code,
+            native_virtual_key_code=code,
+            modifiers=modifiers,
+        )
+        await self._tab._execute_command(command)
+
+    async def up(self, key: Key):
+        """
+        Release a key (key up event).
+
+        Args:
+            key: Key to release (from Key enum).
+
+        Example:
+            await tab.keyboard.up(Key.SHIFT)
+        """
+        logger.info(f'Pressing key up: {key}')
+        key_name, code = key
+        command = InputCommands.dispatch_key_event(
+            type=KeyEventType.KEY_UP,
+            key=key_name,
+            windows_virtual_key_code=code,
+            native_virtual_key_code=code,
+        )
+        await self._tab._execute_command(command)
+
+    async def hotkey(self, key1: Key, key2: Key, key3: Optional[Key] = None):
+        """
+        Execute a key combination (hotkey) with up to 3 keys.
+
+        Automatically detects modifier keys (Ctrl, Shift, Alt, Meta) and applies
+        them correctly when pressing non-modifier keys.
+
+        Args:
+            key1: First key (usually a modifier like Ctrl, Shift, Alt).
+            key2: Second key.
+            key3: Optional third key.
+
+        Example:
+            await tab.keyboard.hotkey(Key.CONTROL, Key.C)  # Ctrl+C
+            await tab.keyboard.hotkey(Key.CONTROL, Key.SHIFT, Key.T)  # Ctrl+Shift+T
+        """
+        logger.info(f'Executing hotkey: {key1} {key2} {key3}')
+        keys = [key1, key2]
+        if key3 is not None:
+            keys.append(key3)
+
+        modifiers, non_modifiers = self._split_modifiers_and_keys(keys)
+        modifier_value = self._calculate_modifier_value(modifiers)
+
+        logger.debug(f'Modifiers: {modifiers} modifier_value: {modifier_value}')
+        for key in non_modifiers:
+            await self.down(key, modifiers=modifier_value)
+            await asyncio.sleep(0.05)
+
+        await asyncio.sleep(0.1)
+
+        for key in reversed(non_modifiers):
+            await self.up(key)
+            await asyncio.sleep(0.05)
+
+    @staticmethod
+    def _split_modifiers_and_keys(keys: list[Key]) -> tuple[list[Key], list[Key]]:
+        """
+        Split keys into modifiers and non-modifiers.
+
+        Args:
+            keys: List of keys to split.
+
+        Returns:
+            Tuple of (modifiers, non_modifiers).
+        """
+        modifier_keys = {Key.CONTROL, Key.SHIFT, Key.ALT, Key.META}
+        modifiers = [k for k in keys if k in modifier_keys]
+        non_modifiers = [k for k in keys if k not in modifier_keys]
+        logger.debug(f'Modifiers: {modifiers} Non-modifiers: {non_modifiers}')
+        return modifiers, non_modifiers
+
+    @staticmethod
+    def _calculate_modifier_value(modifiers: list[Key]) -> Optional[KeyModifier]:
+        """
+        Calculate the KeyModifier value from a list of modifier keys.
+
+        Args:
+            modifiers: List of modifier keys.
+
+        Returns:
+            Combined KeyModifier value, or None if no modifiers.
+        """
+        logger.debug(f'Calculating modifier value for: {modifiers}')
+        if not modifiers:
+            return None
+
+        modifier_map = {
+            Key.ALT: 1,
+            Key.CONTROL: 2,
+            Key.META: 4,
+            Key.SHIFT: 8,
+        }
+
+        value = 0
+        for modifier in modifiers:
+            value += modifier_map.get(modifier, 0)
+
+        return cast(KeyModifier, value) if value > 0 else None

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

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "pydoll-python"
-version = "2.10.0"
+version = "2.11.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"

pydoll_python-2.10.0/pydoll/interactions/__init__.py

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