# Humanization-Playwright
[](https://badge.fury.io/py/humanization-playwright)
[](https://opensource.org/licenses/MIT)
A Python library for simulating human-like browser interactions (mouse movements, typing, clicking, etc.) in automation scripts. Built on top of [Patchright](https://pypi.org/project/patchright/), a patched and undetected version of Playwright, this library helps evade bot detection by adding randomness, Bezier curve-based mouse paths, variable delays, and other human-mimicking behaviors. Ideal for web scraping, testing, or automation tasks requiring stealth.
## Features
- **Human-like Mouse Movements**: Uses cubic Bezier curves with jitter and pauses for natural paths.
- **Typing and Backspacing**: Variable speeds, pauses after spaces, and occasional hesitations.
- **Clicking and Hovering**: Supports left/right/middle clicks with delays.
- **Scrolling and Dragging**: Smooth, inertia-based scrolling and drag-and-drop.
- **Stealth Integration**: Leverages Patchright's patches for undetection (e.g., Runtime.enable leak fixes).
- **Configurable**: Adjust speed, humanization level, typing CPM, and stealth mode.
- **Async Support**: Fully asynchronous for efficient Playwright/Patchright usage.
- **New Additions**: Human waits, mouse overshoot corrections, and more for enhanced realism.
This library is designed as a drop-in enhancement for Patchright scripts, focusing on Chromium-based browsers (Firefox/Webkit not supported).
## Installation
Install via PyPI:
```bash
pip install humanization-playwright
```
After installation, set up Patchright's browser for optimal undetection:
```bash
playwright install chrome # Recommended for better stealth than Chromium
```
**Requirements**:
- Python 3.8+
- Patchright (automatically installed as a dependency)
- Loguru (for logging, also a dependency)
No additional packages needed; avoid installing extras to maintain stealth.
## Usage
### Basic Example
Launch a stealthy browser and perform human-like actions:
```python
import asyncio
from Humanization import Humanization, HumanizationConfig
async def main():
# Configure for slow, highly humanized actions with stealth
config = HumanizationConfig(
fast=False,
humanize=True,
characters_per_minute=400,
backspace_cpm=800,
timeout=10000,
stealth_mode=True
)
# Launch undetected context (uses Patchright recommendations)
Humanization = await Humanization.undetected_launch("/path/to/user_data_dir", config)
# Navigate to a site
await Humanization.page.goto("https://example.com")
# Locate an element
search_input = Humanization.page.locator("input#search")
# Human-like typing
await Humanization.type_at(search_input, "Hello, world!")
# Human-like click
submit_button = Humanization.page.locator("button#submit")
await Humanization.click_at(submit_button)
# Scroll down with inertia
await Humanization.scroll_to(delta_y=500)
# Drag-and-drop example
draggable = Humanization.page.locator("#draggable")
dropzone = Humanization.page.locator("#dropzone")
await Humanization.drag_to(draggable, dropzone)
# Random human pause
await Humanization.human_wait(min_sec=2, max_sec=5)
# Close the context
await Humanization.page.context.close()
asyncio.run(main())
```
### Advanced Configuration
The `HumanizationConfig` dataclass allows fine-tuning:
- `fast`: bool - Use fewer steps and shorter delays for quicker actions (default: True).
- `humanize`: bool - Add jitter, pauses, and hesitations (default: True).
- `characters_per_minute`: float - Typing speed (default: 600).
- `backspace_cpm`: float - Backspacing speed (default: 1200).
- `timeout`: float - Milliseconds for element visibility/focus checks (default: 5000).
- `stealth_mode`: bool - Apply Patchright's undetection defaults (default: True).
Pass custom params to methods, e.g.:
```python
await Humanization.move_to(locator, offset_x=10, offset_y=20, input_mode=True)
```
### Stealth Best Practices
- Always use `Humanization.undetected_launch` for persistent contexts.
- Run headless=False and avoid custom user agents/headers.
- Combine with Patchright's Chrome channel for maximum undetection.
- Test on anti-bot sites to verify.
## Logging
Uses Loguru for debug/info/error logs. Logs to `Humanization.log` by default (rotates at 100 MB).
## Development and Contributing
1. Clone the repo: `git clone https://github.com/saksham-personal/humanization-patchright.git`
2. Install editable: `pip install -e .`
3. Run tests: `pytest` .
4. Build: `python -m build`
Contributions welcome! Open issues/PRs on GitHub for bugs/features.
## License
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "humanization-playwright",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.13,>=3.8",
"maintainer_email": null,
"keywords": "automation, playwright, patchright, humanization, stealth, browser, web-scraping",
"author": null,
"author_email": "potui <saksham.kaushal.official@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/11/19/0c37b9676bccb71df8d3f99c9fc9104f660b3bc99feb25f08c9076a73996/humanization_playwright-0.1.2.tar.gz",
"platform": null,
"description": "# Humanization-Playwright\n\n[](https://badge.fury.io/py/humanization-playwright) \n[](https://opensource.org/licenses/MIT) \n\nA Python library for simulating human-like browser interactions (mouse movements, typing, clicking, etc.) in automation scripts. Built on top of [Patchright](https://pypi.org/project/patchright/), a patched and undetected version of Playwright, this library helps evade bot detection by adding randomness, Bezier curve-based mouse paths, variable delays, and other human-mimicking behaviors. Ideal for web scraping, testing, or automation tasks requiring stealth.\n\n## Features\n\n- **Human-like Mouse Movements**: Uses cubic Bezier curves with jitter and pauses for natural paths.\n- **Typing and Backspacing**: Variable speeds, pauses after spaces, and occasional hesitations.\n- **Clicking and Hovering**: Supports left/right/middle clicks with delays.\n- **Scrolling and Dragging**: Smooth, inertia-based scrolling and drag-and-drop.\n- **Stealth Integration**: Leverages Patchright's patches for undetection (e.g., Runtime.enable leak fixes).\n- **Configurable**: Adjust speed, humanization level, typing CPM, and stealth mode.\n- **Async Support**: Fully asynchronous for efficient Playwright/Patchright usage.\n- **New Additions**: Human waits, mouse overshoot corrections, and more for enhanced realism.\n\nThis library is designed as a drop-in enhancement for Patchright scripts, focusing on Chromium-based browsers (Firefox/Webkit not supported).\n\n## Installation\n\nInstall via PyPI:\n\n```bash\npip install humanization-playwright\n```\n\nAfter installation, set up Patchright's browser for optimal undetection:\n\n```bash\nplaywright install chrome # Recommended for better stealth than Chromium\n```\n\n**Requirements**:\n- Python 3.8+\n- Patchright (automatically installed as a dependency)\n- Loguru (for logging, also a dependency)\n\nNo additional packages needed; avoid installing extras to maintain stealth.\n\n## Usage\n\n### Basic Example\n\nLaunch a stealthy browser and perform human-like actions:\n\n```python\nimport asyncio\nfrom Humanization import Humanization, HumanizationConfig\n\nasync def main():\n # Configure for slow, highly humanized actions with stealth\n config = HumanizationConfig(\n fast=False,\n humanize=True,\n characters_per_minute=400,\n backspace_cpm=800,\n timeout=10000,\n stealth_mode=True\n )\n \n # Launch undetected context (uses Patchright recommendations)\n Humanization = await Humanization.undetected_launch(\"/path/to/user_data_dir\", config)\n \n # Navigate to a site\n await Humanization.page.goto(\"https://example.com\")\n \n # Locate an element\n search_input = Humanization.page.locator(\"input#search\")\n \n # Human-like typing\n await Humanization.type_at(search_input, \"Hello, world!\")\n \n # Human-like click\n submit_button = Humanization.page.locator(\"button#submit\")\n await Humanization.click_at(submit_button)\n \n # Scroll down with inertia\n await Humanization.scroll_to(delta_y=500)\n \n # Drag-and-drop example\n draggable = Humanization.page.locator(\"#draggable\")\n dropzone = Humanization.page.locator(\"#dropzone\")\n await Humanization.drag_to(draggable, dropzone)\n \n # Random human pause\n await Humanization.human_wait(min_sec=2, max_sec=5)\n \n # Close the context\n await Humanization.page.context.close()\n\nasyncio.run(main())\n```\n\n### Advanced Configuration\n\nThe `HumanizationConfig` dataclass allows fine-tuning:\n\n- `fast`: bool - Use fewer steps and shorter delays for quicker actions (default: True).\n- `humanize`: bool - Add jitter, pauses, and hesitations (default: True).\n- `characters_per_minute`: float - Typing speed (default: 600).\n- `backspace_cpm`: float - Backspacing speed (default: 1200).\n- `timeout`: float - Milliseconds for element visibility/focus checks (default: 5000).\n- `stealth_mode`: bool - Apply Patchright's undetection defaults (default: True).\n\nPass custom params to methods, e.g.:\n\n```python\nawait Humanization.move_to(locator, offset_x=10, offset_y=20, input_mode=True)\n```\n\n### Stealth Best Practices\n\n- Always use `Humanization.undetected_launch` for persistent contexts.\n- Run headless=False and avoid custom user agents/headers.\n- Combine with Patchright's Chrome channel for maximum undetection.\n- Test on anti-bot sites to verify.\n\n## Logging\n\nUses Loguru for debug/info/error logs. Logs to `Humanization.log` by default (rotates at 100 MB).\n\n## Development and Contributing\n\n1. Clone the repo: `git clone https://github.com/saksham-personal/humanization-patchright.git`\n2. Install editable: `pip install -e .`\n3. Run tests: `pytest` .\n4. Build: `python -m build`\n\nContributions welcome! Open issues/PRs on GitHub for bugs/features.\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.\n",
"bugtrack_url": null,
"license": null,
"summary": "A library for human-like interactions in Playwright automation, uses Patchright to avoid bot detection and human-like cursors and typing interactions",
"version": "0.1.2",
"project_urls": {
"Homepage": "https://github.com/saksham-personal/humanization-playwright.git",
"Repository": "https://github.com/saksham-personal/humanization-playwright.git"
},
"split_keywords": [
"automation",
" playwright",
" patchright",
" humanization",
" stealth",
" browser",
" web-scraping"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "33b5227fb68b1e6174c83f1175678373c2facfaabbce506458bc87ad1d05a484",
"md5": "9e3d0d088e81886475db19a0bf274fa7",
"sha256": "9d2a476c96f1276c88468245f10215582ec727916baf9a64729fc24480b71d42"
},
"downloads": -1,
"filename": "humanization_playwright-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9e3d0d088e81886475db19a0bf274fa7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.13,>=3.8",
"size": 8056,
"upload_time": "2025-07-21T05:10:59",
"upload_time_iso_8601": "2025-07-21T05:10:59.199148Z",
"url": "https://files.pythonhosted.org/packages/33/b5/227fb68b1e6174c83f1175678373c2facfaabbce506458bc87ad1d05a484/humanization_playwright-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "11190c37b9676bccb71df8d3f99c9fc9104f660b3bc99feb25f08c9076a73996",
"md5": "b6e53cece53cb772f714c3069ee9bc16",
"sha256": "5b05d5d7db5a283a8448d5e00f23626e367ccd370af30c286abee82e5e5bce7f"
},
"downloads": -1,
"filename": "humanization_playwright-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "b6e53cece53cb772f714c3069ee9bc16",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.13,>=3.8",
"size": 9132,
"upload_time": "2025-07-21T05:11:00",
"upload_time_iso_8601": "2025-07-21T05:11:00.475545Z",
"url": "https://files.pythonhosted.org/packages/11/19/0c37b9676bccb71df8d3f99c9fc9104f660b3bc99feb25f08c9076a73996/humanization_playwright-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-21 05:11:00",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "saksham-personal",
"github_project": "humanization-playwright",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "humanization-playwright"
}
JSON
