[ { "path": ".github/FUNDING.yml", "content": "# These are supported funding model platforms\ngithub: [thalissonvs]\n\n" }, { "path": ".github/ISSUE_TEMPLATE/bug_report.yml", "content": "name: Bug Report\ndescription: Report a bug in pydoll\ntitle: \"[Bug]: \"\nlabels: [\"bug\", \"needs-triage\"]\nbody:\n - type: markdown\n attributes:\n value: |\n # pydoll Bug Report\n \n Thank you for taking the time to report a bug. This form will guide you through providing the information needed to address the issue effectively.\n \n - type: checkboxes\n id: checklist\n attributes:\n label: Checklist before reporting\n description: Please make sure you've completed the following steps before submitting a bug report.\n options:\n - label: I have searched for [similar issues](https://github.com/thalissonvs/pydoll/issues) and didn't find a duplicate.\n required: true\n - label: I have updated to the latest version of pydoll to verify the issue still exists.\n required: true\n \n - type: input\n id: version\n attributes:\n label: pydoll Version\n description: What version of pydoll are you using when encountering this bug?\n placeholder: e.g., 1.3.2\n validations:\n required: true\n \n - type: input\n id: python_version\n attributes:\n label: Python Version\n description: What version of Python are you using?\n placeholder: e.g., 3.10.4\n validations:\n required: true\n \n - type: dropdown\n id: os\n attributes:\n label: Operating System\n description: What operating system are you using?\n options:\n - Windows\n - macOS\n - Linux\n - Other (specify in environment details)\n validations:\n required: true\n \n - type: textarea\n id: description\n attributes:\n label: Bug Description\n description: A clear and concise description of what the bug is.\n placeholder: When I try to use X feature, the library fails with error message Y...\n validations:\n required: true\n \n - type: textarea\n id: reproduction_steps\n attributes:\n label: Steps to Reproduce\n description: Step by step instructions to reproduce the bug.\n placeholder: |\n 1. Import the library using `import pydoll`\n 2. Set up the client with `...`\n 3. Call method X with parameters Y\n 4. See error\n validations:\n required: true\n \n - type: textarea\n id: code_example\n attributes:\n label: Code Example\n description: |\n A minimal, self-contained code example that demonstrates the issue.\n This will be automatically formatted into code, so no need for backticks.\n render: python\n placeholder: |\n from pydoll import Client\n \n client = Client(...)\n \n # Code that triggers the bug\n result = client.some_method(...)\n print(result)\n validations:\n required: true\n \n - type: textarea\n id: expected_behavior\n attributes:\n label: Expected Behavior\n description: A clear and concise description of what you expected to happen.\n placeholder: The method should return X or perform Y...\n validations:\n required: false\n \n - type: textarea\n id: actual_behavior\n attributes:\n label: Actual Behavior\n description: What actually happened instead? Include full error messages and stack traces if applicable.\n placeholder: The method raised an exception...\n validations:\n required: false\n \n - type: textarea\n id: logs\n attributes:\n label: Relevant Log Output\n description: |\n If applicable, include any logs or error messages. \n This will be automatically formatted, so no need for backticks.\n render: shell\n placeholder: |\n Traceback (most recent call last):\n File \"example.py\", line 10, in \n ...\n File \".../pydoll/...\", line N, in some_method\n ...\n SomeError: Error message\n \n - type: textarea\n id: additional_context\n attributes:\n label: Additional Context\n description: Add any other context about the problem here (environment details, potential causes, solutions you've tried, etc.)\n placeholder: I've tried reinstalling the package and using a different Python version, but the issue persists... \n" }, { "path": ".github/ISSUE_TEMPLATE/config.yml", "content": "blank_issues_enabled: true\ncontact_links:\n - name: Questions & Discussions\n url: https://github.com/thalissonvs/pydoll/discussions\n about: Please ask and answer questions here. \n" }, { "path": ".github/ISSUE_TEMPLATE/documentation.yml", "content": "name: Documentation Issue\ndescription: Report missing, incorrect, or unclear documentation\ntitle: \"[Docs]: \"\nlabels: [\"documentation\", \"needs-triage\"]\nbody:\n - type: markdown\n attributes:\n value: |\n # pydoll Documentation Issue\n \n Thank you for helping us improve the documentation. This form will guide you through providing the information needed to address documentation issues effectively.\n \n - type: checkboxes\n id: checklist\n attributes:\n label: Checklist before reporting\n description: Please make sure you've completed the following steps before submitting a documentation issue.\n options:\n - label: I have searched for [similar documentation issues](https://github.com/thalissonvs/pydoll/issues) and didn't find a duplicate.\n required: true\n - label: I have checked the latest documentation to verify this issue still exists.\n required: true\n \n - type: dropdown\n id: type\n attributes:\n label: Type of Documentation Issue\n description: What type of documentation issue are you reporting?\n options:\n - Missing documentation (information does not exist)\n - Incorrect documentation (information is wrong)\n - Unclear documentation (information is confusing or ambiguous)\n - Outdated documentation (information is no longer valid)\n - Other (please specify in description)\n validations:\n required: true\n \n - type: input\n id: location\n attributes:\n label: Documentation Location\n description: Where is the documentation with issues located? Provide URLs, file paths, or section names.\n placeholder: e.g., https://docs.example.com/pydoll/api.html#section, README.md, API Reference for Client class\n validations:\n required: true\n \n - type: textarea\n id: description\n attributes:\n label: Issue Description\n description: Describe the issue with the documentation in detail.\n placeholder: |\n The documentation for the `Client.connect()` method doesn't mention the timeout parameter, \n which I discovered by looking at the source code.\n validations:\n required: true\n \n - type: textarea\n id: suggested_fix\n attributes:\n label: Suggested Fix\n description: If you have a suggestion for how to fix the documentation, please provide it here.\n placeholder: |\n Add the following to the `Client.connect()` documentation:\n \n ```\n Parameters:\n timeout (float, optional): Connection timeout in seconds. Defaults to 30.\n ```\n \n - type: textarea\n id: additional_info\n attributes:\n label: Additional Information\n description: Any additional context or information that might help address this documentation issue.\n placeholder: |\n I found this issue when trying to implement a connection with a shorter timeout for my specific use case.\n \n - type: dropdown\n id: contribution\n attributes:\n label: Contribution\n description: Would you be willing to contribute a fix for this documentation?\n options:\n - Yes, I'd be willing to submit a PR with the fix\n - No, I don't have the capacity to fix this\n validations:\n required: true " }, { "path": ".github/ISSUE_TEMPLATE/feature_request.yml", "content": "name: Feature Request\ndescription: Suggest a new feature or enhancement for pydoll\ntitle: \"[Feature Request]: \"\nlabels: [\"enhancement\", \"needs-triage\"]\nbody:\n - type: markdown\n attributes:\n value: |\n # pydoll Feature Request\n \n Thank you for taking the time to suggest a new feature. This form will guide you through providing the information needed to consider your suggestion effectively.\n \n - type: checkboxes\n id: checklist\n attributes:\n label: Checklist before requesting\n description: Please make sure you've completed the following steps before submitting a feature request.\n options:\n - label: I have searched for [similar feature requests](https://github.com/thalissonvs/pydoll/issues) and didn't find a duplicate.\n required: true\n - label: I have checked the documentation to confirm this feature doesn't already exist.\n required: true\n \n - type: textarea\n id: problem\n attributes:\n label: Problem Statement\n description: Is your feature request related to a problem? Please describe what you're trying to accomplish.\n placeholder: I'm trying to accomplish X, but I'm unable to because Y...\n validations:\n required: true\n \n - type: textarea\n id: solution\n attributes:\n label: Proposed Solution\n description: Describe the solution you'd like to see implemented. Be as specific as possible.\n placeholder: |\n I would like to see a new method/class that can...\n \n Example usage might look like:\n ```python\n client.new_feature(param1, param2)\n ```\n validations:\n required: true\n \n - type: textarea\n id: alternatives\n attributes:\n label: Alternatives Considered\n description: Describe any alternative solutions or features you've considered.\n placeholder: I've tried accomplishing this using X and Y approaches, but they don't work well because...\n \n - type: textarea\n id: context\n attributes:\n label: Additional Context\n description: Add any other context, code examples, or references that might help explain your feature request.\n placeholder: |\n Other libraries like X and Y have similar features that work like...\n \n This would help users who need to...\n \n - type: dropdown\n id: importance\n attributes:\n label: Importance\n description: How important is this feature to your use case?\n options:\n - Nice to have\n - Important\n - Critical (blocking my usage)\n validations:\n required: true\n \n - type: dropdown\n id: contribution\n attributes:\n label: Contribution\n description: Would you be willing to contribute this feature yourself?\n options:\n - Yes, I'd be willing to implement this feature\n - I could help with parts of the implementation\n - No, I don't have the capacity to implement this " }, { "path": ".github/ISSUE_TEMPLATE/refactoring.yml", "content": "name: Refactoring Request\ndescription: Suggest code refactoring to improve pydoll's quality, performance, or maintainability\ntitle: \"[Refactor]: \"\nlabels: [\"refactor\", \"needs-triage\"]\nbody:\n - type: markdown\n attributes:\n value: |\n # pydoll Refactoring Request\n \n Thank you for suggesting improvements to our codebase. This form will guide you through providing the information needed to consider your refactoring suggestion effectively.\n \n - type: checkboxes\n id: checklist\n attributes:\n label: Checklist before suggesting refactoring\n description: Please make sure you've completed the following steps before submitting a refactoring request.\n options:\n - label: I have searched for [similar refactoring requests](https://github.com/thalissonvs/pydoll/issues) and didn't find a duplicate.\n required: true\n - label: I have reviewed the current implementation to ensure my understanding is accurate.\n required: true\n \n - type: textarea\n id: current_implementation\n attributes:\n label: Current Implementation\n description: Describe the current implementation and its limitations. Include file paths if known.\n placeholder: |\n The current implementation in `pydoll/module/file.py` has the following issues:\n 1. It uses an inefficient algorithm for...\n 2. The code structure makes it difficult to maintain because...\n validations:\n required: true\n \n - type: textarea\n id: proposed_changes\n attributes:\n label: Proposed Changes\n description: Describe the changes you're suggesting. Be as specific as possible.\n placeholder: |\n I suggest refactoring this code to:\n 1. Replace the current algorithm with X, which would improve performance by...\n 2. Restructure the class hierarchy to better separate concerns by...\n \n Example code sketch (if applicable):\n ```python\n def improved_method():\n # better implementation\n ```\n validations:\n required: true\n \n - type: textarea\n id: benefits\n attributes:\n label: Benefits\n description: Explain the benefits of this refactoring.\n placeholder: |\n This refactoring would:\n - Improve performance by X%\n - Make the code more maintainable by...\n - Reduce code complexity by...\n - Fix potential bugs such as...\n validations:\n required: true\n \n - type: dropdown\n id: impact\n attributes:\n label: API Impact\n description: Would this refactoring change the public API?\n options:\n - No API changes (internal refactoring only)\n - Minor API changes (backward compatible)\n - Breaking API changes\n validations:\n required: true\n \n - type: textarea\n id: testing_approach\n attributes:\n label: Testing Approach\n description: How can we verify that the refactoring doesn't break existing functionality?\n placeholder: |\n The refactoring can be tested by:\n - Running the existing test suite\n - Adding new tests for edge cases such as...\n - Benchmarking performance before and after\n \n - type: dropdown\n id: contribution\n attributes:\n label: Contribution\n description: Would you be willing to contribute this refactoring yourself?\n options:\n - Yes, I'd be willing to implement this refactoring\n - I could help with parts of the implementation\n - No, I don't have the capacity to implement this " }, { "path": ".github/PULL_REQUEST_TEMPLATE/bug_fix.md", "content": "# Bug Fix Pull Request\n\n## Related Issue(s)\n\n\n## Bug Description\n\n\n## Root Cause\n\n\n## Solution\n\n\n## Verification Steps\n\n1. \n2. \n3. \n\n## Code Example\n\n```python\n# Example code showing the fix\n```\n\n## Before / After\n\n\n## Testing\n\n\n## Testing Checklist\n- [ ] Added regression test that would have caught this bug\n- [ ] Modified existing tests to account for this fix\n- [ ] All tests pass\n- [ ] Edge cases have been tested\n\n## Impact\n\n- [ ] Low (isolated fix with no side effects)\n- [ ] Medium (might affect closely related functionality)\n- [ ] High (affects multiple areas or changes core behavior)\n\n## Backwards Compatibility\n- [ ] This change is fully backward compatible\n- [ ] This change introduces backward incompatibilities (explain below)\n\n## Checklist before requesting a review\n- [ ] My code follows the style guidelines of this project\n- [ ] I have performed a self-review of my code\n- [ ] I have added test cases that prove my fix is effective\n- [ ] I have run `poetry run task lint` and fixed any issues\n- [ ] I have run `poetry run task test` and all tests pass\n- [ ] My commits follow the [conventional commits](https://www.conventionalcommits.org/) style with message explaining the fix " }, { "path": ".github/PULL_REQUEST_TEMPLATE/refactoring.md", "content": "# Refactoring Pull Request\n\n## Refactoring Scope\n\n\n## Related Issue(s)\n\n\n## Description\n\n\n## Motivation\n\n\n## Before / After\n\n\n### Before\n```python\n# Original code\n```\n\n### After\n```python\n# Refactored code\n```\n\n## Performance Impact\n\n- [ ] Performance improved\n- [ ] Performance potentially decreased\n- [ ] No significant performance change\n- [ ] Performance impact unknown\n\n## Technical Debt\n\n\n## API Changes\n- [ ] No changes to public API\n- [ ] Public API changed, but backward compatible\n- [ ] Breaking changes to public API\n\n## Testing Strategy\n\n\n## Testing Checklist\n- [ ] Existing tests updated\n- [ ] New tests added for previously uncovered cases\n- [ ] All tests pass\n- [ ] Code coverage maintained or improved\n\n## Risks and Mitigations\n\n\n## Checklist before requesting a review\n- [ ] My code follows the style guidelines of this project\n- [ ] I have performed a thorough self-review of the refactored code\n- [ ] I have commented my code, particularly in complex areas\n- [ ] I have updated documentation if needed\n- [ ] I have run `poetry run task lint` and fixed any issues\n- [ ] I have run `poetry run task test` and all tests pass\n- [ ] My commits follow the [conventional commits](https://www.conventionalcommits.org/) style " }, { "path": ".github/PULL_REQUEST_TEMPLATE/release.md", "content": "# Release Pull Request\n\n## Version\n\n\n## Release Date\n\n\n## Release Type\n- [ ] Major (breaking changes)\n- [ ] Minor (new features, non-breaking)\n- [ ] Patch (bug fixes, non-breaking)\n\n## Change Summary\n\n\n## Key Changes\n\n\n## Breaking Changes\n\n\n## Dependencies\n\n\n## Deprecations \n- While `get_element_text()` is still supported, it is **recommended** to use the new async property `element.text`.\n\n\n## Documentation\n\n\n## Release Checklist\n- [ ] Version number updated in pyproject.toml\n- [ ] Version number updated in cz.yaml\n- [ ] CHANGELOG.md updated with all changes\n- [ ] All tests passing\n- [ ] Documentation updated\n- [ ] API reference updated\n- [ ] Breaking changes documented\n- [ ] Migration guides prepared (if applicable)\n\n## Additional Release Notes\n " }, { "path": ".github/pull_request_template.md", "content": "\n\n# Pull Request\n\n## Description\n\n\n## Related Issue(s)\n\n\n## Type of Change\n\n- [ ] Bug fix (non-breaking change which fixes an issue)\n- [ ] New feature (non-breaking change which adds functionality)\n- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)\n- [ ] Documentation update\n- [ ] Refactoring (no functional changes, no API changes)\n- [ ] Performance improvement\n- [ ] Tests (adding missing tests or correcting existing tests)\n- [ ] Build or CI/CD related changes\n\n## How Has This Been Tested?\n\n\n```python\n# Include code examples if relevant\n```\n\n## Testing Checklist\n\n- [ ] Unit tests added/updated\n- [ ] Integration tests added/updated\n- [ ] All existing tests pass\n\n## Screenshots\n\n\n## Implementation Details\n\n\n## API Changes\n\n\n## Additional Info\n\n\n## Checklist before requesting a review\n- [ ] My code follows the style guidelines of this project\n- [ ] I have performed a self-review of my code\n- [ ] I have commented my code, particularly in hard-to-understand areas\n- [ ] I have made corresponding changes to the documentation\n- [ ] My changes generate no new warnings\n- [ ] I have added tests that prove my fix is effective or that my feature works\n- [ ] New and existing unit tests pass locally with my changes\n- [ ] I have run `poetry run task lint` and fixed any issues\n- [ ] I have run `poetry run task test` and all tests pass\n- [ ] My commits follow the [conventional commits](https://www.conventionalcommits.org/) style " }, { "path": ".github/workflows/deploy-docs.yml", "content": "name: Deploy site + docs\n\non:\n push:\n branches: [main]\n\njobs:\n deploy:\n runs-on: ubuntu-latest\n steps:\n - name: Code Checkout\n uses: actions/checkout@v4\n\n - name: Setup Python\n uses: actions/setup-python@v5\n with:\n python-version: '3.x'\n\n - name: Install Dependencies\n run: |\n python -m pip install --upgrade pip\n pip install mkdocs mkdocs-material pymdown-extensions mkdocstrings[python] mkdocs-static-i18n\n\n # Build MkDocs em pasta temporária\n - name: Build MkDocs into temp folder\n run: mkdocs build --site-dir temp_docs\n\n # Criar estrutura final do site\n - name: Prepare final site\n run: |\n mkdir -p site/docs\n mkdir -p site/images\n cp -r temp_docs/* site/docs/\n cp -r public/* site/\n\n - name: Deploy to GitHub Pages\n uses: peaceiris/actions-gh-pages@v3\n with:\n github_token: ${{ secrets.GITHUB_TOKEN }}\n publish_dir: ./site\n cname: pydoll.tech\n" }, { "path": ".github/workflows/mypy.yml", "content": "name: MyPy CI\n\non:\n push:\n branches:\n - '*' # matches every branch that doesn't contain a '/'\n - '*/*' # matches every branch containing a single '/'\n - '**' # matches every branch\n pull_request:\n\njobs:\n build:\n\n runs-on: ubuntu-latest\n\n strategy:\n max-parallel: 4\n matrix:\n python-version: [\"3.11\"]\n\n steps:\n - uses: actions/checkout@v2\n\n - name: Set up Python ${{ matrix.python-version }}\n uses: actions/setup-python@v2\n with:\n python-version: ${{ matrix.python-version }}\n\n - name: Install Dependencies\n run: |\n python -m pip install --upgrade pip\n python -m pip install mypy\n python -m pip install -e .\n python -m mypy --install-types --non-interactive pydoll \n\n - name: mypy\n run: python -m mypy .\n" }, { "path": ".github/workflows/publish.yml", "content": "name: Publish to PyPI (Poetry)\n\non: workflow_dispatch\n\njobs:\n deploy:\n runs-on: ubuntu-latest\n\n steps:\n - name: Checkout code\n uses: actions/checkout@v3\n\n - name: Set up Python\n uses: actions/setup-python@v4\n with:\n python-version: \"3.10\"\n\n - name: Install Poetry\n run: |\n python -m pip install --upgrade pip\n pip install poetry\n\n - name: Configure Poetry\n run: poetry config pypi-token.pypi ${{ secrets.PYPI_API_TOKEN }}\n\n - name: Install dependencies\n run: poetry install\n\n - name: Build package\n run: poetry build\n\n - name: Publish to PyPI\n run: poetry publish\n" }, { "path": ".github/workflows/release.yml", "content": "name: Release\non: workflow_dispatch\n\njobs:\n version-cz:\n runs-on: ubuntu-latest\n name: \"Version CZ\"\n outputs:\n version: ${{ steps.cz.outputs.version }}\n\n steps:\n - name: Checkout\n uses: actions/checkout@v4\n with:\n fetch-depth: 0\n token: ${{ secrets.GITHUB_TOKEN }}\n\n - id: cz\n name: Create bump and changelog\n uses: commitizen-tools/commitizen-action@master\n with:\n github_token: ${{ secrets.GITHUB_TOKEN }}\n\n - name: Print Version\n run: echo \"Bumped to version ${{ steps.cz.outputs.version }}\"\n \n version-pyproject:\n runs-on: ubuntu-latest\n name: \"Version Pyproject\"\n needs: version-cz\n outputs:\n version: ${{ needs.version-cz.outputs.version }}\n steps:\n - name: Checkout\n uses: actions/checkout@v4\n with:\n fetch-depth: 0\n token: ${{ secrets.GITHUB_TOKEN }}\n\n - name: Install Poetry\n run: |\n curl -sSL https://install.python-poetry.org | python3 -\n export PATH=\"$HOME/.local/bin:$PATH\"\n\n - name: Update Poetry version in pyproject.toml\n run: |\n git config --global user.name \"github-actions[bot]\"\n git config --global user.email \"github-actions[bot]@users.noreply.github.com\"\n poetry version \"${{ needs.version-cz.outputs.version }}\"\n git add pyproject.toml\n git commit -m \"Update pyproject.toml to version ${{ needs.version-cz.outputs.version }}\"\n git pull --rebase\n git push\n\n - name: Update poetry.lock\n continue-on-error: true\n run: |\n git config --global user.name \"github-actions[bot]\"\n git config --global user.email \"github-actions[bot]@users.noreply.github.com\"\n poetry lock\n git add poetry.lock\n git commit -m \"Update poetry.lock\"\n git pull --rebase\n git push\n\n\n release:\n name: Release\n needs: version-pyproject\n runs-on: ubuntu-latest\n steps:\n - name: Create Release\n uses: softprops/action-gh-release@v1\n with:\n draft: false\n prerelease: false\n generate_release_notes: true\n tag_name: ${{ needs.version-pyproject.outputs.version }}\n env:\n GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n" }, { "path": ".github/workflows/ruff-ci.yml", "content": "name: Ruff CI\n\non:\n push:\n branches:\n - '*' # matches every branch that doesn't contain a '/'\n - '*/*' # matches every branch containing a single '/'\n - '**' # matches every branch\n pull_request:\n\njobs:\n build:\n\n runs-on: ubuntu-latest\n\n strategy:\n max-parallel: 4\n matrix:\n python-version: [\"3.11\"]\n\n steps:\n - uses: actions/checkout@v2\n\n - name: Set up Python ${{ matrix.python-version }}\n uses: actions/setup-python@v2\n with:\n python-version: ${{ matrix.python-version }}\n\n - name: Install Dependencies\n run: |\n python -m pip install --upgrade pip\n python -m pip install ruff==0.7.1\n\n - name: ruff\n run: python -m ruff check .\n" }, { "path": ".github/workflows/tests.yml", "content": "name: PyDoll Tests\n\non:\n push:\n pull_request:\n\njobs:\n tests:\n strategy:\n fail-fast: false\n matrix:\n os: [ubuntu-latest, windows-latest]\n python-version: [\"3.10\", \"3.11\", \"3.12\", \"3.13\"]\n runs-on: ${{ matrix.os }}\n steps:\n - uses: actions/checkout@v3\n - name: Set up Python ${{ matrix.python-version }}\n uses: actions/setup-python@v4\n with:\n python-version: ${{ matrix.python-version }}\n - name: Install dependencies\n run: |\n python -m pip install poetry\n poetry install\n - name: Install Chrome\n uses: browser-actions/setup-chrome@v1\n with:\n chrome-version: 132\n - name: Run tests with coverage\n run: |\n poetry run pytest -s -x --cov=pydoll -vv --cov-report=xml\n\n - name: Upload coverage to Codecov\n uses: codecov/codecov-action@v5\n with:\n file: ./coverage.xml\n flags: tests\n name: PyDoll Tests\n fail_ci_if_error: true\n token: ${{ secrets.CODECOV_TOKEN }}\n" }, { "path": ".gitignore", "content": "__pycache__/\n*.py[cod]\n*$py.class\n\n# C extensions\n*.so\n\n# Distribution / packaging\n.Python\nbuild/\ndevelop-eggs/\ndist/\ndownloads/\neggs/\n.eggs/\nlib/\nlib64/\nparts/\nsdist/\nvar/\nwheels/\nshare/python-wheels/\n*.egg-info/\n.installed.cfg\n*.egg\nMANIFEST\n\n# PyInstaller\n# Usually these files are written by a python script from a template\n# before PyInstaller builds the exe, so as to inject date/other infos into it.\n*.manifest\n*.spec\n\n# Installer logs\npip-log.txt\npip-delete-this-directory.txt\n\n# Unit test / coverage reports\nhtmlcov/\n.tox/\n.nox/\n.coverage\n.coverage.*\n.cache\nnosetests.xml\ncoverage.xml\n*.cover\n*.py,cover\n.hypothesis/\n.pytest_cache/\ncover/\n\n# Translations\n*.mo\n*.pot\n\n# Django stuff:\n*.log\nlocal_settings.py\ndb.sqlite3\ndb.sqlite3-journal\n\n# Flask stuff:\ninstance/\n.webassets-cache\n\n# Scrapy stuff:\n.scrapy\n\n# Sphinx documentation\ndocs/_build/\n\n# PyBuilder\n.pybuilder/\n\n\n# Jupyter Notebook\n.ipynb_checkpoints\n\n# IPython\nprofile_default/\nipython_config.py\n\n# pyenv\n# For a library or package, you might want to ignore these files since the code is\n# intended to run in multiple environments; otherwise, check them in:\n# .python-version\n\n# pipenv\n# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.\n# However, in case of collaboration, if having platform-specific dependencies or dependencies\n# having no cross-platform support, pipenv may install dependencies that don't work, or not\n# install all needed dependencies.\n#Pipfile.lock\n\n# poetry\n# Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.\n# This is especially recommended for binary packages to ensure reproducibility, and is more\n# commonly ignored for libraries.\n# https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control\n#poetry.lock\n\n# pdm\n# Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.\n#pdm.lock\n# pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it\n# in version control.\n# https://pdm.fming.dev/latest/usage/project/#working-with-version-control\n.pdm.toml\n.pdm-python\n.pdm-build/\n\n# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm\n__pypackages__/\n\n# Celery stuff\ncelerybeat-schedule\ncelerybeat.pid\n\n# SageMath parsed files\n*.sage.py\n\n# Environments\n.env\n.venv\nenv/\nvenv/\nENV/\nenv.bak/\nvenv.bak/\n\n# Spyder project settings\n.spyderproject\n.spyproject\n\n# Rope project settings\n.ropeproject\n\n# mkdocs documentation\n/site\n\n# mypy\n.mypy_cache/\n.dmypy.json\ndmypy.json\n\n# Pyre type checker\n.pyre/\n\n# pytype static type analyzer\n.pytype/\n\n# Cython debug symbols\ncython_debug/\n\n# PyCharm\n# JetBrains specific template is maintained in a separate JetBrains.gitignore that can\n# be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore\n# and can be added to the global gitignore or merged into this file. For a more nuclear\n# option (not recommended) you can uncomment the following to ignore the entire idea folder.\n#.idea/\n\n.czrc\n.ruff_cache/\n\n# Dev test file\ndev_test_file.py\n" }, { "path": ".python-version", "content": "3.12.5\n" }, { "path": "CHANGELOG.md", "content": "## 2.21.3 (2026-03-14)\n\n### Fix\n\n- **test**: improve OOPIF integration test reliability\n- **iframe**: resolve nested OOPIF iframes inside shadow roots\n\n## 2.21.2 (2026-03-12)\n\n### Fix\n\n- release commit\n\n## 2.21.1 (2026-03-03)\n\n### Fix\n\n- **keyboard**: send correct key, code and keycode in type_text\n- **elements**: fix humanized interactions inside iframes\n- humanized scroll overshoot correction causes infinite loop\n\n## 2.21.0 (2026-03-01)\n\n### Feat\n\n- **interactions**: change humanize default from True to False\n\n### Fix\n\n- **elements**: forward humanize flag to click in type_text\n\n## 2.20.2 (2026-02-18)\n\n### Fix\n\n- **command**: increase default command timeout from 10s to 60s across multiple components\n- **tab**: remove temporary flag to avoid duplicate callback removal\n\n## 2.20.1 (2026-02-16)\n\n### Fix\n\n- **tab**: replace readyState polling with CDP events in navigation\n\n## 2.20.0 (2026-02-13)\n\n### Feat\n\n- **mouse**: add timing property for runtime configuration\n- **requests**: add record() and replay() to Request class\n- **requests**: add HAR network recorder\n- **protocol**: add HAR 1.2 type definitions\n\n### Fix\n\n- **requests**: use surgical callback removal instead of nuclear clear_callbacks\n\n### Refactor\n\n- **tab**: extract bundle static methods to utils module\n\n## 2.19.0 (2026-02-12)\n\n### Feat\n\n- **interactions**: default humanize=True for keyboard type_text\n- **elements**: integrate Mouse API into WebElement.click()\n- **interactions**: add Mouse API with humanized simulation\n- **browser**: add webrtc_leak_protection property to ChromiumOptions\n- **browser**: add automatic User-Agent consistency override\n\n### Fix\n\n- **utils**: harden SOCKS5 proxy forwarder security and robustness\n\n## 2.18.0 (2026-02-11)\n\n### Feat\n\n- **utils**: add SOCKS5 proxy forwarder and convert utils to package\n- **elements**: add cross-iframe selector support for XPath and CSS\n\n## 2.17.0 (2026-02-08)\n\n### Feat\n\n- **tab**: refactor cloudflare bypass to use shadow root traversal\n- **elements**: add shadow root timeout, CSS restriction and context propagation\n- **tab**: add find_shadow_roots with OOPIF traversal and timeout\n- **elements**: add shadow DOM support\n\n### Fix\n\n- **docs**: replace shadow.find() with query() in all documentation\n- **tests**: replace shadow.find() with query() in integration tests\n- **elements**: use float timeout and add contextual WaitElementTimeout messages\n\n## 2.16.0 (2026-02-06)\n\n### Feat\n\n- add clear method for input and enhance page load state handling\n\n### Fix\n\n- **browser**: support secure websocket connections\n\n## 2.15.1 (2026-01-04)\n\n### Fix\n\n- filter Symbol properties from element query results\n\n## 2.15.0 (2025-12-24)\n\n### Feat\n\n- Implement incognito mode cookie retrieval for `tab.get_cookies()` and update related documentation\n\n### Fix\n\n- inconsistence in type checking\n- Dispatch `KEY_DOWN` and `KEY_UP` events for character typing\n\n## 2.14.0 (2025-12-10)\n\n### Feat\n\n- get_tab_by_target method added\n- get_tab_by_target method added\n\n### Fix\n\n- adding type: ignore in JavascriptDialogOpeningEvent object\n- adding type: ignore in JavascriptDialogOpeningEvent object\n\n## 2.13.1 (2025-12-07)\n\n### Fix\n\n- add stuck scroll detection and minimum flick distance to humanized scroll, and correct scroll distance calculation.\n\n## 2.13.0 (2025-12-07)\n\n### Feat\n\n- Implement humanized keyboard typing and physics-based scroll, and add iframe interaction support.\n\n## 2.12.4 (2025-11-29)\n\n### Fix\n\n- optimize iframe resolution logic by adjusting backend node ID checks and enhancing child frame handling\n- refine OOPIF resolution and frame attachment logic for improved handling of backend node IDs\n- enhance OOPIF target attachment logic for improved session handling\n\n## 2.12.3 (2025-11-27)\n\n### Fix\n\n- improve frame retrieval logic for better session handling\n\n## 2.12.2 (2025-11-19)\n\n### Fix\n\n- adjust find_elements_mixin.py to refine return types and defaults\n\n## 2.12.1 (2025-11-14)\n\n### Fix\n\n- continue cleanup process if temporary directory still exists\n- adjust sleep duration for Windows and enhance temp dir cleanup\n- enhance error handling for locked files on Windows systems\n- remove unnecessary retry_times parameter in file processing\n- ensure temp directory cleanup handles Chromium locked files\n- enhance element selection and text extraction for better stability\n- handle oopif targets\n- change way to interact with iframes\n\n### Refactor\n\n- refactor iframe context handling in FindElementsMixin class\n\n### Perf\n\n- update Chrome options for better memory management and stability\n\n## 2.12.0 (2025-11-04)\n\n### Feat\n\n- **execute_script**: validate element argument usage\n- **tab,element,chrome**: revert arguments and add Chromium paths\n- add a retry decorator for handling function execution failures\n\n### Fix\n\n- import TopLevelTargetRequired in test_browser_tab.py\n- allow one additional retry attempt in the retry decorator\n\n### Refactor\n\n- **tab,element**: simplify execute_script parameters\n- **element**: move and enhance execute_script from tab\n- **tab**: separate execute_script concerns and enhance with comprehensive options\n\n## 2.11.0 (2025-11-02)\n\n### Feat\n\n- add input handling functions and key constants for editing\n- add KeyboardAPI for simulating keyboard input actions\n- add KeyboardAPI integration for enhanced keyboard control\n\n### Fix\n\n- enhance text insertion and deprecate legacy key methods\n\n## 2.10.0 (2025-11-01)\n\n### Feat\n\n- add ScrollAPI for enhanced page scrolling capabilities\n\n## 2.9.3 (2025-10-30)\n\n### Refactor\n\n- keep take_screenshot consistent\n- refactor type hints for better clarity and future compatibility\n\n## 2.9.2 (2025-10-19)\n\n### Fix\n\n- update process creation to capture output and clean proxy format\n- preserve query and fragment in WebSocket URL for tabs\n\n### Refactor\n\n- remove debug logging for request status and network events\n- refactor logger messages to use consistent single quotes\n- fix merge conflicts\n- add logging for browser lifecycle and context management events\n- refactor proxy parsing logic for improved clarity and efficiency\n\n## 2.9.1 (2025-10-15)\n\n### Fix\n\n- change download event handling to use PageEvent instead of BrowserEvent\n\n### Refactor\n\n- use early return in setup proxy method\n\n## 2.9.0 (2025-10-05)\n\n### Feat\n\n- add configurable page load state\n\n## 2.8.2 (2025-10-03)\n\n### Fix\n\n- implement proxy authentication handling for browser tabs\n- map exception when try to take screenshot of an iframe\n\n## 2.8.1 (2025-09-27)\n\n### Fix\n\n- store the opened tab in the _tabs_opened dictionary\n- **elements**: correctly detect parenthesized XPath expressions\n\n### Refactor\n\n- simplify FindElementsMixin._get_expression_type startswith checks into single tuple\n\n## 2.8.0 (2025-08-28)\n\n### Feat\n\n- adding get_siblings_elements method\n- adding get_children_elements method\n- refactor Tab class to support optional WebSocket address handling\n- add WebSocket connection support for existing browser instances\n- add optional WebSocket address support in connection handler\n\n### Fix\n\n- add get siblings and get childen methods a raise_exc option\n- improving children and parent retrive docstring and creating a private generic method for then\n- using new execute_script public method\n- solving conflicts\n- rename pages fixtures files and adding a error test\n\n### Refactor\n\n- refactor Tab class to improve initialization and error handling\n- refactor Browser class to manage opened tabs and WebSocket setup\n- add new exception classes for connection and WebSocket errors\n\n## 2.7.0 (2025-08-22)\n\n### Feat\n\n- refactor WebElement methods to use a unified naming convention\n- add Response type and new bring_to_front method to Tab class\n- improve element interactability scripts\n\n### Fix\n\n- **browser**: add google-chrome-stable path for Arch Linux AUR package\n- run actions to fix badges\n- enforce combined condition logic in wait_until\n- **web_element**: raise WaitElementTimeout on wait_until timeout\n\n### Refactor\n\n- update command responses to use Response for empty responses\n- **webelement**: simplify wait_until condition mapping\n\n## 2.6.0 (2025-08-10)\n\n### Feat\n\n- add DownloadTimeout exception for file download timeouts\n- add context manager for handling file downloads in Tab class\n\n### Refactor\n\n- add type checking for connection handler in mixin class\n- add type overloads for event callback in Browser class\n\n## 2.5.0 (2025-08-07)\n\n### Feat\n\n- add HTTP client functionality using the browser's fetch API\n- add HTTP response object for browser-based fetch requests\n- implement Request class for HTTP requests using fetch API\n- add Request handling and improve network log retrieval methods\n\n### Fix\n\n- reject cookies with empty names during parsing in Request class\n- refactor imports to include NotRequired and TypedDict from typing_extensions\n- update imports to use typing_extensions for compatibility reasons\n- check for None in events_enabled before updating params\n- remove unused event type aliases and clean up imports\n\n### Refactor\n\n- depreciating headless argument in start method and adding it in to browser options properties\n- add asynchronous function for makeRequest in JavaScript\n- refactor imports for cleaner organization and improved clarity\n- refactor type hints in FindElementsMixin for clarity and type safety\n- refactor type hints and improve command method signatures\n- refactor event handling to use specific event types for clarity\n- refactor connection handler to use CDPEvent and typed commands\n- refactor storage command methods to return specific command types\n- refactor target command methods to use specific command types\n- refactor command return types to specific command classes\n- refactor page commands to use specific command types directly\n- refactor network commands to use specific command types\n- refactor input command methods to return specific command types\n- refactor fetch_commands to use updated type definitions\n- refactor enums to inherit from str for better compatibility\n- refactor DOM command types for improved code clarity and structure\n- refactor command and event parameter types for better typing\n- refactor command responses to use EmptyResponse where applicable\n- improve protocol types for target domain\n- improve protocol types for storage domain\n- refactor command response types for improved readability and consistency\n- improve protocol types for page domain\n- add IncludeWhitespace and RelationType enums to DOM types\n- improve protocol types for input domain\n- refactor AuthChallengeResponse and remove legacy definitions\n- remove legacy WindowBoundsDict for cleaner type definitions\n- add new TypedDicts and enums for runtime event parameters\n- refactor DOM event types and methods for better clarity and structure\n- refactor fetch command return types for better clarity and structure\n- enhance browser command functionality with new methods and types\n- add TypedDict and Enum definitions for emulation and debugging\n- improve protocol types for network domain\n\n## 2.4.0 (2025-08-01)\n\n### Feat\n\n- changing bool prefs to properties and adding support to user-data-dir preferences\n- adding prefs options customization\n- add overloads for find and query methods in FindElementsMixin\n- add method to retrieve parent element and its attributes\n- implements start_timeout option\n\n### Fix\n\n- adding typehint and fixing some codes\n- removing options preferences private attributes\n- set default URL to 'about:blank' in create_target method\n- change navigation when creating a new tab\n- add type hinting support and update project description\n\n### Refactor\n\n- remove redundant asterisk from find method overloads and reorganize query method overloads\n- refine type hint for response parameter and improve key check\n\n## 2.3.1 (2025-07-12)\n\n### Fix\n\n- refactor click_option_tag to use direct script reference\n- update script to use closest for more reliable DOM selection\n- improve selection script for higher accuracy\n- use correct class name and id selector in query()\n- add fetch command methods to handle request processing\n\n### Refactor\n\n- change body type from dict to string in fetch command parameters\n- refactor continue_request and fulfill_request to use options\n- enhance continue_request and fulfill_request with new options\n\n## 2.3.0 (2025-06-25)\n\n### Feat\n\n- **connection**: Upgrade adapt websockets version to 14.0\n\n### Fix\n\n- refine selector condition to include attributes check\n\n## 2.2.3 (2025-06-20)\n\n### Fix\n\n- fix contextmanager for file upload\n\n## 2.2.2 (2025-06-18)\n\n### Fix\n\n- fix call_function_on parameters order\n\n### Refactor\n\n- replace BeautifulSoup with custom HTML text extractor\n\n## 2.2.1 (2025-06-16)\n\n### Fix\n\n- fix call parameters order in call_function_on method\n\n## 2.2.0 (2025-06-15)\n\n### Feat\n\n- add method to retrieve non-extension opened tabs as Tab instances\n\n### Refactor\n\n- refactor attribute assignments to include type annotations\n- implement singleton pattern for Tab instances by target_id\n\n## 2.1.0 (2025-06-14)\n\n### Feat\n\n- add new script-related exception classes for better handling\n- add functions to clean scripts and check return statements\n- add methods to retrieve network response body and logs\n\n### Fix\n\n- click in the input before typing and fix documentation\n\n### Refactor\n\n- add overloads for execute_script to improve type safety\n\n## 2.0.1 (2025-06-08)\n\n### Fix\n\n- fix private proxy configuration\n\n## 2.0.0 (2025-06-08)\n\n### BREAKING CHANGE\n\n- pydoll v2 finished\n\n### Feat\n\n- intuitive way to interact with iframes\n- refactor Keys class to Key and add utility methods for enums\n- add Event TypedDict for standardized event structure\n- add TargetEvent enum for Chrome DevTools Protocol events\n- add StorageEvent enumeration for Chrome DevTools Protocol events\n- add RuntimeEvent enumeration for Chrome DevTools Protocol events\n- add PageEvent enumeration for Chrome DevTools Protocol events\n- add NetworkEvent enumeration for Chrome DevTools Protocol events\n- add InputEvent enum for Chrome DevTools input events\n- add FetchEvent enumeration for Chrome DevTools Protocol events\n- add DomEvent enumeration for Chrome DevTools Protocol events\n- add BrowserEvent enum for Chrome DevTools protocol events\n- add methods to enable and disable the runtime domain commands\n- add new enums for whitespace, axes, pseudo types, and modes\n- add DOM response types and corresponding response classes\n- add DOM command types and parameter definitions for pydoll\n- add enums for key, mouse, touch, and drag event types\n- add input command types for touch, mouse, and keyboard events\n- enhance TargetCommands class with new methods for targets management\n- add TypedDicts for target response types and browser contexts\n- add TypedDict definitions for target command parameters\n- add storage-related enumerations for bucket durability and types\n- enhance StorageCommands with new methods for data management\n- add storage response types and related classes for handling data\n- add storage command types using TypedDict for structured params\n- add new enumeration classes for serialization and object types\n- add runtime response types for handling various object previews\n- add initial runtime command types for protocol handling\n- add constants for various encoding, formats, and policies\n- add TypedDict definitions for page response types and results\n- add typed dictionaries for various page command parameters\n- add new command parameter classes for network resource handling\n- add TypedDict definitions for network response types\n- organize command types into structured imports and exports\n- add network command types and parameters for cookie management\n- add enums for cookie priorities, connection types, and encodings\n- add response classes for browser window target retrieval\n- setup mkdocs and install related packages\n- add async text property for retrieving element text\n\n### Fix\n\n- remove target directory from .gitignore file\n- fix typo in USB_UNRESTRICTED constant for consistency\n- add new network command parameters and methods for cookies\n- change postData type from dict to string in ContinueRequestParams\n\n### Refactor\n\n- refactor screenshot path handling and enhance error checking\n- refactor type hints from List to built-in list for consistency\n- refine XPath condition handling and ensure integer coordinates\n- refactor condition checks to ensure against None values\n- refactor exception handling and add browser path validation function\n- rename BrowserOptionsManager to ChromiumOptionsManager\n- refactor Edge class to use ChromiumOptionsManager and simplify path validation\n- refactor Chrome class to use Chromium-specific options manager\n- refactor Browser class to use options manager and improve methods\n- refactor Options class to ChromiumOptions and use type hints\n- refactor to create ChromiumOptionsManager for better clarity\n- add abstract base classes for browser options management\n- use `message.get('id')` for safer ID checks in response\n- refactor message handling to support multiple message types\n- refactor element finding methods for enhanced flexibility and clarity\n- rename method for better clarity in captcha element handling\n- refactor type hints for event callback parameters and options\n- simplify ping call by inlining WebSocketClientProtocol cast\n- refactor EventsManager to use typed Event objects consistently\n- add runtime events management to the Tab class functionality\n- update event callback signatures for better type handling\n- remove unused import of Response in runtime_commands.py\n- add Response import to page_commands for improved functionality\n- refactor response classes to use TypedDict for better typing\n- refactor WebElement class to organize exception imports clearly\n- refactor exception handling in FindElementsMixin class\n- refactor exception handling to use custom timeout and connection errors\n- remove unused import statements in events_manager.py\n- refactor error handling to use specific exceptions for clarity\n- refactor error handling to use custom exception for arguments\n- fix PermissionError raising in TempDirectoryManager class\n- refactor error handling to use specific exceptions for clarity\n- handle unsupported OS with a custom exception in Edge class\n- raise UnsupportedOS exception for unsupported operating systems\n- refactor browser error handling and improve method return types\n- refactor exception classes to improve organization and clarity\n- refactor element finding methods to use updated command structure\n- refactor WebElement class for improved structure and clarity\n- refactor import statements and clean up code formatting\n- refactor command imports and enhance download behavior method\n- refactor Tab import and update FetchCommands method calls\n- refactor ConnectionHandler docstrings for clarity and conciseness\n- refactor command and event managers for improved type safety\n- refactor ConnectionHandler to improve WebSocket management and clarity\n- add Tab class for managing browser tabs via CDP integration\n- enhance TempDirectoryManager with detailed docstrings and type hints\n- refactor ProxyManager to enhance proxy credential handling\n- refactor Browser class to enhance automation capabilities and structure\n- move commands to a different module\n- define base structures for commands and responses in protocol\n- import Rect from dom_commands_types for response handling\n- refactor cookie-related types for improved clarity and consistency\n- remove unnecessary whitespace in docstring of InputCommands class\n- refactor DOM commands to improve structure and add functionality\n- refactor InputCommands to enhance user input simulation methods\n- add CookieParam TypedDict to define cookie attributes\n- add new runtime command methods for JavaScript bindings and promises\n- remove unused method to clear accepted encodings in network commands\n- update ResetPermissionsParams to use NotRequired for context ID\n- refactor PageCommands to improve structure and add type hints\n- simplify import statements by using wildcard imports for responses\n- add new response types and update existing response classes\n- consolidate command imports using wildcard imports for clarity\n- correct post_data type from dict to str in FetchCommands class\n- refactor NetworkCommands to use structured command parameters\n- refactor fetch command methods to use static methods directly\n- refactor BrowserCommands to use static methods and improve clarity\n- refactor response imports and update __all__ definitions\n- refactor import statements for better readability and structure\n- refactor import statements for consistency in response types\n- refactor import and rename EnableParams to FetchEnableParams\n- refactor import statement for CommandParams module path\n- refactor fetch command templates to use Command class\n- add enums for window states, download behaviors, and permissions\n- remove unused enum imports and rename base_types module\n- refactor command structures for better organization and clarity\n- rename command and response modules for better clarity\n- refactor imports for better organization and readability\n- add browser command methods for version, permissions, and downloads\n- add command and response types for protocol implementation\n- refactor execute_command to use type annotations for clarity\n- refactor command methods to specify response types in BrowserCommands\n- refactor command structures and introduce base CommandParams class\n- refactor browser command constants to use Command class type\n- refactor connection imports and rename manager files for clarity\n- refactor BrowserType import to a common constants module\n- refactor browser modules to use the new chromium structure\n- refactor element imports and remove deprecated element file\n- refactor import paths to use the protocol submodule structure\n- move command files to the protocol directory for better structure\n- rename insert_text to paste_text and remove unused files\n- refactor the `InputCommands` class to enhance clarity and simplicity in its operations\n- add deprecation warning to get_element_text()\n\n## 1.7.0 (2025-04-06)\n\n### Feat\n\n- refactor captcha handling with adjustable wait times and parameters\n\n## 1.6.0 (2025-04-06)\n\n### Feat\n\n- add connect method to handle existing port scenarios\n- create enable_auto_solve_cloudflare_captcha method\n- add context manager to bypass Cloudflare Turnstile captcha\n\n## 1.5.1 (2025-03-31)\n\n### Fix\n\n- handle headers input as list or dictionary in fetch command\n\n## 1.5.0 (2025-03-26)\n\n### Feat\n\n- add flag to run browser on headless mode on start function\n\n### Fix\n\n- Wait for the file `CrashpadMetrics-active.pma` to be deoccupied and cleaned up\n- Catch websockets.ConnectionClosed errors on duplicate close()\n- move connection closed log inside if statement\n\n## 1.4.0 (2025-03-23)\n\n### Feat\n\n- Update initialize_options method to allow optional browser_type parameter\n- Refactor Edge browser options handling to use EdgeOptions class\n- Supports initialization options based on browser type\n- Edge browser constructors to support optional connection port parameters\n- Add Microsoft Edge browser support\n- 为 Edge 浏览器添加默认用户数据目录支持\n- Add Microsoft Edge browser support\n\n### Refactor\n\n- Clean up imports and improve code formatting across browser modules\n- Simplify user data directory setup and enhance Edge browser path handling\n\n## 1.3.3 (2025-03-18)\n\n### Fix\n\n- solve browser invalid domain events issue\n- improve process termination\n- improve process management and deactivate websockets connection size limit\n\n### Refactor\n\n- import commands and evebts from __init__.py\n\n## 1.3.2 (2025-03-13)\n\n### Fix\n\n- fixed the tests and used lint for the OS multi path support\n- support multiple default Chrome paths on each OS\n\n## 1.3.1 (2025-03-12)\n\n### Fix\n\n- remove unnecessary encoding from screenshot response data\n\n## 1.3.0 (2025-03-12)\n\n### Feat\n\n- add method to retrieve screenshot as base64 encoded string\n\n## 1.2.4 (2025-03-11)\n\n### Fix\n\n- refactor Chrome constructor to use Optional for parameters\n\n## 1.2.3 (2025-03-11)\n\n### Fix\n\n- refactor proxy configuration retrieval for cleaner code flow\n\n## 1.2.2 (2025-03-10)\n\n### Fix\n\n- Get file extension from file path and changes use of reserved word 'format' to 'fmt'\n\n## 1.2.1 (2025-03-09)\n\n### Fix\n\n- resolve issue #29 where browser path was not found on macOS\n- Quickstart code given in README is wrong\n\n## 1.2.0 (2025-02-11)\n\n### Feat\n\n- add close method and command to Page class functionality\n\n## 1.1.0 (2025-02-11)\n\n### Feat\n\n- add method to retrieve Page instance by its ID in Browser class\n\n## 1.0.1 (2025-02-10)\n\n### Fix\n\n- add dialog property to ConnectionHandler and manage dialog state\n\n## 1.0.0 (2025-02-05)\n\n### BREAKING CHANGE\n\n- now you'll have to use By.CSS_SELECTOR instead of By.CSS\n\n### Feat\n\n- refactor import and export statements for better readability\n- update changelog for version 0.7.0 and fix dependency versions\n- add ping method to ConnectionHandler for browser connectivity check\n- add tests for BrowserCommands in test_browser_commands.py\n\n### Fix\n\n- add initial module files for commands, connection, events, and mixins\n- add connection port parameter to Chrome browser initialization\n- use deepcopy for templates to prevent mutation issues\n\n### Refactor\n\n- rename constant CSS to CSS_SELECTOR\n- add command imports and remove obsolete connection handler code\n- refactor methods to be static in ConnectionHandler class\n- refactor proxy configuration and cleanup logic in Browser class\n- refactor ConnectionHandler to improve WebSocket management logic\n- refactor Browser class initialization for better clarity and structure\n- refactor Browser initialization to enhance flexibility and defaults\n- refactor import statement for ConnectionHandler module\n- refactor import paths for ConnectionHandler in browser modules\n- implement ConnectionHandler for WebSocket browser automation\n- implement command and event management for asynchronous processing\n- remove unnecessary logging for WebSocket address fetching\n- refactor Chrome class to use BrowserOptionsManager for path validation\n- implement proxy and browser management in the new managers module\n- refactor Browser class to use manager classes for better structure\n- refactor DOM command scripts for clarity and efficiency\n\n## 0.7.0 (2024-12-09)\n\n### Feat\n\n- autoremove dialog from connection_handler when closed\n- add handle_dialog method to PageCommands class\n- add dialog handling methods to Page class\n- add support for handling JavaScript dialog opening events\n- refactor network response handling for base64 encoding support\n- add clipping option for screenshots and implement element capture\n\n### Fix\n\n- index error on method get_dialog_message\n- update screenshot format from 'jpg' to 'jpeg' for consistency\n- handle potential IndexError when retrieving valid page targetId\n- filter valid pages using URL condition instead of title check\n\n### Refactor\n\n- run ruff formatter to ensure code consistency\n- run ruff formatter to ensure code consistency\n- change screenshot format from PNG to JPG in commands and element\n\n## 0.6.0 (2024-11-18)\n\n### Feat\n\n- add callback ID handling for page load events in Page class\n- update event registration to return callback IDs and add removal\n- refactor DOM commands to use object_id instead of node_id\n\n### Fix\n\n- refactor page navigation and loading logic for efficiency\n- add page reload after navigating to a new URL in Page class\n- refactor URL navigation to use evaluate_script for efficiency\n- implement page refresh on URL unchanged and add navigation event\n- update object ID reference in Page class for clarity\n- refactor element search logic to simplify error handling\n- DomCommands using `object_id` instead of `node_id` to prevent bugs\n- handle OSError when cleaning up temporary directories in Browser\n\n### Refactor\n\n- change error log to warning for missing callback ID\n- refactor DOM command scripts for improved readability and reuse\n- rename methods for clarity and consistency in WebElement class\n- refactor parameter names for consistency in target methods\n- normalize variable naming for consistency in fetch commands\n\n## 0.5.1 (2024-11-12)\n\n### Fix\n\n- simplify outer HTML retrieval for consistent object handling\n- refactor click method to check option tag earlier in flow\n- refactor bounding box retrieval to access nested response value\n- handle KeyError instead of IndexError for element bounds retrieval\n- enhance DOM command methods and rename for clarity and consistency\n- add JavaScript bounding box retrieval for web elements\n- remove redundant top-checks for element clicks in WebElement\n\n## 0.5.0 (2024-11-11)\n\n### Feat\n\n- add method to generate command for calling a function on an object\n- implement script execution and visibility checks in click method\n- add JavaScript functions for element visibility and interaction\n\n### Refactor\n\n- enhance exception classes with descriptive error messages\n- simplify command creation by using RuntimeCommands.evaluate_script\n- refactor JavaScript execution and introduce runtime commands\n\n## 0.4.4 (2024-11-11)\n\n### Fix\n\n- remove redundant DOM content loaded event handling logic\n\n## 0.4.3 (2024-11-11)\n\n### Fix\n\n- rename event variables for clarity and improve timeout handling\n\n### Refactor\n\n- remove debug print statement from connection event handling\n\n## 0.4.2 (2024-11-11)\n\n### Fix\n\n- update event handling to use DOM_CONTENT_LOADED for page load\n- convert Browser context management to async methods\n\n### Refactor\n\n- fix string formatting in logger info message for clarity\n\n## 0.4.1 (2024-11-08)\n\n### Fix\n\n- fixes workflow removing unnecessary hifen\n- reduce sleep duration in key press handling for improved speed\n\n## 0.4.0 (2024-11-08)\n\n### Feat\n\n- add type_keys method for realistic key input simulation\n\n## 0.3.1 (2024-11-08)\n\n### Fix\n\n- addning new package version\n- removing encode utf8 in get_pdf_base64\n\n## 0.3.0 (2024-11-08)\n\n### Feat\n\n- set_download_path added in browser class methods\n\n## 0.2.0 (2024-11-08)\n\n### Feat\n\n- dynamic lib version using pyproject\n\n## 0.1.1 (2024-11-07)\n\n### Fix\n\n- ensure browser process terminates after executing close command\n\n## 0.1.0 (2024-11-07)\n\n### Feat\n\n- add method to delete all cookies from the browser session\n- add is_enabled property to check element's enabled status\n- add option to raise exception in wait_element method\n- add method to set browser download path via command\n- refactor text extraction using BeautifulSoup for accuracy\n- add method to get properties and improve XPath handling\n- refactor text retrieval methods and improve code readability\n- add timeout parameter to page navigation and loading methods\n- add cookie management and scroll into view functionality\n- add method to retrieve page PDF data as base64 string\n- add async property to retrieve inner HTML of the element\n- add async page_source property to retrieve page source code\n- add async property to retrieve the current page URL\n- add method to find multiple DOM elements using selectors\n- refactor WebElement to use FindElementsMixin for clarity\n- add FindElementsMixin for asynchronous DOM element handling\n- add methods to retrieve network response bodies from logs\n- add method to retrieve matching network logs from the page\n- add cookie management methods to the Browser class\n- add ElementNotFound exception to handle missing elements\n- add value property and handle option tag clicks in WebElement\n- rename FIND_ELEMENT_XPATH_TEMPLATE to EVALUATE_TEMPLATE\n- add exception handling for element not found in find_element method\n- downgrade Python version requirement to 3.10 in pyproject.toml\n- add async function to fetch browser WebSocket address\n- simplify text input handling by using insert_text command\n- add TargetCommands class for managing target operations\n- add method to generate command for disabling the Page domain\n- add method to generate text insertion commands for inputs\n- add Page class to manage browser page interactions and events\n- add page management methods to the Browser class\n- add detailed logging for command responses and event handling\n- add event classes for browser, DOM, fetch, and network actions\n- add NetworkCommands class for managing network operations\n- implement fetch command methods for handling requests and responses\n- add method to enable DOM domain events in DomCommands class\n- add proxy configuration and fetch event handling to Browser\n- refactor connection errors to use custom exceptions for clarity\n- add methods to clear callbacks and close WebSocket connection\n- remove unnecessary newline at the end of PageEvents class file\n- add context managers and async file handling for efficiency\n- implement singleton pattern and prevent multiple initializations\n- add dynamic connection port handling for browser instance\n- add temporary directory management for browser session storage\n- add logging for connection events and command executions\n- add PageEvents class with PAGE_LOADED event constant\n- add temporary callback option to event registration method\n- add page event handling and improve loading timeout management\n- add utility function to decode base64 images to bytes\n- add WebElement class for handling browser elements asynchronously\n- add enumeration for selector types in constants module\n- add PageCommands class for browser page control functions\n- add InputCommands class for handling mouse and keyboard events\n- implement DOM commands for interacting with web elements\n- refactor BrowserCommands to include new window management methods\n- implement some basic methods to navigate and control the browser instance\n- enhance ConnectionHandler with detailed docstrings for methods\n- add .gitignore, .python-version, and poetry.lock files\n\n### Fix\n\n- browser context now uses the storage commands to get cookies, while the page context us cookies, while page context uses network\n- update cookie retrieval to use NetworkCommands for consistency\n- remove download path method from Browser and add to Page class\n- add options to disable first-run and browser check flags\n- handle KeyError when retrieving network response bodies\n- use get() to safely retrieve attributes in WebElement class\n- rename class attribute retrieval for clarity and consistency\n- enhance get_properties and simplify text retrieval method\n- enhance create_web_element call with additional value parameter\n- fix incorrect key access in JavaScript evaluation result\n- update cookie management to clear browser cookies correctly\n- filter pages by title instead of URL in Browser class\n- filter out non-page entries when fetching valid page IDs\n- xpath element solved\n- refactor event callback storage to use unique callback IDs\n- add JavaScript execution method and enhance click offsets\n- simplify response handling and improve event callback structure\n- reorder page event enabling to ensure proper browser startup\n- add JSON handling and improve WebSocket command execution\n\n### Refactor\n\n- improve WebElement representation and handle None for nodeValue\n- add newline at end of file for ElementNotFound exception class\n- remove unused aiohttp import and clean up whitespace\n- remove unnecessary blank lines in storage.py for clarity\n- fix missing newline at the end of the file in page.py\n- remove unnecessary whitespace in InputCommands class methods\n- refactor DOM command methods for improved clarity and usability\n- refactor Page class to inherit from FindElementsMixin\n- refactor code to remove duplicate import of StorageCommands\n- clarify error messages for command and callback validation\n- refactor ConnectionHandler to simplify initialization and connect logic\n- remove unnecessary whitespace in element.py for cleaner code\n- refactor WebElement to enhance attribute retrieval methods\n- refactor connection handling and improve error messaging\n- refactor Browser class to use abstract base class and commands\n" }, { "path": "CONTRIBUTING.md", "content": "# Contributing Guide\n\nThank you for your interest in contributing to the project! This document provides guidelines and instructions to help you contribute effectively.\n\n## Table of Contents\n\n- [Environment Setup](#environment-setup)\n- [Development Workflow](#development-workflow)\n- [Code Standards](#code-standards)\n- [Testing](#testing)\n- [Commit Messages](#commit-messages)\n- [Pull Request Process](#pull-request-process)\n\n## Environment Setup\n\n### Prerequisites\n\n- Python 3.10 or higher\n- [Poetry](https://python-poetry.org/docs/#installation) for dependency management\n\n### Installation\n\n1. Clone the repository:\n ```bash\n git clone [REPOSITORY_URL]\n cd pydoll\n ```\n\n2. Install dependencies using Poetry:\n ```bash\n poetry install\n ```\n\n3. Activate the virtual environment:\n ```bash\n poetry shell\n ```\n\n## Development Workflow\n\n1. Create a new branch for your contribution:\n ```bash\n git checkout -b feature/your-feature-name\n ```\n or\n ```bash\n git checkout -b fix/your-fix-name\n ```\n\n2. Make your changes following the code and testing guidelines.\n\n3. Check your code using the linter:\n ```bash\n poetry run task lint\n ```\n\n4. Format your code:\n ```bash\n poetry run task format\n ```\n\n5. Run the tests to ensure everything is working:\n ```bash\n poetry run task test\n ```\n\n6. Commit your changes following the commit conventions (see below).\n\n7. Push your changes and open a Pull Request.\n\n## Code Standards\n\nThis project uses [Ruff](https://github.com/charliermarsh/ruff) for linting and code formatting. The code standards are defined in the `pyproject.toml` file.\n\n### Linting and Formatting\n\nTo check if your code follows the standards:\n\n```bash\npoetry run task lint\n```\n\nTo automatically fix some issues and format your code:\n\n```bash\npoetry run task format\n```\n\n**Important:** Make sure to resolve all linting issues before submitting your changes. Code that doesn't pass the linting checks will not be accepted.\n\n## Testing\n\n### Writing Tests\n\nFor each new feature or modification, it is **mandatory** to write corresponding tests. We use `pytest` for testing.\n\n- Tests should be placed in the `tests/` directory\n- Test file names should start with `test_`\n- Test function names should start with `test_`\n\n### Running Tests\n\nTo run all tests:\n\n```bash\npoetry run task test\n```\n\nThis will also generate a code coverage report (HTML) that can be viewed in the `htmlcov/` folder.\n\n## Commit Messages\n\nThis project follows the [Conventional Commits](https://www.conventionalcommits.org/) standard for commit messages. We use the `commitizen` tool to facilitate the creation of standardized commits.\n\n### Commit Message Structure\n\n```\n[optional scope]: \n\n[optional body]\n\n[optional footer(s)]\n```\n\n### Commit Types\n\n- **feat**: A new feature\n- **fix**: A bug fix\n- **docs**: Documentation-only changes\n- **style**: Changes that do not affect the meaning of the code (whitespace, formatting, etc.)\n- **refactor**: A code change that neither fixes a bug nor adds a feature\n- **perf**: A code change that improves performance\n- **test**: Adding or correcting tests\n- **build**: Changes that affect the build system or external dependencies\n- **ci**: Changes to CI configuration files\n- **chore**: Other changes that don't modify src or test files\n\n### Examples of Good Commit Messages\n\n```\nfeat(parser): add ability to parse arrays\n```\n\n```\nfix(networking): resolve connection timeout issue\n\nA problem was identified in the networking library that\ncaused unexpected timeouts. This change increases the\ndefault timeout from 10s to 30s.\n```\n\n## Pull Request Process\n\n1. Verify that your code passes all tests and linting checks.\n2. Push your branch to the repository.\n3. Open a Pull Request to the main branch.\n4. In the PR description, clearly explain what was changed and why.\n5. Link any related issues to your PR.\n6. Wait for the code review. Read the comments and make necessary changes.\n\n## Questions?\n\nIf you have questions or need help, open an issue in the repository or contact the project maintainers.\n\n---\n\nWe appreciate your contributions to make this project better! " }, { "path": "LICENSE", "content": "The MIT License (MIT)\n\nCopyright © 2025 AutoscrapeLabs\n\nPermission 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:\n\nThe above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.\n\nTHE 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.\n" }, { "path": "README.md", "content": "

\n \"Pydoll
\n

\n

Async-native, fully typed, built for evasion and performance.

\n\n

\n \n \n \n \n \"Tests\"\n \"Ruff\n \"MyPy\n \"Python= 3.10\">\n \"Ask\n

\n\n

\n Documentation ·\n Getting Started ·\n Features ·\n Support\n

\n\nPydoll automates Chromium-based browsers (Chrome, Edge) by connecting directly to the Chrome DevTools Protocol over WebSocket. No WebDriver binary, no `navigator.webdriver` flag, no compatibility issues.\n\nIt combines a high-level API for common tasks with low-level CDP access for fine-grained control over network, fingerprinting, and browser behavior. The entire codebase is async-native and fully type-checked with mypy.\n\n### Top Sponsors\n\n\n \"The\n\n\nRead a full review of Pydoll on The Web Scraping Club, the #1 newsletter dedicated to web scraping.\n\n### Sponsors\n\n\n \n \n \n \n \n
\"Thordata\"\"CapSolver\"\"LambdaTest\"
\n\n[Learn more about our sponsors](SPONSORS.md) · [Become a sponsor](https://github.com/sponsors/thalissonvs)\n\n### Why Pydoll\n\n- **Stealth-first**: Human-like mouse movement, realistic typing, and granular [browser preference](https://pydoll.tech/docs/features/configuration/browser-preferences/) control for fingerprint management.\n- **Async and typed**: Built on `asyncio` from the ground up, 100% type-checked with `mypy`. Full IDE autocompletion and static error checking.\n- **Network control**: [Intercept](https://pydoll.tech/docs/features/network/interception/) requests to block ads/trackers, [monitor](https://pydoll.tech/docs/features/network/monitoring/) traffic for API discovery, and make [authenticated HTTP requests](https://pydoll.tech/docs/features/network/http-requests/) that inherit the browser session.\n- **Shadow DOM and iframes**: Full support for [shadow roots](https://pydoll.tech/docs/deep-dive/architecture/shadow-dom/) (including closed) and cross-origin iframes. Discover, query, and interact with elements inside them using the same API.\n- **Ergonomic API**: `tab.find()` for most cases, `tab.query()` for complex [CSS/XPath selectors](https://pydoll.tech/docs/deep-dive/guides/selectors-guide/).\n\n## Installation\n\n```bash\npip install pydoll-python\n```\n\nNo WebDriver binaries or external dependencies required.\n\n## What's New\n\n
\nHAR Network Recording\n
\n\nRecord network activity during a browser session and export as HAR 1.2. Replay recorded requests to reproduce exact API sequences.\n\n```python\nfrom pydoll.browser.chromium import Chrome\n\nasync with Chrome() as browser:\n tab = await browser.start()\n\n async with tab.request.record() as capture:\n await tab.go_to('https://example.com')\n\n capture.save('flow.har')\n print(f'Captured {len(capture.entries)} requests')\n\n responses = await tab.request.replay('flow.har')\n```\n\nFilter by resource type:\n\n```python\nfrom pydoll.protocol.network.types import ResourceType\n\nasync with tab.request.record(\n resource_types=[ResourceType.FETCH, ResourceType.XHR]\n) as capture:\n await tab.go_to('https://example.com')\n```\n\n[HAR Recording Docs](https://pydoll.tech/docs/features/network/network-recording/)\n
\n\n
\nPage Bundles\n
\n\nSave the current page and all its assets (CSS, JS, images, fonts) as a `.zip` bundle for offline viewing. Optionally inline everything into a single HTML file.\n\n```python\nawait tab.save_bundle('page.zip')\nawait tab.save_bundle('page-inline.zip', inline_assets=True)\n```\n\n[Screenshots, PDFs & Bundles Docs](https://pydoll.tech/docs/features/automation/screenshots-and-pdfs/)\n
\n\n
\nShadow DOM Support\n
\n\nFull Shadow DOM support, including closed shadow roots. Because Pydoll operates at the CDP level (below JavaScript), the `closed` mode restriction doesn't apply.\n\n```python\nshadow = await element.get_shadow_root()\nbutton = await shadow.query('.internal-btn')\nawait button.click()\n\n# Discover all shadow roots on the page\nshadow_roots = await tab.find_shadow_roots()\nfor sr in shadow_roots:\n checkbox = await sr.query('input[type=\"checkbox\"]', raise_exc=False)\n if checkbox:\n await checkbox.click()\n```\n\nHighlights:\n- Closed shadow roots work without workarounds\n- `find_shadow_roots()` discovers every shadow root on the page\n- `timeout` parameter for polling until shadow roots appear\n- `deep=True` traverses cross-origin iframes (OOPIFs)\n- Standard `find()`, `query()`, `click()` API inside shadow roots\n\n```python\n# Cloudflare Turnstile inside a cross-origin iframe\nshadow_roots = await tab.find_shadow_roots(deep=True, timeout=10)\nfor sr in shadow_roots:\n checkbox = await sr.query('input[type=\"checkbox\"]', raise_exc=False)\n if checkbox:\n await checkbox.click()\n```\n\n[Shadow DOM Docs](https://pydoll.tech/docs/deep-dive/architecture/shadow-dom/)\n
\n\n
\nHumanized Mouse Movement\n
\n\nMouse operations produce human-like cursor movement by default:\n\n- **Bezier curve paths** with asymmetric control points\n- **Fitts's Law timing**: duration scales with distance\n- **Minimum-jerk velocity**: bell-shaped speed profile\n- **Physiological tremor**: Gaussian noise scaled with velocity\n- **Overshoot correction**: ~70% chance on fast movements, then corrects back\n\n```python\nawait tab.mouse.move(500, 300)\nawait tab.mouse.click(500, 300)\nawait tab.mouse.drag(100, 200, 500, 400)\n\nbutton = await tab.find(id='submit')\nawait button.click()\n\n# Opt out when speed matters\nawait tab.mouse.click(500, 300, humanize=False)\n```\n\n[Mouse Control Docs](https://pydoll.tech/docs/features/automation/mouse-control/)\n
\n\n## Getting Started\n\n```python\nimport asyncio\nfrom pydoll.browser import Chrome\nfrom pydoll.constants import Key\n\nasync def google_search(query: str):\n async with Chrome() as browser:\n tab = await browser.start()\n await tab.go_to('https://www.google.com')\n\n search_box = await tab.find(tag_name='textarea', name='q')\n await search_box.insert_text(query)\n await tab.keyboard.press(Key.ENTER)\n\n first_result = await tab.find(\n tag_name='h3',\n text='autoscrape-labs/pydoll',\n timeout=10,\n )\n await first_result.click()\n\n await tab.find(id='repository-container-header', timeout=10)\n print(f\"Page loaded: {await tab.title}\")\n\nasyncio.run(google_search('pydoll site:github.com'))\n```\n\n## Features\n\n
\nHybrid Automation (UI + API)\n
\n\nUse UI automation to pass login flows (CAPTCHAs, JS challenges), then switch to `tab.request` for fast API calls that inherit the full browser session: cookies, headers, and all.\n\n```python\n# Log in via UI\nawait tab.go_to('https://my-site.com/login')\nawait (await tab.find(id='username')).type_text('user')\nawait (await tab.find(id='password')).type_text('pass123')\nawait (await tab.find(id='login-btn')).click()\n\n# Make authenticated API calls using the browser session\nresponse = await tab.request.get('https://my-site.com/api/user/profile')\nuser_data = response.json()\n```\n[Hybrid Automation Docs](https://pydoll.tech/docs/features/network/http-requests/)\n
\n\n
\nNetwork Interception and Monitoring\n
\n\nMonitor traffic for API discovery or intercept requests to block ads, trackers, and unnecessary resources.\n\n```python\nimport asyncio\nfrom pydoll.browser.chromium import Chrome\nfrom pydoll.protocol.fetch.events import FetchEvent, RequestPausedEvent\nfrom pydoll.protocol.network.types import ErrorReason\n\nasync def block_images():\n async with Chrome() as browser:\n tab = await browser.start()\n\n async def block_resource(event: RequestPausedEvent):\n request_id = event['params']['requestId']\n resource_type = event['params']['resourceType']\n\n if resource_type in ['Image', 'Stylesheet']:\n await tab.fail_request(request_id, ErrorReason.BLOCKED_BY_CLIENT)\n else:\n await tab.continue_request(request_id)\n\n await tab.enable_fetch_events()\n await tab.on(FetchEvent.REQUEST_PAUSED, block_resource)\n\n await tab.go_to('https://example.com')\n await asyncio.sleep(3)\n await tab.disable_fetch_events()\n\nasyncio.run(block_images())\n```\n[Network Monitoring](https://pydoll.tech/docs/features/network/monitoring/) | [Request Interception](https://pydoll.tech/docs/features/network/interception/)\n
\n\n
\nBrowser Fingerprint Control\n
\n\nGranular control over [browser preferences](https://pydoll.tech/docs/features/configuration/browser-preferences/): hundreds of internal Chrome settings for building consistent fingerprints.\n\n```python\noptions = ChromiumOptions()\n\noptions.browser_preferences = {\n 'profile': {\n 'default_content_setting_values': {\n 'notifications': 2,\n 'geolocation': 2,\n },\n 'password_manager_enabled': False\n },\n 'intl': {\n 'accept_languages': 'en-US,en',\n },\n 'browser': {\n 'check_default_browser': False,\n }\n}\n```\n[Browser Preferences Guide](https://pydoll.tech/docs/features/configuration/browser-preferences/)\n
\n\n
\nConcurrency, Contexts and Remote Connections\n
\n\nManage [multiple tabs](https://pydoll.tech/docs/features/browser-management/tabs/) and [browser contexts](https://pydoll.tech/docs/features/browser-management/contexts/) (isolated sessions) concurrently. Connect to browsers running in Docker or remote servers.\n\n```python\nasync def scrape_page(url, tab):\n await tab.go_to(url)\n return await tab.title\n\nasync def concurrent_scraping():\n async with Chrome() as browser:\n tab_google = await browser.start()\n tab_ddg = await browser.new_tab()\n\n results = await asyncio.gather(\n scrape_page('https://google.com/', tab_google),\n scrape_page('https://duckduckgo.com/', tab_ddg)\n )\n print(results)\n```\n[Multi-Tab Management](https://pydoll.tech/docs/features/browser-management/tabs/) | [Remote Connections](https://pydoll.tech/docs/features/advanced/remote-connections/)\n
\n\n
\nRetry Decorator\n
\n\nThe `@retry` decorator supports custom recovery logic between attempts (e.g., refreshing the page, rotating proxies) and exponential backoff.\n\n```python\nfrom pydoll.decorators import retry\nfrom pydoll.exceptions import ElementNotFound, NetworkError\n\n@retry(\n max_retries=3,\n exceptions=[ElementNotFound, NetworkError],\n on_retry=my_recovery_function,\n exponential_backoff=True\n)\nasync def scrape_product(self, url: str):\n # scraping logic\n ...\n```\n[Retry Decorator Docs](https://pydoll.tech/docs/features/advanced/decorators/)\n
\n\n---\n\n## Contributing\n\nContributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n## Support\n\nIf you find Pydoll useful, consider [sponsoring the project on GitHub](https://github.com/sponsors/thalissonvs).\n\n## License\n\n[MIT License](LICENSE)\n" }, { "path": "README_zh.md", "content": "

\n \"Pydoll
\n

\n

Pydoll: Automate the Web, Naturally

\n\n

\n \n \n \n \n \"Tests\"\n \"Ruff\n \"MyPy\n \"Python= 3.10\">\n \"Ask\n

\n\n\n

\n 📖 文档 •\n 🚀 快速上手 •\n ⚡ 高级特性 •\n 🤝 贡献 •\n 💖 赞助我\n

\n\n- [English](README.md)\n\n设想以下场景：你需要实现浏览器任务的自动化操作——无论是测试Web应用程序、从网站采集数据，还是批量处理重复性流程。传统方法往往需要配置外部驱动程序、进行复杂的系统设置，还可能面临诸多兼容性问题。\n\n**Pydoll的诞生就是解决这些问题!!!**\n\nPydoll 采用全新设计理念，从零构建，直接对接 Chrome DevTools Protocol（CDP），无需依赖外部驱动。 这种精简的实现方式，结合高度拟真的点击、导航及元素交互机制，使其行为与真实用户几乎毫无区别。\n\n我们坚信，真正强大的自动化工具，不应让用户困于繁琐的配置学习，也不该让用户疲于应对反爬系统的风控。使用Pydoll，你只需专注核心业务逻辑——让自动化回归本质，而非纠缠于底层技术细节或防护机制。\n\n
\n

做一个好人，给我们一个星星 ⭐

\n 没有星星，就没有Bug修复。开玩笑的（也许）\n
\n\n## 🌟 Pydoll 的核心优势\n\n- **零 WebDriver 依赖**：彻底告别驱动兼容性烦恼\n- **类人交互引擎**：能够通过行为验证码如 reCAPTCHA v3 或 Turnstile，取决于 IP 声誉和交互模式\n- **异步高性能**：支持高速自动化与多任务并行处理\n- **拟真交互体验**：完美复刻真实用户行为模式\n- **极简部署**：安装即用，开箱即自动化\n\n## 最新功能\n\n### 类人页面滚动 —— 像真实用户一样滚动！\n\n现在你可以控制页面滚动，支持平滑动画并自动等待完成：\n\n```python\nfrom pydoll.constants import ScrollPosition\n\n# 带平滑动画向下滚动（等待完成）\nawait tab.scroll.by(ScrollPosition.DOWN, 500, smooth=True)\n\n# 导航至特定位置\nawait tab.scroll.to_bottom(smooth=True)\nawait tab.scroll.to_top(smooth=True)\n\n# 需要速度时的即时滚动\nawait tab.scroll.by(ScrollPosition.UP, 300, smooth=False)\n```\n\n不同于立即返回的 `execute_script(\"window.scrollBy(...)\")`，滚动API使用CDP的`awaitPromise`等待浏览器的`scrollend`事件，确保后续操作仅在滚动完全完成后执行。非常适合截取屏幕截图、加载延迟内容或创建真实的阅读模式。\n\n### 键盘 API —— 完全控制键盘输入\n\n全新的 `KeyboardAPI` 为页面级别的所有键盘交互提供了简洁、集中的接口：\n\n```python\nfrom pydoll.constants import Key\n\n# 按单个键\nawait tab.keyboard.press(Key.ENTER)\nawait tab.keyboard.press(Key.TAB)\n\n# 使用快捷键/组合键（最多3个键）\nawait tab.keyboard.hotkey(Key.CONTROL, Key.A) # 全选（有效！）\nawait tab.keyboard.hotkey(Key.CONTROL, Key.C) # 复制（有效！）\nawait tab.keyboard.hotkey(Key.CONTROL, Key.SHIFT, Key.ARROWRIGHT) # 向右选择单词\n\n# 复杂序列的手动控制\nawait tab.keyboard.down(Key.SHIFT)\nawait tab.keyboard.press(Key.ARROWRIGHT) # 按住 Shift 选择文本\nawait tab.keyboard.up(Key.SHIFT)\n```\n\n**主要改进：**\n- **集中化**：所有键盘操作通过 `tab.keyboard` 访问\n- **智能修饰键检测**：快捷键自动检测并应用修饰键（Ctrl、Shift、Alt、Meta）\n- **完整按键支持**：26个字母（A-Z）、10个数字（0-9）、所有功能键、数字键盘和特殊键\n- **页面级快捷键**：适用于 Ctrl+C、Ctrl+V、Ctrl+A 等（由于 CDP 限制，浏览器 UI 快捷键不起作用）\n\n> **⚠️ CDP 限制：** 浏览器 UI 快捷键（如 Ctrl+T 打开新标签，F12 打开开发者工具）通过 CDP 无法使用。请改用 Pydoll 的方法：`await browser.new_tab()`、`await tab.close()`。\n\n### Retry 装饰器：生产级错误恢复\n\n使用 `@retry` 装饰器将脆弱的脚本转变为强大的生产级爬虫。通过指数退避和自定义恢复策略，自动从网络故障、超时和临时错误中恢复：\n\n```python\nimport asyncio\nfrom pydoll.browser.chromium import Chrome\nfrom pydoll.decorators import retry\nfrom pydoll.exceptions import ElementNotFound, NetworkError\n\nclass ProductScraper:\n def __init__(self):\n self.tab = None\n self.retry_count = 0\n \n # 在每次重试前执行的恢复回调\n async def recover_from_failure(self):\n self.retry_count += 1\n print(f\"尝试 {self.retry_count} 失败。恢复中...\")\n \n # 刷新页面并恢复状态\n if self.tab:\n await self.tab.refresh()\n await asyncio.sleep(2)\n \n @retry(\n max_retries=3,\n exceptions=[ElementNotFound, NetworkError],\n on_retry=recover_from_failure, # 执行恢复逻辑\n delay=2.0,\n exponential_backoff=True\n )\n async def scrape_product(self, url: str):\n if not self.tab:\n browser = Chrome()\n self.tab = await browser.start()\n \n await self.tab.go_to(url)\n title = await self.tab.find(class_name='product-title', timeout=5)\n return await title.text\n```\n\n**强大功能：**\n- **智能重试逻辑**：仅对您定义的特定异常重试\n- **指数退避**：逐步增加等待时间（1秒 → 2秒 → 4秒 → 8秒）\n- **恢复回调**：在重试之间执行自定义逻辑（刷新页面、切换代理、重启浏览器）\n- **生产验证**：自信地处理真实世界爬虫的混乱情况\n\n非常适合处理速率限制、网络不稳定、动态内容加载和验证码检测。将不可靠的爬虫转变为防弹自动化。\n\n[**📖 完整文档**](https://pydoll.tech/docs/zh/features/advanced/decorators/)\n\n### 通过 WebSocket 进行远程连接 —— 随时随地控制浏览器！\n\n现在你可以使用浏览器的 WebSocket 地址直接连接到已运行的实例，并立即使用完整的 Pydoll API：\n\n```python\nfrom pydoll.browser.chromium import Chrome\n\nchrome = Chrome()\ntab = await chrome.connect('ws://YOUR_HOST:9222/devtools/browser/XXXX')\n\n# 直接开干：导航、元素自动化、请求、事件…\nawait tab.go_to('https://example.com')\ntitle = await tab.execute_script('return document.title')\nprint(title)\n```\n\n这让你可以轻松对接远程/CI 浏览器、容器或共享调试目标——无需本地启动，只需指向 WS 端点即可自动化。\n\n### 像专业人士一样漫游 DOM：get_children_elements() 与 get_siblings_elements()\n\n两个让复杂布局遍历更优雅的小助手：\n\n```python\n# 获取容器的直接子元素\ncontainer = await tab.find(id='cards')\ncards = await container.get_children_elements(max_depth=1)\n\n# 想更深入？这将返回子元素的子元素（以此类推）\nelements = await container.get_children_elements(max_depth=2) \n\n# 在横向列表中无痛遍历兄弟元素\nactive = await tab.find(class_name='item--active')\nsiblings = await active.get_siblings_elements()\n\nprint(len(cards), len(siblings))\n```\n\n用更少样板代码表达更多意图，特别适合动态网格、列表与菜单的场景，让抓取/自动化逻辑更清晰、更可读。\n\n### WebElement：状态等待与新的公共 API\n\n- 新增 `wait_until(...)` 用于等待元素状态，使用更简单：\n\n```python\n# 等待元素变为可见，直到超时\nawait element.wait_until(is_visible=True, timeout=5)\n\n# 等待元素变为可交互（可见、位于顶层并可接收事件）\nawait element.wait_until(is_interactable=True, timeout=10)\n```\n\n- 以下 `WebElement` 方法现已公开：\n - `is_visible()`\n - 判断元素是否具有可见区域、未被 CSS 隐藏，并在需要时滚动进入视口。适用于交互前的快速校验。\n - `is_interactable()`\n - “可点击”状态：综合可见性、启用状态与指针事件命中等条件，适合构建更稳健的交互流程。\n - `is_on_top()`\n - 检查元素在点击位置是否为顶部命中目标，避免被覆盖导致点击失效。\n - `execute_script(script: str, return_by_value: bool = False)`\n - 在元素上下文中执行 JavaScript（this 指向该元素），便于细粒度调整与快速检查。\n\n```python\n# 使用 JS 高亮元素\nawait element.execute_script(\"this.style.outline='2px solid #22d3ee'\")\n\n# 校验状态\nvisible = await element.is_visible()\ninteractable = await element.is_interactable()\non_top = await element.is_on_top()\n```\n\n以上新增能力能显著简化“等待+验证”场景，降低自动化过程中的不稳定性，使用例更可预测。\n\n### 浏览器上下文 HTTP 请求 - 混合自动化的游戏规则改变者！\n你是否曾经希望能够发出自动继承浏览器所有会话状态的 HTTP 请求？**现在你可以了！**
\n`tab.request` 属性为你提供了一个美观的 `requests` 风格接口，可在浏览器的 JavaScript 上下文中直接执行 HTTP 调用。这意味着每个请求都会自动获得 cookies、身份验证标头、CORS 策略和会话状态，就像浏览器本身发出请求一样。\n\n**混合自动化的完美选择：**\n```python\n# 使用 PyDoll 正常导航到网站并登录\nawait tab.go_to('https://example.com/login')\nawait (await tab.find(id='username')).type_text('user@example.com')\nawait (await tab.find(id='password')).type_text('password')\nawait (await tab.find(id='login-btn')).click()\n\n# 现在发出继承已登录会话的 API 调用！\nresponse = await tab.request.get('https://example.com/api/user/profile')\nuser_data = response.json()\n\n# 在保持身份验证的同时 POST 数据\nresponse = await tab.request.post(\n 'https://example.com/api/settings', \n json={'theme': 'dark', 'notifications': True}\n)\n\n# 以不同格式访问响应内容\nraw_data = response.content\ntext_data = response.text\njson_data = response.json()\n\n# 检查设置的 cookies\nfor cookie in response.cookies:\n print(f\"Cookie: {cookie['name']} = {cookie['value']}\")\n\n# 向你的请求添加自定义标头\nheaders = [\n {'name': 'X-Custom-Header', 'value': 'my-value'},\n {'name': 'X-API-Version', 'value': '2.0'}\n]\n\nawait tab.request.get('https://api.example.com/data', headers=headers)\n\n```\n\n**为什么这很棒：**\n- **无需会话切换** - 请求自动继承浏览器 cookies\n- **CORS 无缝工作** - 请求遵循浏览器安全策略 \n- **现代 SPA 的完美选择** - 无缝混合 UI 自动化与 API 调用\n- **身份验证变得简单** - 通过 UI 登录一次，然后调用 API\n- **混合工作流** - 为每个步骤使用最佳工具（UI 或 API）\n\n这为需要浏览器交互和 API 效率的自动化场景开启了令人难以置信的可能性！\n\n### 使用自定义首选项完全控制浏览器！(感谢 [@LucasAlvws](https://github.com/LucasAlvws))\n想要完全自定义 Chrome 的行为？**现在你可以控制一切！**
\n新的 `browser_preferences` 系统让你可以访问数百个之前无法通过编程方式更改的内部 Chrome 设置。我们说的是远超命令行标志的深度浏览器自定义！\n\n**可能性是无限的：**\n```python\noptions = ChromiumOptions()\n\n# 创建完美的自动化环境\noptions.browser_preferences = {\n 'download': {\n 'default_directory': '/tmp/downloads',\n 'prompt_for_download': False,\n 'directory_upgrade': True,\n 'extensions_to_open': '' # 不自动打开任何下载\n },\n 'profile': {\n 'default_content_setting_values': {\n 'notifications': 2, # 阻止所有通知\n 'geolocation': 2, # 阻止位置请求\n 'media_stream_camera': 2, # 阻止摄像头访问\n 'media_stream_mic': 2, # 阻止麦克风访问\n 'popups': 1 # 允许弹窗（对自动化有用）\n },\n 'password_manager_enabled': False, # 禁用密码提示\n 'exit_type': 'Normal' # 始终正常退出\n },\n 'intl': {\n 'accept_languages': 'zh-CN,zh,en-US,en',\n 'charset_default': 'UTF-8'\n },\n 'browser': {\n 'check_default_browser': False, # 不询问默认浏览器\n 'show_update_promotion_infobar': False\n }\n}\n\n# 或使用便捷的辅助方法\noptions.set_default_download_directory('/tmp/downloads')\noptions.set_accept_languages('zh-CN,zh,en-US,en') \noptions.prompt_for_download = False\n```\n\n**实际应用的强大示例：**\n- **静默下载** - 无提示、无对话框，只有自动化下载\n- **阻止所有干扰** - 通知、弹窗、摄像头请求，应有尽有\n- **CI/CD 的完美选择** - 禁用更新检查、默认浏览器提示、崩溃报告\n- **多区域测试** - 即时更改语言、时区和区域设置\n- **安全加固** - 锁定权限并禁用不必要的功能\n- **高级指纹控制** - 修改浏览器安装日期、参与历史和行为模式\n\n**用于隐蔽自动化的指纹自定义：**\n```python\nimport time\n\n# 模拟一个已经存在几个月的浏览器\nfake_engagement_time = int(time.time()) - (7 * 24 * 60 * 60) # 7天前\n\noptions.browser_preferences = {\n 'settings': {\n 'touchpad': {\n 'natural_scroll': True,\n }\n },\n 'profile': {\n 'last_engagement_time': fake_engagement_time,\n 'exit_type': 'Normal',\n 'exited_cleanly': True\n },\n 'newtab_page_location_override': 'https://www.google.com',\n 'session': {\n 'restore_on_startup': 1, # 恢复上次会话\n 'startup_urls': ['https://www.google.com']\n }\n}\n```\n\n这种控制级别以前只有 Chrome 扩展开发者才能使用 - 现在它在你的自动化工具包中！\n\n查看[文档](https://pydoll.tech/docs/zh/features/#custom-browser-preferences/)了解更多详情。\n\n### 新的 `get_parent_element()` 方法\n检索任何 WebElement 的父元素，使导航 DOM 结构更加容易：\n```python\nelement = await tab.find(id='button')\nparent = await element.get_parent_element()\n```\n\n### 新的 start_timeout 选项 (感谢 [@j0j1j2](https://github.com/j0j1j2))\n添加到 ChromiumOptions 来控制浏览器启动可以花费多长时间。在较慢的机器或 CI 环境中很有用。\n\n```python\noptions = ChromiumOptions()\noptions.start_timeout = 20 # 等待 20 秒\n```\n\n### 新的 expect_download() 上下文管理器 —— 稳健、优雅的文件下载！\n还在为不稳定的下载流程、丢失的文件或混乱的事件监听而头疼吗？`tab.expect_download()` 来了：一种可靠、简洁的下载方式。\n\n- 自动配置浏览器下载行为\n- 支持自定义下载目录或临时目录（自动清理！）\n- 内置超时等待，防止任务卡住\n- 提供便捷句柄：读取字节/BASE64，获取 `file_path`\n\n一个“开箱即用”的小示例：\n\n```python\nimport asyncio\nfrom pathlib import Path\nfrom pydoll.browser import Chrome\n\nasync def download_report():\n async with Chrome() as browser:\n tab = await browser.start()\n await tab.go_to('https://example.com/reports')\n\n target_dir = Path('/tmp/my-downloads')\n async with tab.expect_download(keep_file_at=target_dir, timeout=10) as dl:\n # 触发页面上的下载（按钮/链接等）\n await (await tab.find(text='Download latest report')).click()\n\n # 等待完成并读取内容\n data = await dl.read_bytes()\n print(f\"已下载 {len(data)} 字节，保存至: {dl.file_path}\")\n\nasyncio.run(download_report())\n```\n\n想要“零成本清理”？不传 `keep_file_at` 即可——我们会创建临时目录，并在上下文退出后自动清理。对测试场景非常友好。\n\n## 📦 安装\n\n```bash\npip install pydoll-python\n```\n\n就这么简单！安装即用，马上开始自动化\n\n## 🚀 快速上手\n\n### 你的第一个自动化任务\n\n让我们从一个实际例子开始：一个自动执行谷歌搜索并点击第一个结果的自动化流程。通过这个示例，你可以了解该库的工作原理，以及如何开始将日常任务自动化。\n\n```python\nimport asyncio\n\nfrom pydoll.browser import Chrome\nfrom pydoll.constants import Key\n\nasync def google_search(query: str):\n async with Chrome() as browser:\n tab = await browser.start()\n await tab.go_to('https://www.google.com')\n search_box = await tab.find(tag_name='textarea', name='q')\n await search_box.insert_text(query)\n await tab.keyboard.press(Key.ENTER)\n await (await tab.find(\n tag_name='h3',\n text='autoscrape-labs/pydoll',\n timeout=10,\n )).click()\n await tab.find(id='repository-container-header', timeout=10)\n\nasyncio.run(google_search('pydoll site:github.com'))\n```\n\n无需任何配置，只需一个简单脚本，我们就能完成一次完整的谷歌搜索！\n好了，现在让我们看看如何从网页中提取数据，依然沿用之前的示例。\n\n假设在以下代码中，我们已经进入了 Pydoll 项目页面。我们需要提取以下信息：\n\n- 项目描述\n- 星标数量\n- Fork 数量\n- Issue 数量\n- Pull Request 数量\n如果想要获取项目描述，我们将使用 XPath 查询。你可以查阅相关文档，学习如何构建自己的查询语句。\n\n```python\ndescription = await (await tab.query(\n '//h2[contains(text(), \"About\")]/following-sibling::p',\n timeout=10,\n)).text\n```\n\n下面让我们来理解这条查询语句的作用：\n\n1. `//h2[contains(text(), \"About\")]` - 选择第一个包含\"About\"的 `

` 标签\n2. `/following-sibling::p` - 选择第一个在`

` 标签之后的`

`标签\n\n然后你可以获取到剩下的数据：\n\n```python\nnumber_of_stars = await (await tab.find(\n id='repo-stars-counter-star'\n)).text\n\nnumber_of_forks = await (await tab.find(\n id='repo-network-counter'\n)).text\nnumber_of_issues = await (await tab.find(\n id='issues-repo-tab-count',\n)).text\nnumber_of_pull_requests = await (await tab.find(\n id='pull-requests-repo-tab-count',\n)).text\n\ndata = {\n 'description': description,\n 'number_of_stars': number_of_stars,\n 'number_of_forks': number_of_forks,\n 'number_of_issues': number_of_issues,\n 'number_of_pull_requests': number_of_pull_requests,\n}\nprint(data)\n\n```\n\n下图展示了本次自动化任务的执行速度与结果。\n（为演示需要，浏览器界面未显示。）\n\n![google_seach](./docs/images/google-search-example.gif)\n\n\n短短5秒内，我们就成功提取了所需数据！ \n这就是使用Pydoll进行自动化所能达到的速度。\n\n### 更多复杂的例子\n\n接下来我们来看一个你可能经常遇到的场景：类似Cloudflare的验证码防护。 \nPydoll提供了相应的处理方法，但需要说明的是，正如前文所述，其有效性会受到多种因素影响。 \n下面的代码展示了一个完整的Cloudflare验证码处理示例。\n\n```python\nimport asyncio\n\nfrom pydoll.browser import Chrome\nfrom pydoll.constants import By\n\nasync def cloudflare_example():\n async with Chrome() as browser:\n tab = await browser.start()\n async with tab.expect_and_bypass_cloudflare_captcha():\n await tab.go_to('https://2captcha.com/demo/cloudflare-turnstile')\n print('Captcha handled, continuing...')\n await asyncio.sleep(5) # just to see the result :)\n\nasyncio.run(cloudflare_example())\n\n```\n\n执行结果如下：\n\n![cloudflare_example](./docs/images/cloudflare-example.gif)\n\n\n仅需数行代码，我们就成功攻克了最棘手的验证码防护之一。\n而这仅仅是Pydoll所提供的众多强大功能之一。但这还远不是全部！\n\n\n### 自定义配置\n\n有时我们需要对浏览器进行更精细的控制。Pydoll提供了灵活的配置方式来实现这一点。下面我们来看具体示例：\n\n\n```python\nfrom pydoll.browser import Chrome\nfrom pydoll.browser.options import ChromiumOptions as Options\n\nasync def custom_automation():\n # Configure browser options\n options = Options()\n options.add_argument('--proxy-server=username:password@ip:port')\n options.add_argument('--window-size=1920,1080')\n options.binary_location = '/path/to/your/browser'\n options.start_timeout = 20\n\n async with Chrome(options=options) as browser:\n tab = await browser.start()\n # Your automation code here\n await tab.go_to('https://example.com')\n # The browser is now using your custom settings\n\nasyncio.run(custom_automation())\n```\n\n本示例中，我们配置浏览器使用代理服务器，并设置窗口分辨率为1920x1080。此外，还指定了Chrome二进制文件的自定义路径——适用于您的安装位置与常规默认路径不同的情况。\n\n## ⚡ 高级功能\n\nPydoll提供了一系列高级特性满足高端玩家的需求。\n\n\n### 高级元素定位\n\n我们提供多种页面元素定位方式。无论您偏好那种方法，都能找到适合您的解决方案：\n\n```python\nimport asyncio\nfrom pydoll.browser import Chrome\n\nasync def element_finding_examples():\n async with Chrome() as browser:\n tab = await browser.start()\n await tab.go_to('https://example.com')\n\n # Find by attributes (most intuitive)\n submit_btn = await tab.find(\n tag_name='button',\n class_name='btn-primary',\n text='Submit'\n )\n # Find by ID\n username_field = await tab.find(id='username')\n # Find multiple elements\n all_links = await tab.find(tag_name='a', find_all=True)\n # CSS selectors and XPath\n nav_menu = await tab.query('nav.main-menu')\n specific_item = await tab.query('//div[@data-testid=\"item-123\"]')\n # With timeout and error handling\n delayed_element = await tab.find(\n class_name='dynamic-content',\n timeout=10,\n raise_exc=False # Returns None if not found\n )\n # Advanced: Custom attributes\n custom_element = await tab.find(\n data_testid='submit-button',\n aria_label='Submit form'\n )\n\nasyncio.run(element_finding_examples())\n```\n\nfind 方法更为友好。我们可以通过常见属性（如 id、tag_name、class_name 等）进行元素查找，甚至支持自定义属性（例如 data-testid）。\n\n如果这些基础方式仍不能满足需求，还可使用 query 方法，通过 CSS 选择器、XPath 查询语句等多种方式进行元素定位。Pydoll 会自动识别当前使用的查询类型。\n\n### 并发自动化\n\nPydoll 的一大优势在于其基于异步实现的多任务并行处理能力。我们可以同时自动化操作多个浏览器标签页！下面来看具体示例：\n\n```python\nimport asyncio\nfrom pydoll.browser import Chrome\n\nasync def scrape_page(url, tab):\n await tab.go_to(url)\n title = await tab.execute_script('return document.title')\n links = await tab.find(tag_name='a', find_all=True)\n return {\n 'url': url,\n 'title': title,\n 'link_count': len(links)\n }\n\nasync def concurrent_scraping():\n browser = Chrome()\n tab_google = await browser.start()\n tab_duckduckgo = await browser.new_tab()\n tasks = [\n scrape_page('https://google.com/', tab_google),\n scrape_page('https://duckduckgo.com/', tab_duckduckgo)\n ]\n results = await asyncio.gather(*tasks)\n print(results)\n await browser.stop()\n\nasyncio.run(concurrent_scraping())\n```\n\n下方展示令人惊叹的执行速度：\n\n![concurrent_example](./docs/images/concurrent-example.gif)\n\n\n这个例子,我们成功实现了同时对两个页面的数据提取.\n还有更多强大功能！响应式自动化的事件系统、请求拦截与修改等等。赶快查阅文档!\n\n## 🔧 快速问题排查\n\n**找不到浏览器？**\n```python\nfrom pydoll.browser import Chrome\nfrom pydoll.browser.options import ChromiumOptions\n\noptions = ChromiumOptions()\noptions.binary_location = '/path/to/your/chrome'\nbrowser = Chrome(options=options)\n```\n\n**浏览器在 FailedToStartBrowser 错误后启动？**\n```python\nfrom pydoll.browser import Chrome\nfrom pydoll.browser.options import ChromiumOptions\n\noptions = ChromiumOptions()\noptions.start_timeout = 20 # 默认是 10 秒\n\nbrowser = Chrome(options=options)\n```\n\n**需要代理？**\n```python\noptions.add_argument('--proxy-server=your-proxy:port')\n```\n\n**在 Docker 中运行？**\n```python\noptions.add_argument('--no-sandbox')\noptions.add_argument('--disable-dev-shm-usage')\n```\n\n## 📚 文档\n\nPydoll 的完整文档、详细示例以及对所有功能的深入探讨可以通过以下链接访问： [官方文档](https://autoscrape-labs.github.io/pydoll/).\n\n文档包含以下部分:\n- **快速上手指南** - 分步教程\n- **API 参考** - 完整的方法文档\n- **高级技巧** - 网络拦截、事件处理、性能优化\n\n>此 README 的中文版本在[这里](README_zh.md)。\n\n## 🤝 贡献\n\n我们很乐意看到您的帮助让 Pydoll 变得更好！查看我们的[贡献指南](CONTRIBUTING.md)开始贡献。无论是修复错误、添加功能还是改进文档 - 所有贡献都受欢迎！\n\n请确保：\n- 为新功能或错误修复编写测试\n- 遵循代码风格和约定\n- 对拉取请求使用约定式提交\n- 在提交前运行 lint 检查和测试\n\n## 💖 支持我的工作\n\n如果您发现 Pydoll 有用，请考虑[在 GitHub 上支持我](https://github.com/sponsors/thalissonvs)。 \n您将获得独家优惠，如优先支持、自定义功能等等！\n\n现在无法赞助？没问题，您仍然可以通过以下方式提供很大帮助：\n- 为仓库加星\n- 在社交媒体上分享\n- 撰写文章或教程\n- 提供反馈或报告问题\n\n每一点支持都很重要/\n\n## 💬 传播消息\n\n如果 Pydoll 为您节省了时间、心理健康或者拯救了一个键盘免于被砸，请给它一个 ⭐，分享它，或者告诉您奇怪的开发者朋友。\n\n## 📄 许可证\n\nPydoll 在 [MIT 许可证](LICENSE) 下获得许可。\n\n

\n Pydoll — 让浏览器自动化变得神奇！\n

\n" }, { "path": "SPONSORS.md", "content": "# Sponsors\n\nPydoll is supported by these amazing sponsors. Their contributions help keep the project maintained and growing.\n\n## Top Sponsors\n\n\n\"The\n\n\nRead a full review of Pydoll on **[The Web Scraping Club](https://substack.thewebscraping.club/p/pydoll-webdriver-scraping?utm_source=github&utm_medium=repo&utm_campaign=pydoll)**, the #1 newsletter dedicated to web scraping.\n\n---\n\n## Sponsors\n\n\n\"Thordata\"\n\n\nPydoll is proudly sponsored by **[Thordata](https://www.thordata.com/?ls=github&lk=pydoll)**: a residential proxy network built for serious web scraping and automation. With **190+ real residential and ISP locations**, fully encrypted connections, and infrastructure optimized for high-performance workflows, Thordata is an excellent choice for scaling your Pydoll automations.\n\n**[Sign up through our link](https://www.thordata.com/?ls=github&lk=pydoll)** to support the project and get **1GB free** to get started.\n\n---\n\n\n\"CapSolver\"\n\n\nPydoll excels at behavioral evasion, but it doesn't solve captchas. That's where **[CapSolver](https://dashboard.capsolver.com/passport/register?inviteCode=WPhTbOsbXEpc)** comes in. An AI-powered service that handles reCAPTCHA, Cloudflare challenges, and more, seamlessly integrating with your automation workflows.\n\n**[Register with our invite code](https://dashboard.capsolver.com/passport/register?inviteCode=WPhTbOsbXEpc)** and use code **PYDOLL** to get an extra **6% balance bonus**.\n\n---\n\nInterested in sponsoring Pydoll? [Become a sponsor](https://github.com/sponsors/thalissonvs).\n" }, { "path": "codecov.yml", "content": "coverage:\n status:\n project: \n default:\n target: 90%\n threshold: 0%\n base: auto " }, { "path": "cz.yaml", "content": "---\ncommitizen:\n name: cz_conventional_commits\n tag_format: $version\n version: 2.21.3\n" }, { "path": "docs/en/api/browser/chrome.md", "content": "# Chrome Browser\n \n::: pydoll.browser.chromium.Chrome\n options:\n show_root_heading: true\n show_source: false\n heading_level: 2 " }, { "path": "docs/en/api/browser/edge.md", "content": "# Edge Browser\n \n::: pydoll.browser.chromium.Edge\n options:\n show_root_heading: true\n show_source: false\n heading_level: 2 " }, { "path": "docs/en/api/browser/managers.md", "content": "# Browser Managers\n\nThe managers module provides specialized classes for managing different aspects of browser lifecycle and configuration.\n\n## Overview\n\nBrowser managers handle specific responsibilities in browser automation:\n\n::: pydoll.browser.managers\n options:\n show_root_heading: true\n show_source: false\n heading_level: 2\n filters:\n - \"!^_\"\n - \"!^__\"\n\n## Manager Classes\n\n### Browser Process Manager\nManages the browser process lifecycle, including starting, stopping, and monitoring browser processes.\n\n::: pydoll.browser.managers.browser_process_manager\n options:\n show_root_heading: true\n show_source: false\n heading_level: 3\n\n### Browser Options Manager\nHandles browser configuration options and command-line arguments.\n\n::: pydoll.browser.managers.browser_options_manager\n options:\n show_root_heading: true\n show_source: false\n heading_level: 3\n\n### Proxy Manager\nManages proxy configuration and authentication for browser instances.\n\n::: pydoll.browser.managers.proxy_manager\n options:\n show_root_heading: true\n show_source: false\n heading_level: 3\n\n### Temporary Directory Manager\nHandles creation and cleanup of temporary directories used by browser instances.\n\n::: pydoll.browser.managers.temp_dir_manager\n options:\n show_root_heading: true\n show_source: false\n heading_level: 3\n\n## Usage\n\nManagers are typically used internally by browser classes like `Chrome` and `Edge`. They provide modular functionality that can be composed together:\n\n```python\nfrom pydoll.browser.managers.proxy_manager import ProxyManager\nfrom pydoll.browser.managers.temp_dir_manager import TempDirManager\n\n# Managers are used internally by browser classes\n# Direct usage is for advanced scenarios only\nproxy_manager = ProxyManager()\ntemp_manager = TempDirManager()\n```\n\n!!! note \"Internal Usage\"\n These managers are primarily used internally by the browser classes. Direct usage is recommended only for advanced scenarios or when extending the library. " }, { "path": "docs/en/api/browser/options.md", "content": "# Browser Options\n\n## ChromiumOptions\n\n::: pydoll.browser.options.ChromiumOptions\n options:\n show_root_heading: true\n show_source: false\n heading_level: 3\n\n## Options Interface\n\n::: pydoll.browser.interfaces.Options\n options:\n show_root_heading: true\n show_source: false\n heading_level: 3\n\n## BrowserOptionsManager Interface\n\n::: pydoll.browser.interfaces.BrowserOptionsManager\n options:\n show_root_heading: true\n show_source: false\n heading_level: 3 " }, { "path": "docs/en/api/browser/requests.md", "content": "# Browser Requests\n\nThe requests module provides HTTP request capabilities within the browser context, enabling seamless API calls that inherit the browser's session state, cookies, and authentication.\n\n## Overview\n\nThe browser requests module offers a `requests`-like interface for making HTTP calls directly within the browser's JavaScript context. This approach provides several advantages over traditional HTTP libraries:\n\n- **Session inheritance**: Automatic cookie, authentication, and CORS handling\n- **Browser context**: Requests execute in the same security context as the page\n- **No session juggling**: Eliminate the need to transfer cookies and tokens between automation and API calls\n- **SPA compatibility**: Perfect for Single Page Applications with complex authentication flows\n\n## Request Class\n\nThe main interface for making HTTP requests within the browser context.\n\n::: pydoll.browser.requests.request.Request\n options:\n show_root_heading: true\n show_source: false\n heading_level: 3\n group_by_category: true\n members_order: source\n filters:\n - \"!^__\"\n\n## Response Class\n\nRepresents the response from HTTP requests, providing a familiar interface similar to the `requests` library.\n\n::: pydoll.browser.requests.response.Response\n options:\n show_root_heading: true\n show_source: false\n heading_level: 3\n group_by_category: true\n members_order: source\n filters:\n - \"!^__\"\n\n## Usage Examples\n\n### Basic HTTP Methods\n\n```python\nfrom pydoll.browser.chromium import Chrome\n\nasync with Chrome() as browser:\n tab = await browser.start()\n await tab.go_to(\"https://api.example.com\")\n \n # GET request\n response = await tab.request.get(\"/users/123\")\n user_data = await response.json()\n \n # POST request\n response = await tab.request.post(\"/users\", json={\n \"name\": \"John Doe\",\n \"email\": \"john@example.com\"\n })\n \n # PUT request with headers\n response = await tab.request.put(\"/users/123\", \n json={\"name\": \"Jane Doe\"},\n headers={\"Authorization\": \"Bearer token123\"}\n )\n```\n\n### Response Handling\n\n```python\n# Check response status\nif response.ok:\n print(f\"Success: {response.status_code}\")\nelse:\n print(f\"Error: {response.status_code}\")\n response.raise_for_status() # Raises HTTPError for 4xx/5xx\n\n# Access response data\ntext_data = response.text\njson_data = await response.json()\nraw_bytes = response.content\n\n# Inspect headers and cookies\nprint(\"Response headers:\", response.headers)\nprint(\"Request headers:\", response.request_headers)\nfor cookie in response.cookies:\n print(f\"Cookie: {cookie.name}={cookie.value}\")\n```\n\n### Advanced Features\n\n```python\n# Request with custom headers and parameters\nresponse = await tab.request.get(\"/search\", \n params={\"q\": \"python\", \"limit\": 10},\n headers={\n \"User-Agent\": \"Custom Bot 1.0\",\n \"Accept\": \"application/json\"\n }\n)\n\n# File upload simulation\nresponse = await tab.request.post(\"/upload\",\n data={\"description\": \"Test file\"},\n files={\"file\": (\"test.txt\", \"file content\", \"text/plain\")}\n)\n\n# Form data submission\nresponse = await tab.request.post(\"/login\",\n data={\"username\": \"user\", \"password\": \"pass\"}\n)\n```\n\n## Integration with Tab\n\nThe request functionality is accessed through the `tab.request` property, which provides a singleton `Request` instance for each tab:\n\n```python\n# Each tab has its own request instance\ntab1 = await browser.get_tab(0)\ntab2 = await browser.new_tab()\n\n# These are separate Request instances\nrequest1 = tab1.request # Request bound to tab1\nrequest2 = tab2.request # Request bound to tab2\n\n# Requests inherit the tab's context\nawait tab1.go_to(\"https://site1.com\")\nawait tab2.go_to(\"https://site2.com\")\n\n# These requests will have different cookie/session contexts\nresponse1 = await tab1.request.get(\"/api/data\") # Uses site1.com cookies\nresponse2 = await tab2.request.get(\"/api/data\") # Uses site2.com cookies\n```\n\n!!! tip \"Hybrid Automation\"\n This module is particularly powerful for hybrid automation scenarios where you need to combine UI interactions with API calls. For example, log in through the UI, then use the authenticated session for API calls without manually handling cookies or tokens." }, { "path": "docs/en/api/browser/tab.md", "content": "# Tab\n\n::: pydoll.browser.tab.Tab\n options:\n show_root_heading: true\n show_source: false\n heading_level: 2" }, { "path": "docs/en/api/commands/browser.md", "content": "# Browser Commands\n\nBrowser commands provide low-level control over browser instances and their configuration.\n\n## Overview\n\nThe browser commands module handles browser-level operations such as version information, target management, and browser-wide settings.\n\n::: pydoll.commands.browser_commands\n options:\n show_root_heading: true\n show_source: false\n heading_level: 2\n filters:\n - \"!^_\"\n - \"!^__\"\n\n## Usage\n\nBrowser commands are typically used internally by browser classes to manage browser instances:\n\n```python\nfrom pydoll.commands.browser_commands import get_version\nfrom pydoll.connection.connection_handler import ConnectionHandler\n\n# Get browser version information\nconnection = ConnectionHandler()\nversion_info = await get_version(connection)\n```\n\n## Available Commands\n\nThe browser commands module provides functions for:\n\n- Getting browser version and user agent information\n- Managing browser targets (tabs, windows)\n- Controlling browser-wide settings and permissions\n- Handling browser lifecycle events\n\n!!! note \"Internal Usage\"\n These commands are primarily used internally by the `Chrome` and `Edge` browser classes. Direct usage is recommended only for advanced scenarios. " }, { "path": "docs/en/api/commands/dom.md", "content": "# DOM Commands\n\nDOM commands provide comprehensive functionality for interacting with the Document Object Model of web pages.\n\n## Overview\n\nThe DOM commands module is one of the most important modules in Pydoll, providing all the functionality needed to find, interact with, and manipulate HTML elements on web pages.\n\n::: pydoll.commands.dom_commands\n options:\n show_root_heading: true\n show_source: false\n heading_level: 2\n filters:\n - \"!^_\"\n - \"!^__\"\n\n## Usage\n\nDOM commands are used extensively by the `WebElement` class and element finding methods:\n\n```python\nfrom pydoll.commands.dom_commands import query_selector, get_attributes\nfrom pydoll.connection.connection_handler import ConnectionHandler\n\n# Find element and get its attributes\nconnection = ConnectionHandler()\nnode_id = await query_selector(connection, selector=\"#username\")\nattributes = await get_attributes(connection, node_id=node_id)\n```\n\n## Key Functionality\n\nThe DOM commands module provides functions for:\n\n### Element Finding\n- `query_selector()` - Find single element by CSS selector\n- `query_selector_all()` - Find multiple elements by CSS selector\n- `get_document()` - Get the document root node\n\n### Element Interaction\n- `click_element()` - Click on elements\n- `focus_element()` - Focus elements\n- `set_attribute_value()` - Set element attributes\n- `get_attributes()` - Get element attributes\n\n### Element Information\n- `get_box_model()` - Get element positioning and dimensions\n- `describe_node()` - Get detailed element information\n- `get_outer_html()` - Get element HTML content\n\n### DOM Manipulation\n- `remove_node()` - Remove elements from DOM\n- `set_node_value()` - Set element values\n- `request_child_nodes()` - Get child elements\n\n!!! tip \"High-Level APIs\"\n While these commands provide powerful low-level access, most users should use the higher-level `WebElement` class methods like `click()`, `type_text()`, and `get_attribute()` which use these commands internally. " }, { "path": "docs/en/api/commands/fetch.md", "content": "# Fetch Commands\n\nFetch commands provide advanced network request handling and interception capabilities using the Fetch API domain.\n\n## Overview\n\nThe fetch commands module enables sophisticated network request management, including request modification, response interception, and authentication handling.\n\n::: pydoll.commands.fetch_commands\n options:\n show_root_heading: true\n show_source: false\n heading_level: 2\n filters:\n - \"!^_\"\n - \"!^__\"\n\n## Usage\n\nFetch commands are used for advanced network interception and request handling:\n\n```python\nfrom pydoll.commands.fetch_commands import enable, request_paused, continue_request\nfrom pydoll.connection.connection_handler import ConnectionHandler\n\n# Enable fetch domain\nconnection = ConnectionHandler()\nawait enable(connection, patterns=[{\n \"urlPattern\": \"*\",\n \"requestStage\": \"Request\"\n}])\n\n# Handle paused requests\nasync def handle_paused_request(request_id, request):\n # Modify request or continue as-is\n await continue_request(connection, request_id=request_id)\n```\n\n## Key Functionality\n\nThe fetch commands module provides functions for:\n\n### Request Interception\n- `enable()` - Enable fetch domain with patterns\n- `disable()` - Disable fetch domain\n- `continue_request()` - Continue intercepted requests\n- `fail_request()` - Fail requests with specific errors\n\n### Request Modification\n- Modify request headers\n- Change request URLs\n- Alter request methods (GET, POST, etc.)\n- Modify request bodies\n\n### Response Handling\n- `fulfill_request()` - Provide custom responses\n- `get_response_body()` - Get response content\n- Response header modification\n- Response status code control\n\n### Authentication\n- `continue_with_auth()` - Handle authentication challenges\n- Basic authentication support\n- Custom authentication flows\n\n## Advanced Features\n\n### Pattern-Based Interception\n```python\n# Intercept specific URL patterns\npatterns = [\n {\"urlPattern\": \"*/api/*\", \"requestStage\": \"Request\"},\n {\"urlPattern\": \"*.js\", \"requestStage\": \"Response\"},\n {\"urlPattern\": \"https://example.com/*\", \"requestStage\": \"Request\"}\n]\n\nawait enable(connection, patterns=patterns)\n```\n\n### Request Modification\n```python\n# Modify intercepted requests\nasync def modify_request(request_id, request):\n # Add authentication header\n headers = request.headers.copy()\n headers[\"Authorization\"] = \"Bearer token123\"\n \n # Continue with modified headers\n await continue_request(\n connection,\n request_id=request_id,\n headers=headers\n )\n```\n\n### Response Mocking\n```python\n# Mock API responses\nawait fulfill_request(\n connection,\n request_id=request_id,\n response_code=200,\n response_headers=[\n {\"name\": \"Content-Type\", \"value\": \"application/json\"},\n {\"name\": \"Access-Control-Allow-Origin\", \"value\": \"*\"}\n ],\n body='{\"status\": \"success\", \"data\": {\"mocked\": true}}'\n)\n```\n\n### Authentication Handling\n```python\n# Handle authentication challenges\nawait continue_with_auth(\n connection,\n request_id=request_id,\n auth_challenge_response={\n \"response\": \"ProvideCredentials\",\n \"username\": \"user\",\n \"password\": \"pass\"\n }\n)\n```\n\n## Request Stages\n\nFetch commands can intercept requests at different stages:\n\n| Stage | Description | Use Cases |\n|-------|-------------|-----------|\n| Request | Before request is sent | Modify headers, URL, method |\n| Response | After response received | Mock responses, modify content |\n\n## Error Handling\n\n```python\n# Fail requests with specific errors\nawait fail_request(\n connection,\n request_id=request_id,\n error_reason=\"ConnectionRefused\" # or \"AccessDenied\", \"TimedOut\", etc.\n)\n```\n\n## Integration with Network Commands\n\nFetch commands work alongside network commands but provide more granular control:\n\n- **Network Commands**: Broader network monitoring and control\n- **Fetch Commands**: Specific request/response interception and modification\n\n!!! tip \"Performance Considerations\"\n Fetch interception can impact page loading performance. Use specific URL patterns and disable when not needed to minimize overhead. " }, { "path": "docs/en/api/commands/index.md", "content": "# Commands Overview\n\nThe Commands module provides high-level interfaces for interacting with Chrome DevTools Protocol (CDP) domains. Each command module corresponds to a specific CDP domain and provides methods to execute various browser operations.\n\n## Available Command Modules\n\n### Browser Commands\n- **Module**: `browser_commands.py`\n- **Purpose**: Browser-level operations and window management\n- **Documentation**: [Browser Commands](browser.md)\n\n### DOM Commands\n- **Module**: `dom_commands.py`\n- **Purpose**: DOM tree manipulation and element operations\n- **Documentation**: [DOM Commands](dom.md)\n\n### Input Commands\n- **Module**: `input_commands.py`\n- **Purpose**: Input event simulation (keyboard, mouse, touch)\n- **Documentation**: [Input Commands](input.md)\n\n### Network Commands\n- **Module**: `network_commands.py`\n- **Purpose**: Network monitoring and request interception\n- **Documentation**: [Network Commands](network.md)\n\n### Page Commands\n- **Module**: `page_commands.py`\n- **Purpose**: Page lifecycle management and navigation\n- **Documentation**: [Page Commands](page.md)\n\n### Runtime Commands\n- **Module**: `runtime_commands.py`\n- **Purpose**: JavaScript execution and runtime management\n- **Documentation**: [Runtime Commands](runtime.md)\n\n### Storage Commands\n- **Module**: `storage_commands.py`\n- **Purpose**: Browser storage access (cookies, local storage, etc.)\n- **Documentation**: [Storage Commands](storage.md)\n\n### Target Commands\n- **Module**: `target_commands.py`\n- **Purpose**: Target management and tab operations\n- **Documentation**: [Target Commands](target.md)\n\n### Fetch Commands\n- **Module**: `fetch_commands.py`\n- **Purpose**: Network request interception and modification\n- **Documentation**: [Fetch Commands](fetch.md)\n\n## Usage Pattern\n\nCommands are typically accessed through the browser or tab instances:\n\n```python\nfrom pydoll.browser.chromium import Chrome\n\n# Initialize browser\nbrowser = Chrome()\nawait browser.start()\n\n# Get active tab\ntab = await browser.get_active_tab()\n\n# Use commands through the tab\nawait tab.navigate(\"https://example.com\")\nelement = await tab.find(id=\"button\")\nawait element.click()\n```\n\n## Command Structure\n\nEach command module follows a consistent pattern:\n- **Static methods**: For direct command execution\n- **Type hints**: Full type safety with protocol types\n- **Error handling**: Proper exception handling for CDP errors\n- **Documentation**: Comprehensive docstrings with examples " }, { "path": "docs/en/api/commands/input.md", "content": "# Input Commands\n\nInput commands handle mouse and keyboard interactions, providing human-like input simulation.\n\n## Overview\n\nThe input commands module provides functionality for simulating user input including mouse movements, clicks, keyboard typing, and key presses.\n\n::: pydoll.commands.input_commands\n options:\n show_root_heading: true\n show_source: false\n heading_level: 2\n filters:\n - \"!^_\"\n - \"!^__\"\n\n## Usage\n\nInput commands are used by element interaction methods and can be used directly for advanced input scenarios:\n\n```python\nfrom pydoll.commands.input_commands import dispatch_mouse_event, dispatch_key_event\nfrom pydoll.connection.connection_handler import ConnectionHandler\n\n# Simulate mouse click\nconnection = ConnectionHandler()\nawait dispatch_mouse_event(\n connection, \n type=\"mousePressed\", \n x=100, \n y=200, \n button=\"left\"\n)\n\n# Simulate keyboard typing\nawait dispatch_key_event(\n connection,\n type=\"keyDown\",\n key=\"Enter\"\n)\n```\n\n## Key Functionality\n\nThe input commands module provides functions for:\n\n### Mouse Events\n- `dispatch_mouse_event()` - Mouse clicks, movements, and wheel events\n- Mouse button states (left, right, middle)\n- Coordinate-based positioning\n- Drag and drop operations\n\n### Keyboard Events\n- `dispatch_key_event()` - Key press and release events\n- `insert_text()` - Direct text insertion\n- Special key handling (Enter, Tab, Arrow keys, etc.)\n- Modifier keys (Ctrl, Alt, Shift)\n\n### Touch Events\n- Touch screen simulation\n- Multi-touch gestures\n- Touch coordinates and pressure\n\n## Human-like Behavior\n\nThe input commands support human-like behavior patterns:\n\n- Natural mouse movement curves\n- Realistic typing speeds and patterns\n- Random micro-delays between actions\n- Pressure-sensitive touch events\n\n!!! tip \"Element Methods\"\n For most use cases, use the higher-level element methods like `element.click()` and `element.type_text()` which provide a more convenient API and handle common scenarios automatically. " }, { "path": "docs/en/api/commands/network.md", "content": "# Network Commands\n\nNetwork commands provide comprehensive control over network requests, responses, and browser networking behavior.\n\n## Overview\n\nThe network commands module enables request interception, response modification, cookie management, and network monitoring capabilities.\n\n::: pydoll.commands.network_commands\n options:\n show_root_heading: true\n show_source: false\n heading_level: 2\n filters:\n - \"!^_\"\n - \"!^__\"\n\n## Usage\n\nNetwork commands are used for advanced scenarios like request interception and network monitoring:\n\n```python\nfrom pydoll.commands.network_commands import enable, set_request_interception\nfrom pydoll.connection.connection_handler import ConnectionHandler\n\n# Enable network monitoring\nconnection = ConnectionHandler()\nawait enable(connection)\n\n# Enable request interception\nawait set_request_interception(connection, patterns=[{\"urlPattern\": \"*\"}])\n```\n\n## Key Functionality\n\nThe network commands module provides functions for:\n\n### Request Management\n- `enable()` / `disable()` - Enable/disable network monitoring\n- `set_request_interception()` - Intercept and modify requests\n- `continue_intercepted_request()` - Continue or modify intercepted requests\n- `get_request_post_data()` - Get request body data\n\n### Response Handling\n- `get_response_body()` - Get response content\n- `fulfill_request()` - Provide custom responses\n- `fail_request()` - Simulate network failures\n\n### Cookie Management\n- `get_cookies()` - Get browser cookies\n- `set_cookies()` - Set browser cookies\n- `delete_cookies()` - Delete specific cookies\n- `clear_browser_cookies()` - Clear all cookies\n\n### Cache Control\n- `clear_browser_cache()` - Clear browser cache\n- `set_cache_disabled()` - Disable browser cache\n- `get_response_body_for_interception()` - Get cached responses\n\n### Security & Headers\n- `set_user_agent_override()` - Override user agent\n- `set_extra_http_headers()` - Add custom headers\n- `emulate_network_conditions()` - Simulate network conditions\n\n## Advanced Use Cases\n\n### Request Interception\n```python\n# Intercept and modify requests\nawait set_request_interception(connection, patterns=[\n {\"urlPattern\": \"*/api/*\", \"requestStage\": \"Request\"}\n])\n\n# Handle intercepted request\nasync def handle_request(request):\n if \"api/login\" in request.url:\n # Modify request headers\n headers = request.headers.copy()\n headers[\"Authorization\"] = \"Bearer token\"\n await continue_intercepted_request(\n connection, \n request_id=request.request_id,\n headers=headers\n )\n```\n\n### Response Mocking\n```python\n# Mock API responses\nawait fulfill_request(\n connection,\n request_id=request_id,\n response_code=200,\n response_headers={\"Content-Type\": \"application/json\"},\n body='{\"status\": \"success\"}'\n)\n```\n\n!!! warning \"Performance Impact\"\n Network interception can impact page loading performance. Use selectively and disable when not needed. " }, { "path": "docs/en/api/commands/page.md", "content": "# Page Commands\n\nPage commands handle page navigation, lifecycle events, and page-level operations.\n\n## Overview\n\nThe page commands module provides functionality for navigating between pages, managing page lifecycle, handling JavaScript execution, and controlling page behavior.\n\n::: pydoll.commands.page_commands\n options:\n show_root_heading: true\n show_source: false\n heading_level: 2\n filters:\n - \"!^_\"\n - \"!^__\"\n\n## Usage\n\nPage commands are used extensively by the `Tab` class for navigation and page management:\n\n```python\nfrom pydoll.commands.page_commands import navigate, reload, enable\nfrom pydoll.connection.connection_handler import ConnectionHandler\n\n# Navigate to a URL\nconnection = ConnectionHandler()\nawait enable(connection) # Enable page events\nawait navigate(connection, url=\"https://example.com\")\n\n# Reload the page\nawait reload(connection)\n```\n\n## Key Functionality\n\nThe page commands module provides functions for:\n\n### Navigation\n- `navigate()` - Navigate to URLs\n- `reload()` - Reload current page\n- `go_back()` - Navigate back in history\n- `go_forward()` - Navigate forward in history\n- `stop_loading()` - Stop page loading\n\n### Page Lifecycle\n- `enable()` / `disable()` - Enable/disable page events\n- `get_frame_tree()` - Get page frame structure\n- `get_navigation_history()` - Get navigation history\n\n### Content Management\n- `get_resource_content()` - Get page resource content\n- `search_in_resource()` - Search within page resources\n- `set_document_content()` - Set page HTML content\n\n### Screenshots & PDF\n- `capture_screenshot()` - Take page screenshots\n- `print_to_pdf()` - Generate PDF from page\n- `capture_snapshot()` - Capture page snapshots\n\n### JavaScript Execution\n- `add_script_to_evaluate_on_new_document()` - Add startup scripts\n- `remove_script_to_evaluate_on_new_document()` - Remove startup scripts\n\n### Page Settings\n- `set_lifecycle_events_enabled()` - Control lifecycle events\n- `set_ad_blocking_enabled()` - Enable/disable ad blocking\n- `set_bypass_csp()` - Bypass Content Security Policy\n\n## Advanced Features\n\n### Frame Management\n```python\n# Get all frames in the page\nframe_tree = await get_frame_tree(connection)\nfor frame in frame_tree.child_frames:\n print(f\"Frame: {frame.frame.url}\")\n```\n\n### Resource Interception\n```python\n# Get resource content\ncontent = await get_resource_content(\n connection, \n frame_id=frame_id, \n url=\"https://example.com/script.js\"\n)\n```\n\n### Page Events\nThe page commands work with various page events:\n- `Page.loadEventFired` - Page load completed\n- `Page.domContentEventFired` - DOM content loaded\n- `Page.frameNavigated` - Frame navigation\n- `Page.frameStartedLoading` - Frame loading started\n\n!!! tip \"Tab Class Integration\"\n Most page operations are available through the `Tab` class methods like `tab.go_to()`, `tab.reload()`, and `tab.screenshot()` which provide a more convenient API. " }, { "path": "docs/en/api/commands/runtime.md", "content": "# Runtime Commands\n\nRuntime commands provide JavaScript execution capabilities and runtime environment management.\n\n## Overview\n\nThe runtime commands module enables JavaScript code execution, object inspection, and runtime environment control within browser contexts.\n\n::: pydoll.commands.runtime_commands\n options:\n show_root_heading: true\n show_source: false\n heading_level: 2\n filters:\n - \"!^_\"\n - \"!^__\"\n\n## Usage\n\nRuntime commands are used for JavaScript execution and runtime management:\n\n```python\nfrom pydoll.commands.runtime_commands import evaluate, enable\nfrom pydoll.connection.connection_handler import ConnectionHandler\n\n# Enable runtime events\nconnection = ConnectionHandler()\nawait enable(connection)\n\n# Execute JavaScript\nresult = await evaluate(\n connection, \n expression=\"document.title\",\n return_by_value=True\n)\nprint(result.value) # Page title\n```\n\n## Key Functionality\n\nThe runtime commands module provides functions for:\n\n### JavaScript Execution\n- `evaluate()` - Execute JavaScript expressions\n- `call_function_on()` - Call functions on objects\n- `compile_script()` - Compile JavaScript for reuse\n- `run_script()` - Run compiled scripts\n\n### Object Management\n- `get_properties()` - Get object properties\n- `release_object()` - Release object references\n- `release_object_group()` - Release object groups\n\n### Runtime Control\n- `enable()` / `disable()` - Enable/disable runtime events\n- `discard_console_entries()` - Clear console entries\n- `set_custom_object_formatter_enabled()` - Enable custom formatters\n\n### Exception Handling\n- `set_async_call_stack_depth()` - Set call stack depth\n- Exception capture and reporting\n- Error object inspection\n\n## Advanced Usage\n\n### Complex JavaScript Execution\n```python\n# Execute complex JavaScript with error handling\nscript = \"\"\"\ntry {\n const elements = document.querySelectorAll('.item');\n return Array.from(elements).map(el => ({\n text: el.textContent,\n href: el.href\n }));\n} catch (error) {\n return { error: error.message };\n}\n\"\"\"\n\nresult = await evaluate(\n connection,\n expression=script,\n return_by_value=True,\n await_promise=True\n)\n```\n\n### Object Inspection\n```python\n# Get detailed object properties\nproperties = await get_properties(\n connection,\n object_id=object_id,\n own_properties=True,\n accessor_properties_only=False\n)\n\nfor prop in properties:\n print(f\"{prop.name}: {prop.value}\")\n```\n\n### Console Integration\nRuntime commands integrate with browser console:\n- Console messages and errors\n- Console API method calls\n- Custom console formatters\n\n!!! note \"Performance Considerations\"\n JavaScript execution through runtime commands can be slower than native browser execution. Use judiciously for complex operations. " }, { "path": "docs/en/api/commands/storage.md", "content": "# Storage Commands\n\nStorage commands provide comprehensive browser storage management including cookies, localStorage, sessionStorage, and IndexedDB.\n\n## Overview\n\nThe storage commands module enables management of all browser storage mechanisms, providing functionality for data persistence and retrieval.\n\n::: pydoll.commands.storage_commands\n options:\n show_root_heading: true\n show_source: false\n heading_level: 2\n filters:\n - \"!^_\"\n - \"!^__\"\n\n## Usage\n\nStorage commands are used for managing browser storage across different mechanisms:\n\n```python\nfrom pydoll.commands.storage_commands import get_cookies, set_cookies, clear_data_for_origin\nfrom pydoll.connection.connection_handler import ConnectionHandler\n\n# Get cookies for a domain\nconnection = ConnectionHandler()\ncookies = await get_cookies(connection, urls=[\"https://example.com\"])\n\n# Set a new cookie\nawait set_cookies(connection, cookies=[{\n \"name\": \"session_id\",\n \"value\": \"abc123\",\n \"domain\": \"example.com\",\n \"path\": \"/\",\n \"httpOnly\": True,\n \"secure\": True\n}])\n\n# Clear all storage for an origin\nawait clear_data_for_origin(\n connection,\n origin=\"https://example.com\",\n storage_types=\"all\"\n)\n```\n\n## Key Functionality\n\nThe storage commands module provides functions for:\n\n### Cookie Management\n- `get_cookies()` - Get cookies by URL or domain\n- `set_cookies()` - Set new cookies\n- `delete_cookies()` - Delete specific cookies\n- `clear_cookies()` - Clear all cookies\n\n### Local Storage\n- `get_dom_storage_items()` - Get localStorage items\n- `set_dom_storage_item()` - Set localStorage item\n- `remove_dom_storage_item()` - Remove localStorage item\n- `clear_dom_storage()` - Clear localStorage\n\n### Session Storage\n- Session storage operations (similar to localStorage)\n- Session-specific data management\n- Tab-isolated storage\n\n### IndexedDB\n- `get_database_names()` - Get IndexedDB databases\n- `request_database()` - Access database structure\n- `request_data()` - Query database data\n- `clear_object_store()` - Clear object stores\n\n### Cache Storage\n- `request_cache_names()` - Get cache names\n- `request_cached_response()` - Get cached responses\n- `delete_cache()` - Delete cache entries\n\n### Application Cache (Deprecated)\n- Legacy application cache support\n- Manifest-based caching\n\n## Advanced Features\n\n### Bulk Operations\n```python\n# Clear all storage types for multiple origins\norigins = [\"https://example.com\", \"https://api.example.com\"]\nfor origin in origins:\n await clear_data_for_origin(\n connection,\n origin=origin,\n storage_types=\"cookies,local_storage,session_storage,indexeddb\"\n )\n```\n\n### Storage Quotas\n```python\n# Get storage quota information\nquota_info = await get_usage_and_quota(connection, origin=\"https://example.com\")\nprint(f\"Used: {quota_info.usage} bytes\")\nprint(f\"Quota: {quota_info.quota} bytes\")\n```\n\n### Cross-Origin Storage\n```python\n# Manage storage across different origins\nawait set_cookies(connection, cookies=[{\n \"name\": \"cross_site_token\",\n \"value\": \"token123\",\n \"domain\": \".example.com\", # Applies to all subdomains\n \"sameSite\": \"None\",\n \"secure\": True\n}])\n```\n\n## Storage Types\n\nThe module supports various storage mechanisms:\n\n| Storage Type | Persistence | Scope | Capacity |\n|--------------|-------------|-------|----------|\n| Cookies | Persistent | Domain/Path | ~4KB per cookie |\n| localStorage | Persistent | Origin | ~5-10MB |\n| sessionStorage | Session | Tab | ~5-10MB |\n| IndexedDB | Persistent | Origin | Large (GB+) |\n| Cache API | Persistent | Origin | Large |\n\n!!! warning \"Privacy Considerations\"\n Storage operations can affect user privacy. Always handle storage data responsibly and in compliance with privacy regulations. " }, { "path": "docs/en/api/commands/target.md", "content": "# Target Commands\n\nTarget commands manage browser targets including tabs, windows, and other browsing contexts.\n\n## Overview\n\nThe target commands module provides functionality for creating, managing, and controlling browser targets such as tabs, popup windows, and service workers.\n\n::: pydoll.commands.target_commands\n options:\n show_root_heading: true\n show_source: false\n heading_level: 2\n filters:\n - \"!^_\"\n - \"!^__\"\n\n## Usage\n\nTarget commands are used internally by browser classes to manage tabs and windows:\n\n```python\nfrom pydoll.commands.target_commands import get_targets, create_target, close_target\nfrom pydoll.connection.connection_handler import ConnectionHandler\n\n# Get all browser targets\nconnection = ConnectionHandler()\ntargets = await get_targets(connection)\n\n# Create a new tab\nnew_target = await create_target(connection, url=\"https://example.com\")\n\n# Close a target\nawait close_target(connection, target_id=new_target.target_id)\n```\n\n## Key Functionality\n\nThe target commands module provides functions for:\n\n### Target Management\n- `get_targets()` - List all browser targets\n- `create_target()` - Create new tabs or windows\n- `close_target()` - Close specific targets\n- `activate_target()` - Bring target to foreground\n\n### Target Information\n- `get_target_info()` - Get detailed target information\n- Target types: page, background_page, service_worker, browser\n- Target states: attached, detached, crashed\n\n### Session Management\n- `attach_to_target()` - Attach to target for control\n- `detach_from_target()` - Detach from target\n- `send_message_to_target()` - Send commands to targets\n\n### Browser Context\n- `create_browser_context()` - Create isolated browser context\n- `dispose_browser_context()` - Remove browser context\n- `get_browser_contexts()` - List browser contexts\n\n## Target Types\n\nDifferent types of targets can be managed:\n\n### Page Targets\n```python\n# Create a new tab\npage_target = await create_target(\n connection,\n url=\"https://example.com\",\n width=1920,\n height=1080,\n browser_context_id=None # Default context\n)\n```\n\n### Popup Windows\n```python\n# Create a popup window\npopup_target = await create_target(\n connection,\n url=\"https://popup.example.com\",\n width=800,\n height=600,\n new_window=True\n)\n```\n\n### Incognito Contexts\n```python\n# Create incognito browser context\nincognito_context = await create_browser_context(connection)\n\n# Create tab in incognito context\nincognito_tab = await create_target(\n connection,\n url=\"https://private.example.com\",\n browser_context_id=incognito_context.browser_context_id\n)\n```\n\n!!! info \"Headless vs Headed: how contexts show up\"\n Browser contexts are isolated logical environments. In headed mode, the first page created inside a new context will usually open in a new OS window. In headless mode, no window is shown — the isolation remains purely logical (cookies, storage, cache and auth state are still separate per context). Prefer contexts in headless/CI pipelines for performance and clean isolation.\n\n## Advanced Features\n\n### Target Events\nTarget commands work with various target events:\n- `Target.targetCreated` - New target created\n- `Target.targetDestroyed` - Target closed\n- `Target.targetInfoChanged` - Target information updated\n- `Target.targetCrashed` - Target crashed\n\n### Multi-Target Coordination\n```python\n# Manage multiple tabs\ntargets = await get_targets(connection)\npage_targets = [t for t in targets if t.type == \"page\"]\n\nfor target in page_targets:\n # Perform operations on each tab\n await activate_target(connection, target_id=target.target_id)\n # ... do work in this tab\n```\n\n### Target Isolation\n```python\n# Create isolated browser context for testing\ntest_context = await create_browser_context(connection)\n\n# All targets in this context are isolated\ntest_tab1 = await create_target(\n connection, \n url=\"https://test1.com\",\n browser_context_id=test_context.browser_context_id\n)\n\ntest_tab2 = await create_target(\n connection,\n url=\"https://test2.com\", \n browser_context_id=test_context.browser_context_id\n)\n```\n\n!!! note \"Browser Integration\"\n Target commands are primarily used internally by the `Chrome` and `Edge` browser classes. The high-level browser APIs provide more convenient methods for tab management. " }, { "path": "docs/en/api/connection/connection.md", "content": "# Connection Handler\n\n::: pydoll.connection.connection_handler.ConnectionHandler\n options:\n show_root_heading: true\n show_source: false\n heading_level: 2" }, { "path": "docs/en/api/connection/managers.md", "content": "# Connection Managers\n\n## CommandsManager\n\n::: pydoll.connection.managers.commands_manager.CommandsManager\n options:\n show_root_heading: true\n show_source: false\n heading_level: 3\n\n## EventsManager\n\n::: pydoll.connection.managers.events_manager.EventsManager\n options:\n show_root_heading: true\n show_source: false\n heading_level: 3 " }, { "path": "docs/en/api/core/constants.md", "content": "# Constants\n\nThis section documents all constants, enums, and configuration values used throughout Pydoll.\n\n::: pydoll.constants\n options:\n show_root_heading: true\n show_source: false\n heading_level: 2\n group_by_category: true\n members_order: source " }, { "path": "docs/en/api/core/exceptions.md", "content": "# Exceptions\n\nThis section documents all custom exceptions that can be raised by Pydoll operations.\n\n::: pydoll.exceptions\n options:\n show_root_heading: true\n show_source: false\n heading_level: 2\n group_by_category: true\n members_order: source " }, { "path": "docs/en/api/core/utils.md", "content": "# Utilities\n\nThis section documents utility functions and helper classes used throughout Pydoll.\n\n::: pydoll.utils\n options:\n show_root_heading: true\n show_source: false\n heading_level: 2\n group_by_category: true\n members_order: source " }, { "path": "docs/en/api/elements/mixins.md", "content": "# Element Mixins\n\nThe mixins module provides reusable functionality that can be mixed into element classes to extend their capabilities.\n\n## Find Elements Mixin\n\nThe `FindElementsMixin` provides element finding capabilities to classes that include it.\n\n::: pydoll.elements.mixins.find_elements_mixin\n options:\n show_root_heading: true\n show_source: false\n heading_level: 2\n filters:\n - \"!^_\"\n - \"!^__\"\n\n## Usage\n\nMixins are typically used internally by the library to compose functionality. The `FindElementsMixin` is used by classes like `Tab` and `WebElement` to provide element finding methods:\n\n```python\n# These methods come from FindElementsMixin\nelement = await tab.find(id=\"username\")\nelements = await tab.find(class_name=\"item\", find_all=True)\nelement = await tab.query(\"#submit-button\")\n```\n\n## Available Methods\n\nThe `FindElementsMixin` provides several methods for finding elements:\n\n- `find()` - Modern element finding with keyword arguments\n- `query()` - CSS selector and XPath queries\n- `find_element()` - Legacy element finding method\n- `find_elements()` - Legacy method for finding multiple elements\n\n!!! tip \"Modern vs Legacy\"\n The `find()` method is the modern, recommended approach for finding elements. The `find_element()` and `find_elements()` methods are maintained for backward compatibility. " }, { "path": "docs/en/api/elements/shadow_root.md", "content": "# ShadowRoot\n\n::: pydoll.elements.shadow_root.ShadowRoot\n options:\n show_root_heading: true\n show_source: false\n heading_level: 2\n members_order: source\n group_by_category: true\n" }, { "path": "docs/en/api/elements/web_element.md", "content": "# WebElement\n\n::: pydoll.elements.web_element.WebElement\n options:\n show_root_heading: true\n show_source: false\n heading_level: 2\n members_order: source\n group_by_category: true " }, { "path": "docs/en/api/index.md", "content": "# API Reference\n\nWelcome to the Pydoll API Reference! This section provides comprehensive documentation for all classes, methods, and functions available in the Pydoll library.\n\n## Overview\n\nPydoll is organized into several key modules, each serving a specific purpose in browser automation:\n\n### Browser Module\nThe browser module contains classes for managing browser instances and their lifecycle.\n\n- **[Chrome](browser/chrome.md)** - Chrome browser automation\n- **[Edge](browser/edge.md)** - Microsoft Edge browser automation \n- **[Options](browser/options.md)** - Browser configuration options\n- **[Tab](browser/tab.md)** - Tab management and interaction\n- **[Requests](browser/requests.md)** - HTTP requests within browser context\n- **[Managers](browser/managers.md)** - Browser lifecycle managers\n\n### Elements Module\nThe elements module provides classes for interacting with web page elements.\n\n- **[WebElement](elements/web_element.md)** - Individual element interaction\n- **[Mixins](elements/mixins.md)** - Reusable element functionality\n\n### Connection Module\nThe connection module handles communication with the browser through the Chrome DevTools Protocol.\n\n- **[Connection Handler](connection/connection.md)** - WebSocket connection management\n- **[Managers](connection/managers.md)** - Connection lifecycle managers\n\n### Commands Module\nThe commands module provides low-level Chrome DevTools Protocol command implementations.\n\n- **[Commands Overview](commands/index.md)** - CDP command implementations by domain\n\n### Protocol Module\nThe protocol module implements the Chrome DevTools Protocol commands and events.\n\n- **[Base Types](protocol/base.md)** - Base types for Chrome DevTools Protocol\n- **[Browser](protocol/browser.md)** - Browser domain commands and events\n- **[DOM](protocol/dom.md)** - DOM domain commands and events\n- **[Fetch](protocol/fetch.md)** - Fetch domain commands and events\n- **[Input](protocol/input.md)** - Input domain commands and events\n- **[Network](protocol/network.md)** - Network domain commands and events\n- **[Page](protocol/page.md)** - Page domain commands and events\n- **[Runtime](protocol/runtime.md)** - Runtime domain commands and events\n- **[Storage](protocol/storage.md)** - Storage domain commands and events\n- **[Target](protocol/target.md)** - Target domain commands and events\n\n### Core Module\nThe core module contains fundamental utilities, constants, and exceptions.\n\n- **[Constants](core/constants.md)** - Library constants and enums\n- **[Exceptions](core/exceptions.md)** - Custom exception classes\n- **[Utils](core/utils.md)** - Utility functions\n\n## Quick Navigation\n\n### Most Common Classes\n\n| Class | Purpose | Module |\n|-------|---------|--------|\n| `Chrome` | Chrome browser automation | `pydoll.browser.chromium` |\n| `Edge` | Edge browser automation | `pydoll.browser.chromium` |\n| `Tab` | Tab interaction and control | `pydoll.browser.tab` |\n| `WebElement` | Element interaction | `pydoll.elements.web_element` |\n| `ChromiumOptions` | Browser configuration | `pydoll.browser.options` |\n\n### Key Enums and Constants\n\n| Name | Purpose | Module |\n|------|---------|--------|\n| `By` | Element selector strategies | `pydoll.constants` |\n| `Key` | Keyboard key constants | `pydoll.constants` |\n| `PermissionType` | Browser permission types | `pydoll.constants` |\n\n### Common Exceptions\n\n| Exception | When Raised | Module |\n|-----------|-------------|--------|\n| `ElementNotFound` | Element not found in DOM | `pydoll.exceptions` |\n| `WaitElementTimeout` | Element wait timeout | `pydoll.exceptions` |\n| `BrowserNotStarted` | Browser not started | `pydoll.exceptions` |\n\n## Usage Patterns\n\n### Basic Browser Automation\n\n```python\nfrom pydoll.browser.chromium import Chrome\n\nasync with Chrome() as browser:\n tab = await browser.start()\n await tab.go_to(\"https://example.com\")\n element = await tab.find(id=\"my-element\")\n await element.click()\n```\n\n### Element Finding\n\n```python\n# Using the modern find() method\nelement = await tab.find(id=\"username\")\nelement = await tab.find(tag_name=\"button\", class_name=\"submit\")\n\n# Using CSS selectors or XPath\nelement = await tab.query(\"#username\")\nelement = await tab.query(\"//button[@class='submit']\")\n```\n\n### Event Handling\n\n```python\nawait tab.enable_page_events()\nawait tab.on('Page.loadEventFired', handle_page_load)\n```\n\n## Type Hints\n\nPydoll is fully typed and provides comprehensive type hints for better IDE support and code safety. All public APIs include proper type annotations.\n\n```python\nfrom typing import Optional, List\nfrom pydoll.elements.web_element import WebElement\n\n# Methods return properly typed objects\nelement: Optional[WebElement] = await tab.find(id=\"test\", raise_exc=False)\nelements: List[WebElement] = await tab.find(class_name=\"item\", find_all=True)\n```\n\n## Async/Await Support\n\nAll Pydoll operations are asynchronous and must be used with `async`/`await`:\n\n```python\nimport asyncio\n\nasync def main():\n # All Pydoll operations are async\n async with Chrome() as browser:\n tab = await browser.start()\n await tab.go_to(\"https://example.com\")\n \nasyncio.run(main())\n```\n\nBrowse the sections below to explore the complete API documentation for each module. " }, { "path": "docs/en/api/protocol/base.md", "content": "# Protocol Base Types\n\nBase types and structures for Chrome DevTools Protocol commands, responses, and events.\n\n## Base Types\n\n::: pydoll.protocol.base\n options:\n show_root_heading: true\n show_source: false\n heading_level: 3\n group_by_category: true\n members_order: source\n filters:\n - \"!^__\"" }, { "path": "docs/en/api/protocol/browser.md", "content": "# Browser Protocol\n\nBrowser domain commands, events and types for Chrome DevTools Protocol.\n\n## Methods\n\n::: pydoll.protocol.browser.methods\n options:\n show_root_heading: true\n show_source: false\n heading_level: 2\n\n## Events \n\n::: pydoll.protocol.browser.events\n options:\n show_root_heading: true\n show_source: false\n heading_level: 2\n\n## Types\n\n::: pydoll.protocol.browser.types\n options:\n show_root_heading: true\n show_source: false\n heading_level: 2" }, { "path": "docs/en/api/protocol/dom.md", "content": "# DOM Protocol\n\nDOM domain commands and events for Chrome DevTools Protocol.\n\n## Methods\n\n::: pydoll.protocol.dom.methods\n options:\n show_root_heading: true\n show_source: false\n heading_level: 2\n\n## Events\n\n::: pydoll.protocol.dom.events\n options:\n show_root_heading: true\n show_source: false\n heading_level: 2\n\n## Types\n\n::: pydoll.protocol.dom.types\n options:\n show_root_heading: true\n show_source: false\n heading_level: 2" }, { "path": "docs/en/api/protocol/fetch.md", "content": "# Fetch Protocol\n\nFetch domain commands, events and types for Chrome DevTools Protocol.\n\n## Methods\n\n::: pydoll.protocol.fetch.methods\n options:\n show_root_heading: true\n show_source: false\n heading_level: 2\n\n## Events\n\n::: pydoll.protocol.fetch.events\n options:\n show_root_heading: true\n show_source: false\n heading_level: 2\n\n## Types\n\n::: pydoll.protocol.fetch.types\n options:\n show_root_heading: true\n show_source: false\n heading_level: 2" }, { "path": "docs/en/api/protocol/input.md", "content": "# Input Protocol\n\nInput domain commands, events and types for Chrome DevTools Protocol.\n\n## Methods\n\n::: pydoll.protocol.input.methods\n options:\n show_root_heading: true\n show_source: false\n heading_level: 2\n\n## Events\n\n::: pydoll.protocol.input.events\n options:\n show_root_heading: true\n show_source: false\n heading_level: 2\n\n## Types\n\n::: pydoll.protocol.input.types\n options:\n show_root_heading: true\n show_source: false\n heading_level: 2" }, { "path": "docs/en/api/protocol/network.md", "content": "# Network Protocol\n\nNetwork domain commands and events for Chrome DevTools Protocol.\n\n## Methods\n\n::: pydoll.protocol.network.methods\n options:\n show_root_heading: false\n show_source: false\n heading_level: 2\n\n## Events\n\n::: pydoll.protocol.network.events\n options:\n show_root_heading: false\n show_source: false\n heading_level: 2\n\n## Types\n\n::: pydoll.protocol.network.types\n options:\n show_root_heading: false\n show_source: false\n heading_level: 2" }, { "path": "docs/en/api/protocol/page.md", "content": "# Page Protocol\n\nPage domain commands, events and types for Chrome DevTools Protocol.\n\n## Methods\n\n::: pydoll.protocol.page.methods\n options:\n show_root_heading: true\n show_source: false\n heading_level: 2\n\n## Events\n\n::: pydoll.protocol.page.events\n options:\n show_root_heading: true\n show_source: false\n heading_level: 2\n\n## Types\n\n::: pydoll.protocol.page.types\n options:\n show_root_heading: true\n show_source: false\n heading_level: 2" }, { "path": "docs/en/api/protocol/runtime.md", "content": "# Runtime Protocol\n\nRuntime domain commands, events and types for Chrome DevTools Protocol.\n\n## Methods\n\n::: pydoll.protocol.runtime.methods\n options:\n show_root_heading: true\n show_source: false\n heading_level: 2\n\n## Events\n\n::: pydoll.protocol.runtime.events\n options:\n show_root_heading: true\n show_source: false\n heading_level: 2\n\n## Types\n\n::: pydoll.protocol.runtime.types\n options:\n show_root_heading: true\n show_source: false\n heading_level: 2" }, { "path": "docs/en/api/protocol/storage.md", "content": "# Storage Protocol\n\nStorage domain commands, events and types for Chrome DevTools Protocol.\n\n## Methods\n\n::: pydoll.protocol.storage.methods\n options:\n show_root_heading: true\n show_source: false\n heading_level: 2\n\n## Events\n\n::: pydoll.protocol.storage.events\n options:\n show_root_heading: true\n show_source: false\n heading_level: 2\n\n## Types\n\n::: pydoll.protocol.storage.types\n options:\n show_root_heading: true\n show_source: false\n heading_level: 2" }, { "path": "docs/en/api/protocol/target.md", "content": "# Target Protocol\n\nTarget domain commands and events for Chrome DevTools Protocol.\n\n## Methods\n\n::: pydoll.protocol.target.methods\n options:\n show_root_heading: true\n show_source: false\n heading_level: 2\n\n## Events\n\n::: pydoll.protocol.target.events\n options:\n show_root_heading: true\n show_source: false\n heading_level: 2\n\n## Types\n\n::: pydoll.protocol.target.types\n options:\n show_root_heading: true\n show_source: false\n heading_level: 2" }, { "path": "docs/en/deep-dive/architecture/browser-domain.md", "content": "# Browser Domain Architecture\n\nThe Browser domain represents the highest level of Pydoll's automation hierarchy, managing the browser process lifecycle, CDP connections, context isolation, and global browser operations. This document explores the internal architecture, design decisions, and technical implementation of browser-level control.\n\n!!! info \"Practical Usage Guide\"\n For practical examples and usage patterns, see the [Browser Management](../features/browser-management/tabs.md) and [Browser Contexts](../features/browser-management/contexts.md) guides.\n\n## Architectural Overview\n\nThe Browser domain sits at the intersection of process management, protocol communication, and resource coordination. It orchestrates multiple specialized components to provide a unified interface for browser automation:\n\n```mermaid\ngraph LR\n Browser[Browser Instance]\n Browser --> ProcessManager[Process Manager]\n Browser --> ProxyManager[Proxy Manager]\n Browser --> TempDirManager[Temp Directory Manager]\n Browser --> TabRegistry[Tab Registry]\n Browser --> ConnectionHandler[Connection Handler]\n \n ProcessManager --> |Manages| BrowserProcess[Browser Process]\n ConnectionHandler <--> |WebSocket| CDP[Chrome DevTools Protocol]\n TabRegistry --> |Manages| Tabs[Tab Instances]\n CDP <--> BrowserProcess\n```\n\n### Hierarchy and Abstraction\n\nThe Browser domain is implemented as an **abstract base class** that defines the contract for all browser implementations:\n\n```python\nclass Browser(ABC):\n \"\"\"Abstract base class for browser automation via CDP.\"\"\"\n \n @abstractmethod\n def _get_default_binary_location(self) -> str:\n \"\"\"Subclasses must provide browser-specific executable path.\"\"\"\n pass\n \n async def start(self, headless: bool = False) -> Tab:\n \"\"\"Concrete implementation shared by all browsers.\"\"\"\n # 1. Resolve binary location\n # 2. Setup user data directory\n # 3. Start browser process\n # 4. Verify CDP connection\n # 5. Configure proxy (if needed)\n # 6. Return initial tab\n```\n\nThis design enables **polymorphism** - Chrome, Edge, and other Chromium-based browsers share 99% of their code, differing only in executable paths and minor flag variations.\n\n## Component Architecture\n\nThe Browser class coordinates several specialized managers, each responsible for a specific aspect of browser automation. Understanding these components is key to understanding Pydoll's design.\n\n### Connection Handler\n\nThe ConnectionHandler is the **communication bridge** between Pydoll and the browser process. It manages:\n\n- **WebSocket lifecycle**: Connection establishment, keep-alive, reconnection\n- **Command execution**: Sending CDP commands and awaiting responses\n- **Event dispatching**: Routing CDP events to registered callbacks\n- **Callback registry**: Maintaining event listeners per connection\n\n```python\nclass Browser:\n def __init__(self, ...):\n # ConnectionHandler is initialized with port or WebSocket address\n self._connection_handler = ConnectionHandler(self._connection_port)\n \n async def _execute_command(self, command, timeout=10):\n \"\"\"All CDP commands flow through the connection handler.\"\"\"\n return await self._connection_handler.execute_command(command, timeout)\n```\n\n!!! info \"Connection Layer Deep Dive\"\n For detailed information on WebSocket communication, command/response flow, and async patterns, see [Connection Layer Architecture](./connection-layer.md).\n\n### Process Manager\n\nThe BrowserProcessManager handles **operating system process lifecycle**:\n\n```python\nclass BrowserProcessManager:\n def start_browser_process(self, binary, port, arguments):\n \"\"\"\n 1. Constructs command-line with binary path + arguments\n 2. Spawns subprocess with proper stdio handling\n 3. Monitors process startup\n 4. Stores process handle for later termination\n \"\"\"\n \n def stop_process(self):\n \"\"\"\n 1. Attempts graceful termination (SIGTERM)\n 2. Waits for process exit\n 3. Force-kills if timeout exceeded (SIGKILL)\n 4. Cleans up process resources\n \"\"\"\n```\n\n**Why separate process management?**\n\n- **Testability**: Process manager can be mocked for unit tests\n- **Cross-platform**: Encapsulates OS-specific process handling\n- **Reliability**: Handles edge cases like zombie processes, orphaned children\n\n### Tab Registry\n\nThe Browser maintains a **registry of Tab instances** to ensure singleton behavior per target:\n\n```python\nclass Browser:\n def __init__(self, ...):\n self._tabs_opened: dict[str, Tab] = {}\n \n async def new_tab(self, url='', browser_context_id=None) -> Tab:\n # Create target via CDP\n response = await self._execute_command(\n TargetCommands.create_target(browser_context_id=browser_context_id)\n )\n target_id = response['result']['targetId']\n \n # Check if tab already exists in registry\n if target_id in self._tabs_opened:\n return self._tabs_opened[target_id]\n \n # Create new Tab instance and register it\n tab = Tab(self, target_id=target_id, ...)\n self._tabs_opened[target_id] = tab\n return tab\n```\n\n**Why singleton Tab instances?**\n\n- **State consistency**: Multiple references to same tab share state (enabled domains, callbacks)\n- **Memory efficiency**: Prevents duplicate Tab instances for same target\n- **Event routing**: Ensures events route to correct Tab instance\n\n### Proxy Authentication Architecture\n\nPydoll implements **automatic proxy authentication** via the Fetch domain to avoid exposing credentials in CDP commands. The implementation uses **two distinct mechanisms** depending on proxy scope:\n\n#### Mechanism 1: Browser-Level Proxy Auth (Global Proxy)\n\nWhen a proxy is configured via `ChromiumOptions` (applies to all tabs in the default context):\n\n```python\n# In Browser.start() -> _configure_proxy()\nasync def _configure_proxy(self, private_proxy, proxy_credentials):\n # Enable Fetch AT BROWSER LEVEL\n await self.enable_fetch_events(handle_auth_requests=True)\n \n # Register callbacks AT BROWSER LEVEL (affects ALL tabs)\n await self.on(FetchEvent.REQUEST_PAUSED, self._continue_request_callback, temporary=True)\n await self.on(FetchEvent.AUTH_REQUIRED, \n partial(self._continue_request_with_auth_callback,\n proxy_username=credentials[0],\n proxy_password=credentials[1]),\n temporary=True)\n```\n\n**Scope:** Browser-wide WebSocket connection → affects **all tabs in default context**\n\n#### Mechanism 2: Tab-Level Proxy Auth (Per-Context Proxy)\n\nWhen a proxy is configured per-context via `create_browser_context(proxy_server=...)`:\n\n```python\n# Store credentials per context\nasync def create_browser_context(self, proxy_server, ...):\n sanitized_proxy, extracted_auth = self._sanitize_proxy_and_extract_auth(proxy_server)\n \n response = await self._execute_command(\n TargetCommands.create_browser_context(proxy_server=sanitized_proxy)\n )\n context_id = response['result']['browserContextId']\n \n if extracted_auth:\n self._context_proxy_auth[context_id] = extracted_auth # Store per context\n \n return context_id\n\n# Setup auth for EACH tab in that context\nasync def _setup_context_proxy_auth_for_tab(self, tab, browser_context_id):\n creds = self._context_proxy_auth.get(browser_context_id)\n if not creds:\n return\n \n # Enable Fetch ON THE TAB (tab-level WebSocket)\n await tab.enable_fetch_events(handle_auth=True)\n \n # Register callbacks ON THE TAB (affects only this tab)\n await tab.on(FetchEvent.REQUEST_PAUSED, \n partial(self._tab_continue_request_callback, tab=tab), \n temporary=True)\n await tab.on(FetchEvent.AUTH_REQUIRED,\n partial(self._tab_continue_request_with_auth_callback,\n tab=tab,\n proxy_username=creds[0],\n proxy_password=creds[1]),\n temporary=True)\n```\n\n**Scope:** Tab-level WebSocket connection → affects **only that specific tab**\n\n#### Why Two Mechanisms?\n\n| Aspect | Browser-Level | Tab-Level |\n|--------|---------------|-----------|\n| **Trigger** | Proxy in `ChromiumOptions` | Proxy in `create_browser_context()` |\n| **WebSocket** | Browser-level connection | Tab-level connection |\n| **Scope** | All tabs in default context | Only tabs in that context |\n| **Efficiency** | One listener for all tabs | One listener per tab |\n| **Isolation** | No context separation | Each context has different credentials |\n\n**Design rationale for tab-level auth:**\n\n- **Context isolation**: Each context can have a **different proxy** with **different credentials**\n- **CDP limitation**: Fetch domain cannot be scoped to a specific context at browser level\n- **Tradeoff**: Slightly less efficient (one listener per tab), but necessary for per-context proxy support\n\nThis architecture ensures **credentials never appear in CDP logs** and authentication is handled transparently.\n\n!!! warning \"Fetch Domain Side Effects\"\n - **Browser-level Fetch**: Temporarily pauses **all requests across all tabs** in the default context until auth completes\n - **Tab-level Fetch**: Temporarily pauses **all requests in that specific tab** until auth completes\n \n This is a CDP limitation - Fetch enables request interception. After authentication completes, Fetch is disabled to minimize overhead.\n\n## Initialization and Lifecycle\n\n### Constructor Design\n\nThe Browser constructor initializes all internal components but **does not start the browser process**. This separation allows configuration before launch:\n\n```python\nclass Browser(ABC):\n def __init__(\n self,\n options_manager: BrowserOptionsManager,\n connection_port: Optional[int] = None,\n ):\n # 1. Validate parameters\n self._validate_connection_port(connection_port)\n \n # 2. Initialize options via manager\n self.options = options_manager.initialize_options()\n \n # 3. Determine CDP port (random if not specified)\n self._connection_port = connection_port or randint(9223, 9322)\n \n # 4. Initialize specialized managers\n self._proxy_manager = ProxyManager(self.options)\n self._browser_process_manager = BrowserProcessManager()\n self._temp_directory_manager = TempDirectoryManager()\n self._connection_handler = ConnectionHandler(self._connection_port)\n \n # 5. Initialize state tracking\n self._tabs_opened: dict[str, Tab] = {}\n self._context_proxy_auth: dict[str, tuple[str, str]] = {}\n self._ws_address: Optional[str] = None\n```\n\n**Key design decisions:**\n\n- **Lazy process start**: Constructor is synchronous; `start()` is async\n- **Port flexibility**: Random port prevents collisions in parallel automation\n- **Options manager pattern**: Strategy pattern for browser-specific configuration\n- **Component composition**: Specialized managers instead of monolithic class\n\n### Start Sequence\n\nThe `start()` method orchestrates browser launch and connection:\n\n```python\nasync def start(self, headless: bool = False) -> Tab:\n # 1. Resolve binary location\n binary_location = self.options.binary_location or self._get_default_binary_location()\n \n # 2. Setup user data directory (temp or persistent)\n self._setup_user_dir()\n \n # 3. Extract proxy credentials (if private proxy)\n proxy_config = self._proxy_manager.get_proxy_credentials()\n \n # 4. Start browser process with arguments\n self._browser_process_manager.start_browser_process(\n binary_location, self._connection_port, self.options.arguments\n )\n \n # 5. Verify CDP endpoint is responsive\n await self._verify_browser_running()\n \n # 6. Configure proxy authentication (via Fetch domain)\n await self._configure_proxy(proxy_config[0], proxy_config[1])\n \n # 7. Get first valid target and create Tab\n valid_tab_id = await self._get_valid_tab_id(await self.get_targets())\n tab = Tab(self, target_id=valid_tab_id, connection_port=self._connection_port)\n self._tabs_opened[valid_tab_id] = tab\n \n return tab\n```\n\n!!! tip \"Why start() Returns a Tab\"\n This is a **design compromise** for ergonomics. Ideally, `start()` would only launch the browser, and users would call `new_tab()` separately. However, returning the initial tab reduces boilerplate for the 90% use case (single-tab automation). The tradeoff: the initial tab cannot be avoided even in multi-tab scenarios.\n\n### Context Manager Protocol\n\nThe Browser implements `__aenter__` and `__aexit__` for automatic cleanup:\n\n```python\nasync def __aexit__(self, exc_type, exc_val, exc_tb):\n # 1. Restore backup preferences (if modified)\n if self._backup_preferences_dir:\n shutil.copy2(self._backup_preferences_dir, ...)\n \n # 2. Check if browser is still running\n if await self._is_browser_running(timeout=2):\n await self.stop()\n \n # 3. Close WebSocket connection\n await self._connection_handler.close()\n```\n\nThis ensures proper cleanup even if exceptions occur during automation.\n\n## Browser Context Architecture\n\nBrowser contexts are Pydoll's most sophisticated isolation mechanism, providing **complete browsing environment separation** within a single browser process. Understanding their architecture is essential for advanced automation.\n\n### CDP Hierarchy: Browser, Context, Target\n\nCDP organizes browser structure into three levels:\n\n```mermaid\ngraph TB\n Browser[Browser Process]\n Browser --> DefaultContext[Default BrowserContext]\n Browser --> Context1[BrowserContext ID: abc-123]\n Browser --> Context2[BrowserContext ID: def-456]\n \n DefaultContext --> Target1[Target/Page ID: page-1]\n DefaultContext --> Target2[Target/Page ID: page-2]\n \n Context1 --> Target3[Target/Page ID: page-3]\n \n Context2 --> Target4[Target/Page ID: page-4]\n Context2 --> Target5[Target/Page ID: page-5]\n```\n\n**Key concepts:**\n\n1. **Browser Process**: Single Chromium instance with one CDP endpoint\n2. **BrowserContext**: Isolated storage/cache/permission boundary (similar to incognito mode)\n3. **Target**: Individual page, popup, worker, or background target\n\n### Context Isolation Boundaries\n\nEach browser context maintains **strict isolation** for:\n\n| Resource | Isolation Level | Implementation |\n|----------|----------------|----------------|\n| Cookies | Full | Separate cookie jar per context |\n| localStorage | Full | Separate storage per origin per context |\n| IndexedDB | Full | Separate database per origin per context |\n| Cache | Full | Independent HTTP cache per context |\n| Permissions | Full | Context-specific permission grants |\n| Network proxy | Full | Per-context proxy configuration |\n| Authentication | Full | Independent auth state per context |\n\n!!! info \"Why Contexts Are Lightweight\"\n Unlike launching multiple browser processes, contexts share the **rendering engine, GPU process, and network stack**. Only storage and state are isolated. This makes contexts 10-100x faster to create than new browser instances.\n\n### Context Creation and Target Binding\n\nCreating a context and target involves two CDP commands:\n\n```python\n# Step 1: Create isolated browsing context\nresponse = await self._execute_command(\n TargetCommands.create_browser_context(\n proxy_server='http://proxy.example.com:8080',\n proxy_bypass_list='localhost,127.0.0.1'\n )\n)\ncontext_id = response['result']['browserContextId']\n\n# Step 2: Create target (page) within that context\nresponse = await self._execute_command(\n TargetCommands.create_target(\n browser_context_id=context_id # Binds target to context\n )\n)\ntarget_id = response['result']['targetId']\n```\n\n**Critical detail:** The `browser_context_id` parameter **binds the target to the context's isolation boundary**. Without it, the target is created in the default context.\n\n### Window Materialization in Headed Mode\n\nIn **headed mode** (visible UI), browser contexts have an important physical constraint:\n\n- A context initially exists only **in memory** (no window)\n- The **first target** created in a context **must** open a top-level window\n- **Subsequent targets** can open as tabs within that window\n\nThis is a **CDP/Chromium limitation**, not a Pydoll design choice:\n\n```python\n# First target in context: MUST create window\ntab1 = await browser.new_tab(browser_context_id=context_id) # Opens new window\n\n# Subsequent targets: CAN open as tabs in existing window\ntab2 = await browser.new_tab(browser_context_id=context_id) # Opens as tab\n```\n\n**Why does this matter?**\n\n- In **headless mode**: Completely irrelevant (no windows rendered)\n- In **headed mode**: First target per context will open a visible window\n- In **test environments**: Multiple contexts → multiple windows (can be confusing)\n\n!!! tip \"Headless Contexts Are Cleaner\"\n For CI/CD, scraping, or batch automation, use headless mode. Context isolation works identically, but without window materialization overhead.\n\n### Context Deletion and Cleanup\n\nDeleting a context **immediately closes all targets** within it:\n\n```python\nawait browser.delete_browser_context(context_id)\n# All tabs in this context are now closed\n# All storage for this context is cleared\n# Context cannot be reused (ID is invalid)\n```\n\n**Cleanup sequence:**\n\n1. CDP sends `Target.disposeBrowserContext` command\n2. Browser closes all targets in that context\n3. Browser clears all storage for that context\n4. Browser invalidates the context ID\n5. Pydoll removes context from internal registries\n\n## Event System at Browser Level\n\nThe Browser domain supports **browser-wide event listeners** that operate across all tabs and contexts. This is distinct from tab-level events.\n\n### Browser vs Tab Event Scope\n\n```python\n# Browser-level event: applies to ALL tabs\nawait browser.on('Target.targetCreated', handle_new_target)\n\n# Tab-level event: applies to ONE tab\nawait tab.on('Page.loadEventFired', handle_page_load)\n```\n\n**Architectural difference:**\n\n- **Browser events** use the **browser-level WebSocket connection** (port-based or `ws://host/devtools/browser/...`)\n- **Tab events** use **tab-level WebSocket connections** (`ws://host/devtools/page/`)\n\n### Fetch Domain: Global Request Interception\n\nThe Fetch domain can be enabled at **both** browser and tab levels, with different scopes:\n\n```python\n# Browser-level Fetch: intercepts requests for ALL tabs\nawait browser.enable_fetch_events(handle_auth_requests=True)\nawait browser.on('Fetch.requestPaused', handle_request)\n\n# Tab-level Fetch: intercepts requests for ONE tab\nawait tab.enable_fetch_events(handle_auth_requests=True)\nawait tab.on('Fetch.requestPaused', handle_request)\n```\n\n**When to use each:**\n\n| Use Case | Level | Reason |\n|----------|-------|--------|\n| Proxy authentication | Browser | Applies globally to all contexts |\n| Ad blocking | Browser | Block ads across all tabs |\n| API mocking | Tab | Mock specific API for specific test |\n| Request logging | Tab | Log only relevant tab's requests |\n\n!!! warning \"Fetch Performance Impact\"\n Enabling Fetch at the browser level **pauses all requests** across all tabs until callbacks execute. This adds latency to every request. Use tab-level Fetch when possible to minimize impact.\n\n### Command Routing\n\nAll CDP commands flow through the Browser's connection handler:\n\n```python\nasync def _execute_command(self, command, timeout=10):\n \"\"\"\n Routes command to appropriate connection:\n - Browser-level commands → browser WebSocket\n - Tab-level commands → delegated to Tab instance\n \"\"\"\n return await self._connection_handler.execute_command(command, timeout)\n```\n\nThis centralized routing enables:\n\n- **Request/response correlation**: Match responses to requests via ID\n- **Timeout management**: Cancel commands that exceed timeout\n- **Error handling**: Convert CDP errors to Python exceptions\n\n## Resource Management\n\n### Cookie and Storage Operations\n\nThe Browser domain exposes **browser-wide** and **context-specific** storage operations:\n\n```python\n# Browser-level operations (all contexts)\nawait browser.set_cookies(cookies)\nawait browser.get_cookies()\nawait browser.delete_all_cookies()\n\n# Context-specific operations\nawait browser.set_cookies(cookies, browser_context_id=context_id)\nawait browser.get_cookies(browser_context_id=context_id)\nawait browser.delete_all_cookies(browser_context_id=context_id)\n```\n\nThese operations use the **Storage domain** under the hood:\n\n- `Storage.getCookies`: Retrieve cookies for context or all contexts\n- `Storage.setCookies`: Set cookies with domain/path/expiry\n- `Storage.clearCookies`: Clear cookies for context or all contexts\n\n!!! info \"Browser vs Tab Storage Scope\"\n - **Browser-level**: Operates on entire browser or specific context\n - **Tab-level**: Scoped to tab's current origin\n \n Use browser-level for global cookie management (e.g., setting session cookies for all domains). Use tab-level for origin-specific operations (e.g., clearing cookies after logout).\n\n### Permission Grants\n\nThe Browser domain provides **programmatic permission control**, bypassing browser prompts:\n\n```python\nawait browser.grant_permissions(\n [PermissionType.GEOLOCATION, PermissionType.NOTIFICATIONS],\n origin='https://example.com',\n browser_context_id=context_id\n)\n```\n\n**Architecture:**\n\n- Permissions are granted via the `Browser.grantPermissions` CDP command\n- Permissions are **context-specific** (isolated per context)\n- Grants override default prompt behavior\n- `reset_permissions()` reverts to default behavior\n\n### Download Management\n\nDownload behavior is configured via the `Browser.setDownloadBehavior` command:\n\n```python\nawait browser.set_download_behavior(\n behavior=DownloadBehavior.ALLOW,\n download_path='/path/to/downloads',\n events_enabled=True, # Emit download progress events\n browser_context_id=context_id\n)\n```\n\n**Options:**\n\n- `ALLOW`: Save to specified path\n- `DENY`: Cancel all downloads\n- `DEFAULT`: Show browser's default download UI\n\n### Window Management\n\nWindow operations apply to the **physical OS window** of a target:\n\n```python\nwindow_id = await browser.get_window_id_for_target(target_id)\nawait browser.set_window_bounds({\n 'left': 100, 'top': 100,\n 'width': 1920, 'height': 1080,\n 'windowState': 'normal' # or 'minimized', 'maximized', 'fullscreen'\n})\n```\n\n**Implementation details:**\n\n- Uses `Browser.getWindowForTarget` to resolve window ID from target ID\n- `Browser.setWindowBounds` modifies window geometry\n- **Headless mode**: Window operations are no-ops (no physical windows exist)\n\n## Architectural Insights and Design Tradeoffs\n\n### Singleton Tab Registry: Why?\n\nThe tab registry pattern (`_tabs_opened: dict[str, Tab]`) ensures that:\n\n1. **Event routing works correctly**: CDP events contain a `targetId` but no Tab reference. The registry maps `targetId` → `Tab` for correct callback dispatch.\n2. **State consistency**: Multiple code paths that reference the same target get the **same Tab instance**, preventing state divergence.\n3. **Memory efficiency**: Without the registry, `get_opened_tabs()` would create duplicate Tab instances for every call.\n\n**Tradeoff:** Memory usage grows with tab count, but this is unavoidable for stateful Tab instances.\n\n### Why start() Returns a Tab\n\nThis design decision sacrifices purity for **ergonomics**:\n\n- **Downside**: Initial tab cannot be avoided, even in multi-tab automation\n- **Upside**: 90% of users (single-tab scripts) don't need boilerplate:\n\n```python\n# With start() returning Tab\ntab = await browser.start()\n\n# Without (pure design)\nawait browser.start()\ntab = await browser.new_tab()\n```\n\n**Alternative explored:** Auto-close initial tab in `new_tab()`. Rejected because it's surprising behavior (implicit side effects).\n\n### Proxy Authentication: Two-Level Architecture Tradeoff\n\nPydoll's proxy authentication uses two different Fetch domain strategies:\n\n**Browser-Level (Global Proxy):**\n- **Security benefit**: Credentials never logged in CDP traces\n- **Performance cost**: Fetch pauses **all requests across all tabs** until auth completes\n- **Efficiency**: Single listener for all tabs in default context\n- **Mitigation**: Fetch is disabled after first auth, minimizing overhead\n\n**Tab-Level (Per-Context Proxy):**\n- **Security benefit**: Credentials never logged in CDP traces\n- **Performance cost**: Fetch pauses **all requests in that tab** until auth completes\n- **Efficiency**: Separate listener per tab (less efficient, but necessary for isolation)\n- **Isolation benefit**: Each context can have different proxy credentials\n- **Mitigation**: Fetch is disabled after first auth per tab\n\n**Why not use Browser.setProxyAuth?** This CDP command doesn't exist. Fetch is the only mechanism for programmatic auth.\n\n**Why tab-level for contexts?** CDP's Fetch domain cannot be scoped to a specific BrowserContext. Since each context can have a different proxy with different credentials, Pydoll must handle auth at the tab level to respect context boundaries.\n\n### Port Randomization Strategy\n\nRandom CDP ports (9223-9322) prevent collisions when running parallel browser instances:\n\n```python\nself._connection_port = connection_port or randint(9223, 9322)\n```\n\n**Why not increment from 9222?**\n\n- Race conditions in multi-process environments (e.g., pytest-xdist)\n- Collision with user's manual port selection\n\n**Tradeoff:** Random ports are harder to debug (can't hardcode). Solution: `browser._connection_port` exposes the chosen port.\n\n### Component Separation: Why Managers?\n\nThe Browser class delegates to specialized managers (ProcessManager, ProxyManager, TempDirManager, ConnectionHandler) for:\n\n1. **Testability**: Managers can be mocked independently\n2. **Reusability**: ProxyManager logic shared across Browser implementations\n3. **Maintainability**: Each manager has single responsibility\n4. **Cross-platform**: OS-specific logic isolated in ProcessManager\n\n**Tradeoff:** More indirection, but significantly better code organization at scale.\n\n## Key Takeaways\n\n1. **Browser is a coordinator**, not a monolith. It orchestrates managers and handles CDP communication.\n2. **Tab registry ensures singleton instances** per target, critical for event routing and state consistency.\n3. **Browser contexts are lightweight isolation**, sharing browser process but separating storage/cache/auth.\n4. **Proxy auth via Fetch** is a security tradeoff - hides credentials but adds latency.\n5. **Event system has two levels**: Browser-wide and tab-specific, with different WebSocket connections.\n6. **Component separation** (managers) improves testability and cross-platform support.\n\n## Related Documentation\n\nFor deeper understanding of related architectural components:\n\n- **[Connection Layer](./connection-layer.md)**: WebSocket communication, command/response flow, async patterns\n- **[Event Architecture](./event-architecture.md)**: Event dispatch, callback management, domain enabling\n- **[Tab Domain](./tab-domain.md)**: Tab-level operations, page navigation, element finding\n- **[CDP Deep Dive](./cdp.md)**: Chrome DevTools Protocol fundamentals\n- **[Proxy Architecture](./proxy-architecture.md)**: Network-level proxy concepts and implementation\n\nFor practical usage patterns:\n\n- **[Tab Management](../features/browser-management/tabs.md)**: Multi-tab automation patterns\n- **[Browser Contexts](../features/browser-management/contexts.md)**: Context isolation in practice\n- **[Proxy Configuration](../features/configuration/proxy.md)**: Setting up proxies and authentication\n" }, { "path": "docs/en/deep-dive/architecture/browser-requests-architecture.md", "content": "# Browser-Context Requests Architecture\n\nThis document explores the architectural design of Pydoll's browser-context HTTP request system, which enables making HTTP requests that seamlessly inherit the browser's session state, cookies, and authentication.\n\n!!! info \"Practical Guide Available\"\n This is the architectural deep dive. For practical examples and use cases, see [HTTP Requests Guide](../features/network/http-requests.md).\n\n## Architectural Overview\n\nBrowser-context requests solve a fundamental problem in hybrid automation: maintaining session continuity between UI interactions and API calls. Traditional approaches require manually extracting cookies and headers, creating fragile coupling between browser and HTTP client.\n\nPydoll's architecture eliminates this complexity by executing HTTP requests **inside** the browser's JavaScript context, while leveraging CDP network events to capture comprehensive metadata that JavaScript alone cannot provide.\n\n### Why This Architecture?\n\n| Traditional Approach | Pydoll Architecture |\n|---------------------|---------------------|\n| Separate HTTP client (requests, aiohttp) | Unified browser-based execution |\n| Manual cookie extraction and sync | Automatic cookie inheritance |\n| Two separate session states | Single session state |\n| Limited CORS handling | Browser-native CORS enforcement |\n| Complex authentication flows | Transparent auth preservation |\n\n\n## Component Architecture\n\nThe browser-context request system consists of two primary classes that work together with Pydoll's event system:\n\n```mermaid\nclassDiagram\n class Tab {\n +request: Request\n +enable_network_events()\n +disable_network_events()\n +get_network_response_body()\n +on(event_name, callback)\n +clear_callbacks()\n }\n \n class Request {\n -tab: Tab\n -_network_events_enabled: bool\n -_requests_sent: list\n -_requests_received: list\n +get(url, params, kwargs)\n +post(url, data, json, kwargs)\n +put(url, data, json, kwargs)\n +patch(url, data, json, kwargs)\n +delete(url, kwargs)\n +head(url, kwargs)\n +options(url, kwargs)\n -_execute_fetch_request()\n -_register_callbacks()\n -_extract_headers()\n -_extract_cookies()\n }\n \n class Response {\n -_status_code: int\n -_content: bytes\n -_text: str\n -_json: dict\n -_response_headers: list\n -_request_headers: list\n -_cookies: list\n -_url: str\n +ok: bool\n +status_code: int\n +text: str\n +content: bytes\n +url: str\n +headers: list\n +request_headers: list\n +cookies: list\n +json()\n +raise_for_status()\n }\n \n Tab *-- Request\n Request ..> Response : creates\n Request ..> Tab : uses events\n```\n\n### Request Class\n\nThe `Request` class serves as the interface layer, providing a familiar `requests`-like API while orchestrating the complex interaction between JavaScript execution and network event monitoring.\n\n**Key Responsibilities:**\n\n- Translate Python method calls to Fetch API JavaScript\n- Manage temporary network event listeners\n- Accumulate network events during request execution\n- Extract metadata from CDP events\n- Construct Response objects with complete information\n\n### Response Class\n\nThe `Response` class provides a `requests.Response`-compatible interface, making migration from traditional HTTP clients seamless.\n\n**Key Features:**\n\n- Multiple content accessors (text, bytes, JSON)\n- Lazy JSON parsing with caching\n- Comprehensive header information (both sent and received)\n- Cookie extraction from Set-Cookie headers\n- Final URL after redirects\n\n## Execution Flow\n\nThe request execution follows a six-phase pipeline:\n\n```mermaid\nflowchart TD\n Start([tab.request.get#40;url#41;]) --> Phase1[1. Preparation
Build URL + options]\n \n Phase1 --> Phase2[2. Event Registration
Enable network events
Register callbacks]\n \n Phase2 --> Phase3[3. JavaScript Execution
Runtime.evaluate(fetch)]\n \n Phase3 --> Phase4{4. Network Activity}\n Phase4 -->|Request sent| Event1[REQUEST_WILL_BE_SENT]\n Phase4 -->|Response received| Event2[RESPONSE_RECEIVED]\n Phase4 -->|Extra info| Event3[*_EXTRA_INFO events]\n \n Event1 --> Collect[Collect metadata]\n Event2 --> Collect\n Event3 --> Collect\n \n Collect --> Phase5[5. Construction
Extract headers/cookies
Build Response object]\n \n Phase5 --> Phase6[6. Cleanup
Clear callbacks
Disable events]\n \n Phase6 --> End([Return Response])\n```\n\n### Phase Details\n\n| Phase | Layer | Key Operations | Asynchronous |\n|-------|-------|----------------|--------------|\n| **1. Preparation** | Request | URL building, options formatting | No |\n| **2. Event Registration** | Tab | Enable events, register callbacks | Yes |\n| **3. JavaScript Execution** | CDP/Browser | Execute fetch() in browser context | Yes |\n| **4. Network Activity** | Browser/CDP | HTTP request, emit CDP events | Yes (parallel) |\n| **5. Construction** | Request | Parse events, build Response | No |\n| **6. Cleanup** | Tab | Remove callbacks, disable events | Yes |\n\n## Event System Integration\n\nBrowser-context requests are tightly integrated with Pydoll's event system architecture. Understanding this relationship is crucial.\n\n### Temporary Event Lifecycle\n\n```mermaid\nstateDiagram-v2\n [*] --> NoEvents: Request starts\n NoEvents --> EventsEnabled: Enable network events\n EventsEnabled --> CallbacksRegistered: Register callbacks\n CallbacksRegistered --> ExecutingRequest: Execute fetch\n ExecutingRequest --> CapturingEvents: Events fire\n CapturingEvents --> ExecutingRequest: More events\n ExecutingRequest --> CleaningUp: Fetch completes\n CleaningUp --> CallbacksRemoved: Clear callbacks\n CallbacksRemoved --> EventsDisabled: Disable if needed\n EventsDisabled --> [*]: Request complete\n```\n\n### Why Both JavaScript and Events?\n\nA common question: if JavaScript can execute the request, why use network events?\n\n| Information Source | JavaScript (Fetch API) | Network Events (CDP) |\n|-------------------|------------------------|----------------------|\n| Response status | Available | Available |\n| Response body | Available | Not available |\n| Response headers | Partial (CORS restricted) | Complete |\n| Request headers | Not accessible | Complete |\n| Set-Cookie headers | Hidden by browser | Available |\n| Timing information | Limited | Comprehensive |\n| Redirect chain | Only final URL | Full chain |\n\n**The Solution:** Combine both sources for complete information.\n\n!!! tip \"Complementary Technologies\"\n JavaScript provides the response body and triggers the request in the browser's context (with cookies, auth). Network events provide the metadata that JavaScript security policies hide.\n\n### CDP Network Event Types\n\nThe architecture uses four CDP event types to capture complete metadata:\n\n| Event | Purpose | Key Information |\n|-------|---------|----------------|\n| `REQUEST_WILL_BE_SENT` | Main outgoing request | URL, method, standard headers |\n| `REQUEST_WILL_BE_SENT_EXTRA_INFO` | Additional request metadata | Associated cookies, raw headers |\n| `RESPONSE_RECEIVED` | Main response received | Status, headers, MIME type, timing |\n| `RESPONSE_RECEIVED_EXTRA_INFO` | Additional response metadata | Set-Cookie headers, security info |\n\n!!! info \"Event Multiplicity\"\n A single HTTP request generates multiple CDP events. The Request class accumulates all related events and extracts non-duplicate information during the construction phase.\n\n## Header and Cookie Architecture\n\n### Header Extraction Strategy\n\nHeaders exist in multiple CDP events with potential duplication. The architecture uses a deduplication strategy:\n\n```mermaid\nflowchart TD\n A[Network Events] --> B{Event Type}\n B -->|REQUEST events| C[Extract Sent Headers]\n B -->|RESPONSE events| D[Extract Received Headers]\n \n C --> E[Deduplicate by name+value]\n D --> F[Deduplicate by name+value]\n \n E --> G[Request Headers List]\n F --> H[Response Headers List]\n \n G --> I[Response Object]\n H --> I\n```\n\n**Deduplication Logic:**\n\n1. Events are processed in order\n2. Each header is identified by `(name, value)` tuple\n3. Only first occurrence of each tuple is kept\n4. Result: unique, non-redundant header list\n\n### Cookie Parsing Architecture\n\nCookies require special handling because they come from `Set-Cookie` headers in `RESPONSE_RECEIVED_EXTRA_INFO` events:\n\n```mermaid\nflowchart TD\n A[RESPONSE_RECEIVED_EXTRA_INFO] --> B[Extract Set-Cookie headers]\n B --> C{Multi-line header?}\n C -->|Yes| D[Split by newline]\n C -->|No| E[Parse single cookie]\n D --> F[Parse each line]\n F --> G[Extract name=value]\n E --> G\n G --> H{Valid name?}\n H -->|Yes| I[Create CookieParam]\n H -->|No| J[Discard]\n I --> K[Add to cookie list]\n K --> L[Deduplicate]\n L --> M[Response Object]\n```\n\n**Cookie Extraction Principles:**\n\n- Only `EXTRA_INFO` events contain `Set-Cookie` headers\n- Cookie attributes (Path, Domain, Secure, HttpOnly) are ignored\n- Browser manages cookie attributes internally\n- Only name-value pairs are extracted for informational purposes\n\n!!! warning \"Cookie Scope\"\n The `Response.cookies` property contains only **new or updated** cookies from this specific response. Existing browser cookies are managed automatically and not exposed through this interface.\n\n## JavaScript Execution Context\n\nThe Fetch API execution happens in the browser's JavaScript context, which is key to the architecture's power:\n\n### Fetch API Integration\n\nThe request is translated to JavaScript:\n\n```javascript\n// Simplified representation\n(async () => {\n const response = await fetch(url, {\n method: 'GET',\n headers: {'X-Custom': 'value'},\n // Browser automatically adds:\n // - Cookie header\n // - Authorization if set\n // - Standard headers (User-Agent, Accept, etc.)\n });\n \n return {\n status: response.status,\n url: response.url, // Final URL after redirects\n text: await response.text(),\n content: new Uint8Array(await response.arrayBuffer()),\n json: response.headers.get('Content-Type')?.includes('application/json')\n ? await response.clone().json()\n : null\n };\n})()\n```\n\n### Browser Context Benefits\n\nExecuting in the browser context provides:\n\n| Benefit | Description |\n|---------|-------------|\n| **Automatic Cookie Inclusion** | Browser sends all applicable cookies automatically |\n| **Auth State Preservation** | Authentication headers maintained from browser session |\n| **CORS Enforcement** | Browser applies same CORS policies as user interactions |\n| **TLS/SSL Handling** | Browser's certificate validation and security policies apply |\n| **Compression** | Automatic handling of gzip, br, deflate |\n| **Redirects** | Browser follows redirects transparently |\n| **Same Security Context** | Request appears identical to user-initiated requests |\n\n!!! info \"Anti-Bot Detection\"\n Requests executed in the browser context are indistinguishable from user-initiated requests, making them effective against anti-bot systems that analyze request patterns.\n\n## Performance Considerations\n\n### Event Overhead\n\nNetwork events add overhead to request execution:\n\n| Scenario | Overhead | Recommendation |\n|----------|----------|----------------|\n| Single request | Low | Acceptable |\n| Multiple sequential requests | Moderate | Enable events once |\n| Bulk requests (100+) | High | Consider enabling events at tab level |\n| Long-running automation | Memory concern | Disable when done |\n\n### Optimization Pattern\n\n```python\n# Inefficient - events enabled/disabled repeatedly\nfor url in urls:\n response = await tab.request.get(url)\n\n# Efficient - events enabled once\nawait tab.enable_network_events()\nfor url in urls:\n response = await tab.request.get(url)\nawait tab.disable_network_events()\n```\n\n!!! tip \"Automatic Optimization\"\n The Request class checks if network events are already enabled and skips redundant enable/disable operations automatically.\n\n### JSON Parsing Strategy\n\nResponse JSON parsing uses lazy evaluation with caching:\n\n1. First call to `response.json()`: Parse and cache\n2. Subsequent calls: Return cached result\n3. If JSON pre-parsed during construction: Use that\n\nThis prevents redundant parsing overhead.\n\n## Security Architecture\n\n### CORS Policy Enforcement\n\nBrowser-context requests respect CORS policies:\n\n```mermaid\nflowchart TD\n A[tab.request.get(url)] --> B{Same Origin?}\n B -->|Yes| C[Request Allowed]\n B -->|No| D{CORS Headers Present?}\n D -->|Yes| E[Request Allowed]\n D -->|No| F[Request Blocked]\n \n C --> G[Response Returned]\n E --> G\n F --> H[CORS Error]\n```\n\n**CORS Behavior:**\n\n- Requests to same origin: Always allowed\n- Cross-origin requests: Require CORS headers from server\n- Opaque responses: May be blocked by browser\n\n**Workaround for CORS Issues:**\n\nNavigate to the domain first to establish same-origin context:\n\n```python\nawait tab.go_to('https://different-domain.com')\nresponse = await tab.request.get('https://different-domain.com/api')\n```\n\n### Cookie Security\n\nCookies with security flags (`HttpOnly`, `Secure`, `SameSite`) are handled by the browser:\n\n- **HttpOnly cookies**: Sent automatically but not exposed to JavaScript or CDP\n- **Secure cookies**: Only sent over HTTPS\n- **SameSite cookies**: Browser enforces SameSite policies\n\nThe `Response.cookies` property may not show all cookies due to these security restrictions.\n\n### TLS/SSL Validation\n\nThe browser validates SSL certificates. Self-signed or invalid certificates cause requests to fail unless:\n\n```python\noptions = ChromiumOptions()\noptions.add_argument('--ignore-certificate-errors')\nbrowser = Chrome(options=options)\n```\n\n!!! warning \"Security Trade-off\"\n Disabling certificate validation reduces security. Only use in controlled environments.\n\n## Limitations and Design Decisions\n\n### Request Body Size\n\nVery large request bodies (files, large datasets) have JavaScript memory constraints. For file uploads, use `WebElement.set_input_files()` or the file chooser interceptor instead.\n\n### Binary Response Handling\n\nBinary responses are converted through JavaScript's `ArrayBuffer` and `Uint8Array`, which adds some overhead for very large responses (>100MB).\n\n### Redirect Transparency\n\nThe Fetch API follows redirects automatically. Only the final URL is captured. If you need the redirect chain, use network monitoring separately.\n\n### Event Timing\n\nEvents must be registered **before** executing the fetch. The architecture ensures this through the registration phase, but manual event handling requires careful timing.\n\n## Architectural Principles\n\nThe browser-context request architecture adheres to these principles:\n\n1. **Session Continuity**: Never break the browser's session state\n2. **Zero Manual Sync**: No cookie/header extraction required\n3. **Complete Information**: Combine JavaScript + events for full metadata\n4. **Automatic Cleanup**: Resources freed after each request\n5. **Familiar Interface**: `requests`-compatible API for easy adoption\n6. **Performance Conscious**: Optimize for common use cases\n7. **Security Aware**: Respect browser security policies\n\n## Integration with Other Systems\n\n### Event System Dependency\n\nBrowser-context requests depend on the event system architecture:\n\n- Leverages `Tab.on()` for callback registration\n- Uses `Tab.clear_callbacks()` for cleanup\n- Respects existing network event enablement\n- Integrates with event lifecycle management\n\nSee [Event System Architecture](event-architecture.md) for details.\n\n### Type System Integration\n\nThe architecture uses Python's type system extensively:\n\n- `HeaderEntry` TypedDict for headers\n- `CookieParam` TypedDict for cookies\n- Event type definitions from `pydoll.protocol.network.events`\n- Provides IDE autocomplete and type safety\n\nSee [Typing System](typing-system.md) for details.\n\n## Further Reading\n\n- **[HTTP Requests Guide](../features/network/http-requests.md)** - Practical examples and use cases\n- **[Event System Architecture](event-architecture.md)** - Event system internal design\n- **[Network Monitoring](../features/network/monitoring.md)** - Passive network observation\n- **[Request Interception](../features/network/interception.md)** - Active request modification\n- **[Typing System](typing-system.md)** - Type system integration\n\n## Summary\n\nPydoll's browser-context request architecture achieves seamless HTTP communication by combining JavaScript Fetch API execution with CDP network event monitoring. This hybrid approach provides:\n\n- **Complete metadata** from both JavaScript and CDP events\n- **Automatic session continuity** through browser context execution \n- **Familiar interface** compatible with the requests library\n- **Performance optimization** through event reuse\n- **Security compliance** with browser policies\n\nThe architecture demonstrates how combining complementary technologies (JavaScript + CDP events) can solve complex problems elegantly, providing power and convenience without compromising on completeness or security.\n\n" }, { "path": "docs/en/deep-dive/architecture/event-architecture.md", "content": "# Event System Architecture\n\nThis document explores the internal architecture of Pydoll's event system, covering WebSocket communication, event flow, callback management, and performance considerations.\n\n!!! info \"Practical Usage Guide\"\n For practical examples and usage patterns, see the [Event System Guide](../features/advanced/event-system.md).\n\n## WebSocket Communication and CDP\n\nAt the core of Pydoll's event system is the Chrome DevTools Protocol (CDP), which provides a structured way to interact with and monitor browser activities over WebSocket connections. This bidirectional communication channel allows your code to both send commands to the browser and receive events back.\n\n```mermaid\nsequenceDiagram\n participant Client as Pydoll Code\n participant Connection as ConnectionHandler\n participant WebSocket\n participant Browser\n \n Client->>Connection: Register callback for event\n Connection->>Connection: Store callback in registry\n \n Client->>Connection: Enable event domain\n Connection->>WebSocket: Send CDP command to enable domain\n WebSocket->>Browser: Forward command\n Browser-->>WebSocket: Acknowledge domain enabled\n WebSocket-->>Connection: Forward response\n Connection-->>Client: Domain enabled\n \n Browser->>WebSocket: Event occurs, sends CDP event message\n WebSocket->>Connection: Forward event message\n Connection->>Connection: Look up callbacks for this event\n Connection->>Client: Execute registered callback\n```\n\n### WebSocket Communication Model\n\nThe WebSocket connection between Pydoll and the browser follows this pattern:\n\n1. **Connection Establishment**: When the browser starts, a WebSocket server is created, and Pydoll establishes a connection to it\n2. **Bidirectional Messaging**: Both Pydoll and the browser can send messages at any time\n3. **Message Types**:\n - **Commands**: Sent from Pydoll to the browser (e.g., navigation, DOM manipulation)\n - **Command Responses**: Sent from the browser to Pydoll in response to commands\n - **Events**: Sent from the browser to Pydoll when something happens (e.g., page load, network activity)\n\n### Chrome DevTools Protocol Structure\n\nCDP organizes its functionality into domains, each responsible for a specific area of browser functionality:\n\n| Domain | Responsibility | Typical Events |\n|--------|----------------|----------------|\n| Page | Page lifecycle | Load events, navigation, dialogs |\n| Network | Network activity | Request/response monitoring, WebSockets |\n| DOM | Document structure | DOM changes, attribute modifications |\n| Fetch | Request interception | Request paused, authentication required |\n| Runtime | JavaScript execution | Console messages, exceptions |\n| Browser | Browser management | Window creation, tabs, contexts |\n\nEach domain must be explicitly enabled before it will emit events, which helps manage performance by only processing events that are actually needed.\n\n## Domain Architecture\n\n### The Enable/Disable Pattern\n\nThe explicit enable/disable pattern serves several important architectural purposes:\n\n1. **Performance Optimization**: By only enabling domains you're interested in, you reduce the overhead of event processing\n2. **Resource Management**: Some event domains (like Network or DOM monitoring) can generate large volumes of events that consume memory\n3. **Protocol Compliance**: CDP requires explicit domain enabling before events are emitted\n4. **Controlled Cleanup**: Explicitly disabling domains ensures proper cleanup when events are no longer needed\n\n```mermaid\nstateDiagram-v2\n [*] --> Disabled: Initial State\n Disabled --> Enabled: enable_xxx_events()\n Enabled --> Disabled: disable_xxx_events()\n Enabled --> [*]: Tab Closed\n Disabled --> [*]: Tab Closed\n```\n\n!!! warning \"Event Leak Prevention\"\n Failing to disable event domains when they're no longer needed can lead to memory leaks and performance degradation, especially in long-running automation. Always disable event domains when you're done with them, particularly for high-volume events like network monitoring.\n\n### Domain-Specific Enabling Methods\n\nDifferent domains are enabled through specific methods on the appropriate objects:\n\n| Domain | Enable Method | Disable Method | Available On |\n|--------|--------------|----------------|--------------|\n| Page | `enable_page_events()` | `disable_page_events()` | Tab |\n| Network | `enable_network_events()` | `disable_network_events()` | Tab |\n| DOM | `enable_dom_events()` | `disable_dom_events()` | Tab |\n| Fetch | `enable_fetch_events()` | `disable_fetch_events()` | Tab, Browser |\n| File Chooser | `enable_intercept_file_chooser_dialog()` | `disable_intercept_file_chooser_dialog()` | Tab |\n\n!!! info \"Domain Ownership\"\n Events belong to specific domains based on their functionality. Some domains are only available at certain levels - for instance, Page events are available on the Tab instance but not directly at the Browser level.\n\n## Event Registration System\n\n### The `on()` Method\n\nThe central method for subscribing to events is the `on()` method, available on both Tab and Browser instances:\n\n```python\nasync def on(\n self, event_name: str, callback: callable, temporary: bool = False\n) -> int:\n \"\"\"\n Registers an event listener.\n\n Args:\n event_name (str): The event name to listen for.\n callback (callable): The callback function to execute when the\n event is triggered.\n temporary (bool): If True, the callback will be removed after it's\n triggered once. Defaults to False.\n\n Returns:\n int: The ID of the registered callback.\n \"\"\"\n```\n\nThis method returns a callback ID that can be used to remove the callback later if needed.\n\n### Callback Registry\n\nInternally, the `ConnectionHandler` maintains a callback registry:\n\n```python\n{\n 'Page.loadEventFired': [\n (callback_id_1, callback_function_1, temporary=False),\n (callback_id_2, callback_function_2, temporary=True),\n ],\n 'Network.requestWillBeSent': [\n (callback_id_3, callback_function_3, temporary=False),\n ]\n}\n```\n\nWhen an event arrives via WebSocket:\n\n1. The event name is extracted from the message\n2. The registry is queried for matching callbacks\n3. Each callback is executed with the event data\n4. Temporary callbacks are removed after execution\n\n### Async Callback Handling\n\nCallbacks can be either synchronous or asynchronous. The event system handles both:\n\n```python\nasync def _trigger_callbacks(self, event_name: str, event_data: dict):\n for cb_id, cb_data in self._event_callbacks.items():\n if cb_data['event'] == event_name:\n if asyncio.iscoroutinefunction(cb_data['callback']):\n await cb_data['callback'](event_data)\n else:\n cb_data['callback'](event_data)\n```\n\nAsynchronous callbacks are awaited sequentially. This means each callback completes before the next one executes, which is important for:\n\n- **Predictable Execution Order**: Callbacks execute in registration order\n- **Error Handling**: Exceptions in one callback don't prevent others from executing\n- **State Consistency**: Callbacks can rely on sequential state changes\n\n!!! info \"Sequential vs Concurrent Execution\"\n Callbacks execute sequentially within the same event. However, different events can be processed concurrently since the event loop handles multiple connections simultaneously.\n\n## Event Flow and Lifecycle\n\nThe event lifecycle follows these steps:\n\n```mermaid\nflowchart TD\n A[Browser Activity] -->|Generates| B[CDP Event]\n B -->|Sent via WebSocket| C[ConnectionHandler]\n C -->|Filters by Event Name| D{Registered Callbacks?}\n D -->|Yes| E[Process Event]\n D -->|No| F[Discard Event]\n E -->|For Each Callback| G[Execute Callback]\n G -->|If Temporary| H[Remove Callback]\n G -->|If Permanent| I[Retain for Future Events]\n```\n\n### Detailed Flow\n\n1. **Browser Activity**: Something happens in the browser (page loads, request sent, DOM changes)\n2. **CDP Event Generation**: Browser generates a CDP event message\n3. **WebSocket Transmission**: Message is sent over WebSocket to Pydoll\n4. **Event Reception**: The ConnectionHandler receives the event\n5. **Callback Lookup**: ConnectionHandler checks its registry for callbacks matching the event name\n6. **Callback Execution**: If callbacks exist, each is executed with the event data\n7. **Temporary Removal**: If a callback was registered as temporary, it's removed after execution\n\n## Browser-Level vs. Tab-Level Events\n\nPydoll's event system operates at both the browser and tab levels, with important distinctions:\n\n```mermaid\ngraph TD\n Browser[Browser Instance] -->|\"Global Events (e.g., Target events)\"| BrowserCallbacks[Browser-Level Callbacks]\n Browser -->|\"Creates\"| Tab1[Tab Instance 1]\n Browser -->|\"Creates\"| Tab2[Tab Instance 2]\n Tab1 -->|\"Tab-Specific Events\"| Tab1Callbacks[Tab 1 Callbacks]\n Tab2 -->|\"Tab-Specific Events\"| Tab2Callbacks[Tab 2 Callbacks]\n```\n\n### Browser-Level Events\n\nBrowser-level events operate globally across all tabs. These are limited to specific domains like:\n\n- **Target Events**: Tab creation, destruction, crash\n- **Browser Events**: Window management, download coordination\n\n```python\n# Browser-level event registration\nawait browser.on('Target.targetCreated', handle_new_target)\n```\n\nBrowser-level event domains are limited, and trying to use tab-specific events will raise an exception.\n\n### Tab-Level Events\n\nTab-level events are specific to an individual tab:\n\n```python\n# Each tab has its own event context\ntab1 = await browser.start()\ntab2 = await browser.new_tab()\n\nawait tab1.enable_page_events()\nawait tab1.on(PageEvent.LOAD_EVENT_FIRED, handle_tab1_load)\n\nawait tab2.enable_page_events()\nawait tab2.on(PageEvent.LOAD_EVENT_FIRED, handle_tab2_load)\n```\n\nThis architecture allows for:\n\n- **Isolated Event Handling**: Events in one tab don't affect others\n- **Per-Tab Configuration**: Different tabs can monitor different event types\n- **Resource Efficiency**: Only enable events on tabs that need them\n\n!!! info \"Domain-Specific Scope\"\n Not all event domains are available at both levels:\n \n - **Fetch Events**: Available at both browser and tab levels\n - **Page Events**: Available only at the tab level\n - **Target Events**: Available only at the browser level\n\n## Performance Architecture\n\n### Event System Overhead\n\nThe event system adds overhead to browser automation, especially for high-frequency events:\n\n| Event Domain | Typical Event Volume | Performance Impact |\n|--------------|---------------------|-------------------|\n| Page | Low | Minimal |\n| Network | High | Moderate to High |\n| DOM | Very High | High |\n| Fetch | Moderate | Moderate (higher if intercepting) |\n\n### Performance Optimization Strategies\n\n1. **Selective Domain Enabling**: Only enable event domains you're actively using\n2. **Strategic Scoping**: Use browser-level events only for truly browser-wide concerns\n3. **Timely Disabling**: Always disable event domains when you're finished with them\n4. **Early Filtering**: In callbacks, filter out irrelevant events as early as possible\n5. **Temporary Callbacks**: Use the `temporary=True` flag for one-time events\n\n### Memory Management\n\nThe event system manages memory through several mechanisms:\n\n1. **Callback Registry Cleanup**: Removing callbacks frees their references\n2. **Temporary Auto-Removal**: Temporary callbacks are automatically cleaned up\n3. **Domain Disabling**: Disabling a domain stops event generation\n4. **Tab Closure**: When a tab closes, all its callbacks are automatically removed\n\n!!! warning \"Memory Leak Prevention\"\n In long-running automation, always clean up callbacks and disable domains when done. High-frequency events (especially DOM) can accumulate significant memory if left enabled.\n\n## Connection Handler Architecture\n\nThe `ConnectionHandler` is the central component managing WebSocket communication and event dispatching.\n\n### Key Responsibilities\n\n1. **WebSocket Management**: Establishing and maintaining the WebSocket connection\n2. **Message Routing**: Distinguishing between command responses and events\n3. **Callback Registry**: Maintaining the mapping of event names to callbacks\n4. **Event Dispatching**: Executing registered callbacks when events arrive\n5. **Cleanup**: Removing callbacks and closing connections\n\n### Internal Structure\n\n```python\nclass ConnectionHandler:\n def __init__(self, ...):\n self._events_handler = EventsManager()\n self._websocket = None\n # ... other attributes\n \n async def register_callback(self, event_name, callback, temporary):\n return self._events_handler.register_callback(event_name, callback, temporary)\n\nclass EventsManager:\n def __init__(self):\n self._event_callbacks = {} # Callback ID -> callback data\n self._callback_id = 0\n \n def register_callback(self, event_name, callback, temporary):\n self._callback_id += 1\n self._event_callbacks[self._callback_id] = {\n 'event': event_name,\n 'callback': callback,\n 'temporary': temporary\n }\n return self._callback_id\n \n async def _trigger_callbacks(self, event_name, event_data):\n callbacks_to_remove = []\n \n for cb_id, cb_data in self._event_callbacks.items():\n if cb_data['event'] == event_name:\n # Execute callback (await if async, call directly if sync)\n if asyncio.iscoroutinefunction(cb_data['callback']):\n await cb_data['callback'](event_data)\n else:\n cb_data['callback'](event_data)\n \n # Mark temporary callbacks for removal\n if cb_data['temporary']:\n callbacks_to_remove.append(cb_id)\n \n # Remove temporary callbacks after all callbacks executed\n for cb_id in callbacks_to_remove:\n self.remove_callback(cb_id)\n```\n\nThis architecture ensures:\n\n- **Efficient Lookup**: Event names map directly to callback lists\n- **Minimal Overhead**: Only registered events are processed\n- **Automatic Cleanup**: Temporary callbacks are removed after execution\n- **Thread Safety**: Operations are async-safe\n\n## Event Message Format\n\nCDP events follow a standardized message format:\n\n```json\n{\n \"method\": \"Network.requestWillBeSent\",\n \"params\": {\n \"requestId\": \"1234.56\",\n \"loaderId\": \"7890.12\",\n \"documentURL\": \"https://example.com\",\n \"request\": {\n \"url\": \"https://api.example.com/data\",\n \"method\": \"GET\",\n \"headers\": {...}\n },\n \"timestamp\": 123456.789,\n \"wallTime\": 1234567890.123,\n \"initiator\": {...},\n \"type\": \"XHR\"\n }\n}\n```\n\nKey components:\n\n- **`method`**: The event name in `Domain.eventName` format\n- **`params`**: Event-specific data, varies by event type\n- **No `id` field**: Unlike commands, events don't have request IDs\n\nThe event system extracts the `method` field to route to the appropriate callbacks, passing the entire message to each callback.\n\n## Multi-Tab Event Coordination\n\nPydoll's architecture supports sophisticated multi-tab event coordination:\n\n### Independent Tab Contexts\n\nEach tab maintains its own:\n\n- Event domain enablement state\n- Callback registry\n- Event communication channel\n- Network logs (if network events enabled)\n\n!!! info \"Communication Architecture\"\n Each tab has its own event communication channel to the browser. For technical details on how WebSocket connections and target IDs work at the protocol level, see [Browser Domain Architecture](./browser-domain.md).\n\n### Shared Browser Context\n\nMultiple tabs can share:\n\n- Browser-level event listeners\n- Cookie storage\n- Cache\n- Browser process\n\nThis architecture allows for:\n\n1. **Parallel Event Processing**: Multiple tabs can process events simultaneously\n2. **Isolated Failures**: Issues in one tab don't affect others\n3. **Resource Sharing**: Common browser features are shared efficiently\n4. **Coordinated Actions**: Browser-level events can coordinate cross-tab activities\n\n## Conclusion\n\nPydoll's event system architecture is designed for:\n\n- **Performance**: Minimal overhead through selective domain enabling and efficient callback dispatch\n- **Flexibility**: Support for both browser-level and tab-level events\n- **Scalability**: Handle multiple tabs with independent event contexts\n- **Reliability**: Automatic cleanup and memory management\n\nUnderstanding this architecture helps you:\n\n- **Optimize Performance**: Know which domains have high overhead\n- **Debug Issues**: Understand the event flow when things don't work as expected\n- **Design Better Automation**: Leverage the architecture for efficient event-driven workflows\n- **Avoid Pitfalls**: Prevent memory leaks and performance degradation\n\nFor practical usage patterns and examples, see the [Event System Guide](../features/advanced/event-system.md).\n\n" }, { "path": "docs/en/deep-dive/architecture/find-elements-mixin.md", "content": "# FindElements Mixin Architecture\n\nThe FindElementsMixin represents a critical architectural decision in Pydoll: using **composition over inheritance** to share element-finding capabilities between `Tab` and `WebElement` without coupling them through a common base class. This document explores the mixin pattern, its implementation, and the internal mechanics of element location.\n\n!!! info \"Practical Usage Guide\"\n For practical examples and usage patterns, see the [Element Finding Guide](../features/automation/element-finding.md) and [Selectors Guide](./selectors-guide.md).\n\n## Mixin Pattern: Design Philosophy\n\n### What is a Mixin?\n\nA mixin is a class designed to **provide methods to other classes** without being a base class in a traditional inheritance hierarchy. Unlike standard inheritance (which models \"is-a\" relationships), mixins model **\"can-do\" capabilities**.\n\n```python\n# Traditional inheritance: \"is-a\"\nclass Animal:\n def breathe(self): ...\n\nclass Dog(Animal): # Dog IS-A Animal\n def bark(self): ...\n\n# Mixin pattern: \"can-do\"\nclass FlyableMixin:\n def fly(self): ...\n\nclass Bird(Animal, FlyableMixin): # Bird IS-A Animal, CAN fly\n pass\n```\n\n### Why Mixins Over Inheritance?\n\nPydoll faces a specific architectural challenge:\n\n- **`Tab`** needs to find elements in the **document context**\n- **`WebElement`** needs to find elements **relative to itself** (child elements)\n- Both need **identical selector logic** (CSS, XPath, attribute building)\n\n**Option 1: Shared Base Class**\n\n```python\nclass ElementLocator:\n def find(...): ...\n\nclass Tab(ElementLocator):\n pass\n\nclass WebElement(ElementLocator):\n pass\n```\n\n**Problems:**\n- Tight coupling: `Tab` and `WebElement` now share inheritance hierarchy\n- Violates Single Responsibility: `Tab` shouldn't inherit from same class as `WebElement`\n- Hard to extend: Adding new capabilities requires modifying base class\n\n**Option 2: Mixin Pattern (Chosen Approach)**\n\n```python\nclass FindElementsMixin:\n def find(...): ...\n def query(...): ...\n\nclass Tab(FindElementsMixin):\n # Tab-specific logic\n pass\n\nclass WebElement(FindElementsMixin):\n # WebElement-specific logic\n pass\n```\n\n**Benefits:**\n\n- **Decoupling**: `Tab` and `WebElement` remain independent\n- **Reusability**: Same element-finding logic in both classes\n- **Composability**: Can add other mixins without conflicts\n- **Testability**: Mixin can be tested in isolation\n\n!!! tip \"Mixin Characteristics\"\n 1. **Stateless**: Mixins don't maintain their own state (no `__init__`)\n 2. **Dependency Injection**: Assumes consuming class provides dependencies (e.g., `_connection_handler`)\n 3. **Single Purpose**: Each mixin provides one cohesive capability\n 4. **Not Instantiable**: Never create `FindElementsMixin()` directly\n\n## Mixin Implementation in Pydoll\n\n### Class Structure\n\nThe FindElementsMixin uses **dependency injection** to work with any class that provides a `_connection_handler`:\n\n```python\nclass FindElementsMixin:\n \"\"\"\n Mixin providing element finding capabilities.\n \n Assumes the consuming class has:\n - _connection_handler: ConnectionHandler instance for CDP commands\n - _object_id: Optional[str] for context-relative searches (WebElement only)\n \"\"\"\n \n if TYPE_CHECKING:\n _connection_handler: ConnectionHandler # Type hint, not actual attribute\n \n async def find(self, ...):\n # Implementation uses self._connection_handler\n # Checks for self._object_id to determine context\n```\n\n**Key insight:** The mixin doesn't define `_connection_handler` or `_object_id`. It **assumes** they exist via duck typing.\n\n### How Tab and WebElement Use the Mixin\n\n```python\n# Tab: Document-level searches\nclass Tab(FindElementsMixin):\n def __init__(self, browser, target_id, connection_port):\n self._connection_handler = ConnectionHandler(connection_port)\n # No _object_id → searches from document root\n\n# WebElement: Element-relative searches\nclass WebElement(FindElementsMixin):\n def __init__(self, object_id, connection_handler, ...):\n self._object_id = object_id # CDP object ID\n self._connection_handler = connection_handler\n # Has _object_id → searches relative to this element\n```\n\n**Critical distinction:**\n\n- **Tab**: `hasattr(self, '_object_id')` → `False` → uses `RuntimeCommands.evaluate()` (document context)\n- **WebElement**: `hasattr(self, '_object_id')` → `True` → uses `RuntimeCommands.call_function_on()` (element context)\n\n### Context Detection\n\nThe mixin dynamically detects search context:\n\n```python\nasync def _find_element(self, by, value, raise_exc=True):\n if hasattr(self, '_object_id'):\n # Relative search: call JavaScript function on THIS element\n command = self._get_find_element_command(by, value, self._object_id)\n else:\n # Document search: evaluate JavaScript in global context\n command = self._get_find_element_command(by, value)\n \n response = await self._execute_command(command)\n # ...\n```\n\nThis single implementation handles both:\n\n- `tab.find(id='submit')` → searches entire document\n- `form_element.find(id='submit')` → searches within `form_element`\n\n!!! warning \"Mixin Dependency Coupling\"\n The mixin is **tightly coupled** to CDP's object model. It assumes:\n \n - Elements are represented by `objectId` strings\n - `Runtime.evaluate()` for document searches\n - `Runtime.callFunctionOn()` for element-relative searches\n \n This is acceptable because Pydoll is **CDP-specific**. A more generic design would require abstraction layers.\n\n## Public API Design\n\nThe mixin exposes two high-level methods with distinct design philosophies:\n\n### find(): Attribute-Based Selection\n\n```python\n@overload\nasync def find(self, find_all: Literal[False], ...) -> WebElement: ...\n\n@overload\nasync def find(self, find_all: Literal[True], ...) -> list[WebElement]: ...\n\nasync def find(\n self,\n id: Optional[str] = None,\n class_name: Optional[str] = None,\n name: Optional[str] = None,\n tag_name: Optional[str] = None,\n text: Optional[str] = None,\n timeout: int = 0,\n find_all: bool = False,\n raise_exc: bool = True,\n **attributes,\n) -> Union[WebElement, list[WebElement], None]:\n```\n\n**Design decisions:**\n\n1. **Kwargs over positional By enum**:\n ```python\n # Pydoll (intuitive)\n await tab.find(id='submit', class_name='primary')\n \n # Selenium (verbose)\n driver.find_element(By.ID, 'submit') # Can't combine attributes easily\n ```\n\n2. **Auto-resolution to optimal selector**:\n - Single attribute → uses `By.ID`, `By.CLASS_NAME`, etc. (fastest)\n - Multiple attributes → builds XPath (flexible but slower)\n\n3. **`**attributes` for extensibility**:\n ```python\n await tab.find(data_testid='submit-btn', aria_label='Submit form')\n # Builds: //\\*[@data-testid='submit-btn' and @aria-label='Submit form']\n ```\n\n### query(): Expression-Based Selection\n\n```python\n@overload\nasync def query(self, expression, find_all: Literal[False], ...) -> WebElement: ...\n\n@overload\nasync def query(self, expression, find_all: Literal[True], ...) -> list[WebElement]: ...\n\nasync def query(\n self, \n expression: str, \n timeout: int = 0, \n find_all: bool = False, \n raise_exc: bool = True\n) -> Union[WebElement, list[WebElement], None]:\n```\n\n**Design decisions:**\n\n1. **Auto-detect CSS vs XPath**:\n ```python\n # XPath detection (starts with / or ./)\n await tab.query(\"//div[@id='content']\")\n \n # CSS detection (default)\n await tab.query(\"div#content > p.intro\")\n ```\n\n2. **Single expression parameter** (unlike `find()`):\n - Assumes user knows selector syntax\n - No abstraction overhead\n\n3. **Direct passthrough to browser**:\n - `querySelector()` / `querySelectorAll()` for CSS\n - `document.evaluate()` for XPath\n\n### Overload Pattern for Type Safety\n\nBoth methods use `@overload` to provide **precise return types**:\n\n```python\n# IDE knows return type is WebElement\nelement = await tab.find(id='submit')\n\n# IDE knows return type is list[WebElement]\nelements = await tab.find(class_name='item', find_all=True)\n\n# IDE knows return type is Optional[WebElement]\nmaybe_element = await tab.find(id='optional', raise_exc=False)\n```\n\nThis is critical for IDE autocomplete and type checking. See [Type System Deep Dive](./typing-system.md) for details.\n\n## Selector Resolution Architecture\n\nThe mixin converts user input into CDP commands through a resolution pipeline:\n\n| Stage | Input | Output | Key Decision |\n|-------|-------|--------|-------------|\n| **1. Method Selection** | `find()` kwargs or `query()` expression | Selector strategy | Attribute-based vs expression-based |\n| **2. Strategy Resolution** | Attributes or expression | `By` enum + value | Single attr → native method, Multiple → XPath |\n| **3. Context Detection** | `By` + value + `hasattr(_object_id)` | CDP command type | Document vs element-relative search |\n| **4. Command Generation** | CDP command type + selector | JavaScript + CDP method | `evaluate()` vs `callFunctionOn()` |\n| **5. Execution** | CDP command | `objectId` or array of `objectId`s | Via ConnectionHandler |\n| **6. WebElement Creation** | `objectId` + attributes | `WebElement` instance(s) | Factory function to avoid circular imports |\n\n### Key Architectural Decisions\n\n**1. Single vs Multiple Attributes**\n\n```python\n# Single attribute → Direct selector (fast)\nawait tab.find(id='username') # Uses By.ID → getElementById()\n\n# Multiple attributes → XPath (flexible)\nawait tab.find(tag_name='input', type='password', name='pwd')\n# → //input[@type='password' and @name='pwd']\n```\n\n**Why this matters:**\n- Native methods (`getElementById`, `getElementsByClassName`) are 10-50% faster than XPath\n- XPath overhead is acceptable when combining attributes (no alternative)\n\n**2. Auto-Detection of Selector Type**\n\n```python\nawait tab.query(\"//div\") # Starts with / → XPath\nawait tab.query(\"#login\") # Default → CSS\n```\n\n**Implementation:**\n```python\nif expression.startswith(('./', '/', '(/')):\n return By.XPATH\nreturn By.CSS_SELECTOR\n```\n\nHeuristic is **unambiguous** - CSS selectors cannot start with `/`.\n\n**3. XPath Relative Path Adjustment**\n\nFor element-relative searches, absolute XPath must be converted:\n\n```python\n# User provides: //div\n# For WebElement: .//div (relative to element, not document)\n\ndef _ensure_relative_xpath(xpath):\n return f'.{xpath}' if not xpath.startswith('.') else xpath\n```\n\nWithout this, `element.find()` would search from document root.\n\n## CDP Command Generation\n\nThe mixin routes to different CDP methods based on search context:\n\n| Context | Selector Type | CDP Method | JavaScript Equivalent |\n|---------|--------------|------------|---------------------|\n| Document | CSS | `Runtime.evaluate` | `document.querySelector()` |\n| Document | XPath | `Runtime.evaluate` | `document.evaluate()` |\n| Element | CSS | `Runtime.callFunctionOn` | `this.querySelector()` |\n| Element | XPath | `Runtime.callFunctionOn` | `document.evaluate(..., this)` |\n\n**Key insight:** `Runtime.callFunctionOn` requires an `objectId` (the element to call on), while `Runtime.evaluate` executes in global scope.\n\n### JavaScript Templates\n\nPydoll uses pre-defined templates for consistency and performance:\n\n```python\n# CSS selectors\nScripts.QUERY_SELECTOR = 'document.querySelector(\"{selector}\")'\nScripts.RELATIVE_QUERY_SELECTOR = 'this.querySelector(\"{selector}\")'\n\n# XPath expressions\nScripts.FIND_XPATH_ELEMENT = '''\n document.evaluate(\"{escaped_value}\", document, null,\n XPathResult.FIRST_ORDERED_NODE_TYPE, null).singleNodeValue\n'''\n```\n\nTemplates avoid runtime string concatenation and centralize JavaScript code.\n\n## Object ID Resolution and WebElement Creation\n\nCDP represents DOM nodes as **`objectId` strings**. The mixin abstracts this:\n\n**Single element flow:**\n1. Execute CDP command → Extract `objectId` from response\n2. Call `DOM.describeNode(objectId)` → Get attributes, tag name\n3. Create `WebElement(objectId, connection_handler, attributes)`\n\n**Multiple elements flow:**\n1. Execute CDP command → Returns **array as single remote object**\n2. Call `Runtime.getProperties(array_objectId)` → Enumerate array indices\n3. Extract individual `objectId` for each element\n4. Describe and create `WebElement` for each\n\n**Why `Runtime.getProperties`?** CDP doesn't return arrays directly - it returns a **reference to an array object**. We must enumerate its properties to extract individual elements.\n\n## Architectural Insights and Design Tradeoffs\n\n### Why Kwargs Instead of By Enum?\n\n**Pydoll's choice:**\n```python\nawait tab.find(id='submit', class_name='primary')\n```\n\n**Selenium's approach:**\n```python\ndriver.find_element(By.ID, 'submit') # Can't combine attributes\n```\n\n**Rationale:**\n\n- **Discoverability**: IDE autocomplete shows all available parameters\n- **Composability**: Can combine multiple attributes in one call\n- **Readability**: `id='submit'` is more intuitive than `(By.ID, 'submit')`\n\n**Tradeoff:** Kwargs are less explicit about selector strategy. Solved by documentation and logging.\n\n### Why Auto-Detect CSS vs XPath?\n\nThe `_get_expression_type()` heuristic eliminates user burden:\n\n```python\nawait tab.query(\"//div\") # Auto: XPath\nawait tab.query(\"#login\") # Auto: CSS\nawait tab.query(\"div > p\") # Auto: CSS\n```\n\n**Benefits:**\n\n- **Ergonomics**: Users don't need to specify selector type\n- **Correctness**: Impossible to misuse (XPath with CSS method, vice versa)\n\n**Limitation:** No way to force CSS interpretation of ambiguous selectors (rare edge case).\n\n### Circular Import Prevention: create_web_element()\n\nThe mixin uses a **factory function** to avoid circular imports:\n\n```python\ndef create_web_element(*args, **kwargs):\n \"\"\"Dynamically import WebElement at runtime.\"\"\"\n from pydoll.elements.web_element import WebElement # Late import\n return WebElement(*args, **kwargs)\n```\n\n**Why needed?**\n\n- `FindElementsMixin` → needs to create `WebElement`\n- `WebElement` → inherits from `FindElementsMixin`\n- Circular dependency!\n\n**Solution:** Late import inside factory function. Import only executes when function is called, breaking the cycle.\n\n### hasattr() for Context Detection: Elegant or Hacky?\n\nThe mixin uses `hasattr(self, '_object_id')` to detect Tab vs WebElement:\n\n```python\nif hasattr(self, '_object_id'):\n # WebElement: element-relative search\nelse:\n # Tab: document-level search\n```\n\n**Is this \"hacky\"?**\n\n- **No**: It's **duck typing** (Pythonic idiom)\n- Mixin doesn't need to know class hierarchy\n- Both Tab and WebElement provide `_connection_handler`\n- WebElement additionally provides `_object_id`\n\n**Alternative approaches:**\n\n1. **Type checking**: `if isinstance(self, WebElement)` → Couples mixin to WebElement\n2. **Abstract method**: Requires Tab/WebElement to implement `get_search_context()` → More boilerplate\n3. **Dependency injection**: Pass context as parameter → Breaks API ergonomics\n\n**Verdict:** `hasattr()` is the best solution for this use case.\n\n## Key Takeaways\n\n1. **Mixins enable code sharing** without coupling `Tab` and `WebElement` through inheritance\n2. **Context detection via duck typing** (`hasattr`) keeps mixin decoupled from class hierarchy\n3. **Auto-resolution optimizes performance** by using native methods for single attributes\n4. **XPath building provides composability** for multi-attribute queries\n5. **Polling-based waiting is simple** but trades CPU cycles for implementation simplicity\n6. **CDP object model complexity** is hidden behind WebElement abstraction\n7. **Type safety via overloads** provides precise return types for IDE support\n\n## Related Documentation\n\nFor deeper understanding of related architectural components:\n\n- **[Type System](./typing-system.md)**: Overload pattern, TypedDict, Generic types\n- **[WebElement Domain](./webelement-domain.md)**: WebElement architecture and interaction methods\n- **[Selectors Guide](./selectors-guide.md)**: CSS vs XPath syntax and best practices\n- **[Tab Domain](./tab-domain.md)**: Tab-level operations and context management\n\nFor practical usage patterns:\n\n- **[Element Finding Guide](../features/automation/element-finding.md)**: Practical examples and patterns\n- **[Human-Like Interactions](../features/automation/human-interactions.md)**: Realistic element interaction" }, { "path": "docs/en/deep-dive/architecture/index.md", "content": "# Internal Architecture\n\n**Understand the design, then break the rules intentionally.**\n\nMost documentation shows you **what** a framework does. This section reveals **how** and **why** Pydoll is architected the way it is: the design patterns, architectural decisions, and tradeoffs that shape every line of code.\n\n## Why Architecture Matters\n\nYou can use Pydoll effectively without understanding its internal architecture. But when you need to:\n\n- **Debug** complex issues that span multiple components\n- **Optimize** performance bottlenecks in large-scale automation\n- **Extend** Pydoll with custom functionality\n- **Contribute** improvements to the codebase\n- **Build** similar tools for different use cases\n\n...architectural knowledge becomes **indispensable**.\n\n!!! quote \"Architecture as Language\"\n **\"Architecture is frozen music.\"** - Johann Wolfgang von Goethe\n \n Good architecture isn't just about making code work, it's about making code **understandable**, **maintainable**, and **extensible**. Understanding Pydoll's architecture teaches you patterns you'll apply to every project.\n\n## The Six Architectural Domains\n\nPydoll's architecture is organized into **six cohesive domains**, each with clear responsibilities and interfaces:\n\n### 1. Browser Domain\n**[→ Explore Browser Architecture](./browser-domain.md)**\n\n**The orchestrator: managing processes, contexts, and global state.**\n\nThe Browser domain sits at the top of the hierarchy, coordinating:\n\n- **Process management**: Launching/terminating browser executables\n- **Browser contexts**: Isolated environments (like incognito windows)\n- **Tab registry**: Singleton pattern for Tab instances\n- **Proxy authentication**: Automatic auth via Fetch domain\n- **Global operations**: Downloads, permissions, window management\n\n**Key architectural patterns**:\n\n- **Abstract base class** for Chrome/Edge/other Chromium browsers\n- **Manager pattern** (ProcessManager, ProxyManager, TempDirManager)\n- **Singleton registry** for Tab instances (prevents duplicates)\n- **Context manager protocol** for automatic cleanup\n\n**Critical insight**: The Browser doesn't directly manipulate pages, it **coordinates** lower-level components. This separation of concerns enables multi-browser support and concurrent tab operations.\n\n---\n\n### 2. Tab Domain\n**[→ Explore Tab Architecture](./tab-domain.md)**\n\n**The workhorse: executing commands, managing state, coordinating automation.**\n\nThe Tab domain is Pydoll's primary interface, handling:\n\n- **Navigation**: Page loading with configurable wait states\n- **Element finding**: Delegated to FindElementsMixin\n- **JavaScript execution**: Both page and element contexts\n- **Event coordination**: Tab-specific event listeners\n- **Network monitoring**: Request/response capture and analysis\n- **IFrame handling**: Nested context management\n\n**Key architectural patterns**:\n\n- **Façade pattern**: Simplified interface to complex CDP operations\n- **Mixin composition**: FindElementsMixin for element location\n- **Per-tab WebSocket**: Independent connections for parallelism\n- **State flags**: Track enabled domains (network_events_enabled, etc.)\n- **Lazy initialization**: Request object created on first access\n\n**Critical insight**: Each Tab owns its **own ConnectionHandler**, enabling true parallel operations across tabs without contention or state leakage.\n\n---\n\n### 3. WebElement Domain\n**[→ Explore WebElement Architecture](./webelement-domain.md)**\n\n**The interactor: bridging Python code and DOM elements.**\n\nThe WebElement domain represents **individual DOM elements**, providing:\n\n- **Interaction methods**: Click, type, scroll, select\n- **Property access**: Text, HTML, bounds, attributes\n- **State queries**: Visibility, enabled status, value\n- **Screenshots**: Element-specific image capture\n- **Child finding**: Relative element location (also via FindElementsMixin)\n\n**Key architectural patterns**:\n\n- **Proxy pattern**: Python object representing remote browser element\n- **Object ID abstraction**: CDP's objectId hidden behind Python API\n- **Hybrid properties**: Sync (attributes) vs async (dynamic state)\n- **Command pattern**: Interaction methods wrap CDP commands\n- **Fallback strategies**: Multiple approaches for robustness\n\n**Critical insight**: WebElement maintains **both cached attributes** (from creation) and **dynamic state** (fetched on demand), balancing performance with freshness.\n\n---\n\n### 4. FindElements Mixin\n**[→ Explore FindElements Architecture](./find-elements-mixin.md)**\n\n**The locator: translating selectors into DOM queries.**\n\nThe FindElementsMixin provides element-finding capabilities to both Tab and WebElement through **composition**, not inheritance:\n\n- **Attribute-based finding**: `find(id='submit', class_name='btn')`\n- **Expression-based querying**: `query('div.container > p')`\n- **Strategy resolution**: Optimal selector for single vs. multiple attributes\n- **Waiting mechanisms**: Polling with configurable timeouts\n- **Context detection**: Document vs. element-relative searches\n\n**Key architectural patterns**:\n- **Mixin pattern**: Shared capability without inheritance hierarchy\n- **Strategy pattern**: Different selector strategies based on input\n- **Template method**: Common flow, strategy-specific implementation\n- **Factory function**: Late import to avoid circular dependencies\n- **Overload pattern**: Type-safe return types (WebElement vs list)\n\n**Critical insight**: The mixin uses **duck typing** (`hasattr(self, '_object_id')`) to detect Tab vs WebElement, enabling code reuse without tight coupling.\n\n---\n\n### 5. Event Architecture\n**[→ Explore Event Architecture](./event-architecture.md)**\n\n**The dispatcher: routing browser events to Python callbacks.**\n\nThe Event Architecture enables reactive automation through:\n\n- **Event registration**: `on()` method for subscribing to CDP events\n- **Callback dispatch**: Async execution without blocking\n- **Domain management**: Explicit enable/disable for performance\n- **Temporary callbacks**: Auto-removal after first invocation\n- **Multi-level scope**: Browser-wide vs tab-specific events\n\n**Key architectural patterns**:\n\n- **Observer pattern**: Subscribe/notify for event-driven code\n- **Registry pattern**: Event name → callback list mapping\n- **Wrapper pattern**: Auto-wrap sync callbacks for async execution\n- **Cleanup protocol**: Automatic callback removal on tab close\n- **Scope isolation**: Independent event contexts per tab\n\n**Critical insight**: Events are **push-based** (browser notifies Python), not poll-based, enabling low-latency reactive automation without busy-waiting.\n\n---\n\n### 6. Browser Requests Architecture\n**[→ Explore Requests Architecture](./browser-requests-architecture.md)**\n\n**The hybrid: HTTP requests with browser session state.**\n\nThe Browser Requests system bridges HTTP and browser automation:\n\n- **Session continuity**: Cookies and auth automatically included\n- **Dual data sources**: JavaScript Fetch API + CDP network events\n- **Complete metadata**: Headers, cookies, timing (not all available via JavaScript)\n- **`requests`-like API**: Familiar interface with browser power\n\n**Key architectural patterns**:\n\n- **Hybrid execution**: JavaScript for body, CDP for metadata\n- **Temporary event registration**: Enable/capture/disable pattern\n- **Lazy property initialization**: Request object created on first use\n- **Adapter pattern**: Requests-compatible interface to browser fetch\n\n**Critical insight**: Browser requests combine **two information sources** (JavaScript and CDP events). JavaScript provides the response body, CDP provides headers and cookies that JavaScript security policies hide.\n\n---\n\n## Architectural Principles\n\nThese six domains follow consistent principles:\n\n### 1. Separation of Concerns\nEach domain has a **single, well-defined responsibility**:\n\n- Browser → Process/context management\n- Tab → Command execution and state\n- WebElement → Element interaction\n- FindElements → Element location\n- Events → Reactive dispatch\n- Requests → HTTP in browser context\n\n**Benefit**: Changes in one domain rarely require changes in others.\n\n### 2. Composition Over Inheritance\nInstead of deep inheritance hierarchies, Pydoll uses:\n\n- **Mixins** (FindElementsMixin shared by Tab and WebElement)\n- **Managers** (ProcessManager, ProxyManager, TempDirManager)\n- **Dependency injection** (ConnectionHandler passed to components)\n\n**Benefit**: Flexible component reuse without tight coupling.\n\n### 3. Async by Default\nAll I/O operations are `async def` and must be `await`ed:\n\n- WebSocket communication\n- CDP command execution\n- Event callback dispatch\n- Network requests\n\n**Benefit**: Enables true concurrency with multiple tabs, parallel operations, and non-blocking I/O.\n\n### 4. Type Safety\nEvery public API has type annotations:\n\n- Function parameters and return types\n- CDP responses as `TypedDict`\n- Event types for callback parameters\n- Overloads for polymorphic methods\n\n**Benefit**: IDE autocomplete, static type checking, self-documenting code.\n\n### 5. Resource Management\nContext managers ensure cleanup:\n\n- `async with Browser()` → closes browser on exit\n- `async with tab.expect_file_chooser()` → disables interceptor\n- `async with tab.expect_download()` → cleans temp files\n\n**Benefit**: Automatic resource cleanup, prevents leaks even on exceptions.\n\n## Component Interaction\n\nUnderstanding how domains interact is key:\n\n```mermaid\ngraph TB\n User[Your Python Code]\n \n User --> Browser[Browser Domain]\n User --> Tab[Tab Domain]\n User --> Element[WebElement Domain]\n \n Browser --> ProcessMgr[Process Manager]\n Browser --> ContextMgr[Context Manager]\n Browser --> TabRegistry[Tab Registry]\n \n Tab --> ConnHandler[Connection Handler]\n Tab --> FindMixin[FindElements Mixin]\n Tab --> EventSystem[Event System]\n Tab --> RequestSystem[Request System]\n \n Element --> ConnHandler2[Connection Handler]\n Element --> FindMixin2[FindElements Mixin]\n \n ConnHandler --> WebSocket[WebSocket to CDP]\n ConnHandler2 --> WebSocket\n EventSystem --> ConnHandler\n RequestSystem --> ConnHandler\n RequestSystem --> EventSystem\n \n WebSocket --> Chrome[Chrome Browser]\n```\n\n**Key interactions**:\n\n1. **Browser creates Tabs** → Tabs stored in registry\n2. **Tab and WebElement both use FindElementsMixin** → Shared element location\n3. **Each Tab owns a ConnectionHandler** → Independent WebSocket connections\n4. **Request system uses Event system** → Network events capture metadata\n5. **All components use ConnectionHandler** → Centralized CDP communication\n\n## Prerequisites\n\nTo fully benefit from this section:\n\n- **[Core Fundamentals](../fundamentals/cdp.md)** - Understand CDP, async, and types\n- **Python design patterns** - Familiarity with common patterns\n- **OOP concepts** - Classes, inheritance, composition, interfaces\n- **Async Python** - Comfortable with `async def` and `await` \n\n**If you haven't read Fundamentals**, start there first. Architecture builds on those concepts.\n\n## Beyond Architecture\n\nAfter mastering internal architecture, you'll be ready for:\n\n- **Contributing code**: Understand where new features fit\n- **Performance optimization**: Identify bottlenecks and inefficiencies\n- **Custom extensions**: Build on Pydoll's patterns\n- **Similar tools**: Apply these patterns to other projects\n\n## Philosophy of Design\n\nGood architecture is **invisible**, it shouldn't get in your way. Pydoll's architecture prioritizes:\n\n1. **Simplicity**: Each component does one thing well\n2. **Consistency**: Similar operations have similar patterns\n3. **Explicitness**: No magic, no hidden behavior\n4. **Type safety**: Catch errors at design time, not runtime\n5. **Performance**: Async by default, parallelism without locks\n\nThese aren't arbitrary choices, they're **battle-tested principles** from decades of software engineering.\n\n---\n\n## Ready to Understand the Design?\n\nStart with **[Browser Domain](./browser-domain.md)** to understand how process management and context isolation work, then progress through the domains in order.\n\n**This is where usage becomes mastery.**\n\n---\n\n!!! success \"After Completing Architecture\"\n Once you understand these patterns, you'll see them everywhere in software engineering, not just Pydoll. These are **universal patterns** applied to browser automation:\n \n - Façade (Tab simplifies CDP complexity)\n - Observer (Event system for reactive code)\n - Mixin (FindElementsMixin for code reuse)\n - Registry (Browser tracks Tab instances)\n - Strategy (FindElements resolves optimal selectors)\n \n Good architecture is **timeless knowledge**.\n" }, { "path": "docs/en/deep-dive/architecture/shadow-dom.md", "content": "# Shadow DOM Architecture\n\nThe Shadow DOM is one of the most challenging aspects of modern web automation. Elements inside shadow trees are invisible to regular DOM queries, which breaks traditional automation approaches. This document explains how Shadow DOM works at the browser level, why conventional tools fail with closed shadow roots, and how Pydoll bypasses these restrictions through direct CDP access.\n\n!!! info \"Practical Usage Guide\"\n For usage examples and quick-start patterns, see the [Element Finding Guide — Shadow DOM section](../../features/element-finding.md#shadow-dom-support).\n\n## What is Shadow DOM?\n\nShadow DOM is a web standard that enables **DOM encapsulation**. It allows a component to have its own isolated DOM tree (the \"shadow tree\") attached to a regular DOM element (the \"shadow host\"). Elements inside a shadow tree are hidden from the main document's queries.\n\n```mermaid\ngraph TB\n subgraph \"Main DOM (Light DOM)\"\n Document[\"document\"]\n Host[\"div#my-component\\n(shadow host)\"]\n Other[\"p.normal-content\"]\n end\n\n subgraph \"Shadow Tree (Encapsulated)\"\n SR[\"#shadow-root (open)\"]\n Style[\"style\"]\n Button[\"button.internal\"]\n Input[\"input.private\"]\n end\n\n Document --> Host\n Document --> Other\n Host -.->|\"attachShadow()\"| SR\n SR --> Style\n SR --> Button\n SR --> Input\n```\n\n### Shadow Root Modes\n\nWhen a component creates a shadow root via `attachShadow()`, it specifies a **mode**:\n\n| Mode | JavaScript Access | CDP Access | Common Usage |\n|------|-------------------|------------|--------------|\n| `open` | `element.shadowRoot` returns the root | Full access via `backendNodeId` | Custom web components (Lit, Stencil) |\n| `closed` | `element.shadowRoot` returns `null` | Full access via `backendNodeId` | Security-sensitive components, payment forms |\n| `user-agent` | Not accessible via JS | Limited access | Browser-internal UI (input placeholders, video controls) |\n\nThis distinction is critical: **JavaScript-level access is restricted by mode, but CDP-level access is not.**\n\n### Why Regular Automation Fails\n\nTraditional automation tools rely on JavaScript execution in the page context:\n\n```javascript\n// WebDriver / Selenium approach\ndocument.querySelector('#my-component') // ✓ Finds the host\ndocument.querySelector('#my-component button') // ✗ Cannot cross shadow boundary\nelement.shadowRoot // ✗ Returns null for closed roots\n```\n\nThe shadow boundary is enforced by the browser's JavaScript engine. Any automation tool that executes JavaScript to find elements will hit this wall. This includes Selenium, Playwright's `page.evaluate()`, and any tool using `Runtime.evaluate()` with `document.querySelector()` at the document level.\n\n## How Pydoll Bypasses Shadow Boundaries\n\nPydoll's approach works at a layer **below JavaScript**: the Chrome DevTools Protocol. CDP has direct access to the browser's internal DOM representation, which ignores shadow mode restrictions entirely.\n\n### The CDP Advantage\n\n```mermaid\nsequenceDiagram\n participant User as User Code\n participant SR as ShadowRoot\n participant CH as ConnectionHandler\n participant CDP as Chrome CDP\n participant DOM as Browser DOM\n\n User->>SR: shadow_root.query('.btn')\n SR->>SR: _get_find_element_command(object_id)\n SR->>CH: execute_command(Runtime.callFunctionOn)\n CH->>CDP: WebSocket send\n CDP->>DOM: Execute querySelector on shadow root object\n DOM-->>CDP: Element result\n CDP-->>CH: Response with objectId\n CH-->>SR: Element data\n SR-->>User: WebElement instance\n```\n\nThe key insight is in **how the shadow root object is obtained** and **how queries are executed against it**:\n\n1. **Discovery**: `DOM.describeNode` with `pierce=true` returns shadow root nodes with their `backendNodeId`, regardless of mode\n2. **Resolution**: `DOM.resolveNode` converts a `backendNodeId` to a JavaScript `objectId` that references the shadow root directly\n3. **Querying**: `Runtime.callFunctionOn` executes `this.querySelector()` on the shadow root's `objectId`; this works because the call is made **on the shadow root object itself**, not from the document context\n\n### Step-by-Step: Shadow Root Access\n\n```mermaid\nflowchart TD\n A[\"WebElement\\n(shadow host)\"]\n B[\"shadowRoots[] with\\nbackendNodeId\"]\n C[\"JavaScript objectId\\nfor shadow root\"]\n D[\"ShadowRoot instance\"]\n E[\"WebElement\\n(inside shadow)\"]\n\n A -->|\"DOM.describeNode\\ndepth=1, pierce=true\"| B\n B -->|\"DOM.resolveNode\\nbackendNodeId\"| C\n C -->|\"Create ShadowRoot\\nwith objectId\"| D\n D -->|\"find() / query()\\nvia callFunctionOn\"| E\n```\n\n#### Step 1: Describe the Host Node\n\n```python\n# Pydoll sends this CDP command:\n{\n \"method\": \"DOM.describeNode\",\n \"params\": {\n \"objectId\": \"\",\n \"depth\": 1,\n \"pierce\": true # ← This is the key flag\n }\n}\n```\n\nThe `pierce` parameter tells CDP to traverse shadow boundaries when describing the node. The response includes shadow root information regardless of the shadow root mode:\n\n```json\n{\n \"result\": {\n \"node\": {\n \"nodeName\": \"DIV\",\n \"shadowRoots\": [\n {\n \"nodeId\": 0,\n \"backendNodeId\": 5,\n \"shadowRootType\": \"closed\",\n \"childNodeCount\": 4\n }\n ]\n }\n }\n}\n```\n\n!!! warning \"nodeId vs backendNodeId\"\n When the DOM domain is not explicitly enabled (which is Pydoll's default to minimize overhead), `nodeId` is always `0`. The `backendNodeId` is the stable, always-available identifier. Pydoll uses `backendNodeId` exclusively for shadow root resolution, which is why it works without requiring `DOM.enable()`.\n\n#### Step 2: Resolve to JavaScript Object\n\n```python\n# Convert backendNodeId to a usable objectId:\n{\n \"method\": \"DOM.resolveNode\",\n \"params\": {\n \"backendNodeId\": 5\n }\n}\n```\n\nThe response provides an `objectId`, a handle to the shadow root in JavaScript's object space:\n\n```json\n{\n \"result\": {\n \"object\": {\n \"objectId\": \"-2296764575741119861.1.3\"\n }\n }\n}\n```\n\n#### Step 3: Query Within the Shadow Root\n\nWith the shadow root's `objectId`, Pydoll leverages `FindElementsMixin`'s existing relative search mechanism:\n\n```python\n# When ShadowRoot.query('.btn') is called:\n{\n \"method\": \"Runtime.callFunctionOn\",\n \"params\": {\n \"functionDeclaration\": \"function() { return this.querySelector(\\\".btn\\\"); }\",\n \"objectId\": \"-2296764575741119861.1.3\"\n }\n}\n```\n\nThe function runs with `this` bound to the shadow root object. Since shadow roots implement the `querySelector()` and `querySelectorAll()` interfaces natively, CSS selectors work naturally within the shadow boundary.\n\n## ShadowRoot Architecture\n\n### Design Decision: Reuse FindElementsMixin\n\nThe most critical architectural decision was making `ShadowRoot` inherit from `FindElementsMixin`:\n\n```python\nclass ShadowRoot(FindElementsMixin):\n def __init__(self, object_id, connection_handler, mode, host_element):\n self._object_id = object_id # Shadow root CDP reference\n self._connection_handler = connection_handler # For CDP communication\n self._mode = mode # ShadowRootType enum\n self._host_element = host_element # Back-reference to host\n```\n\n**Why this works**: `FindElementsMixin._find_element()` checks `hasattr(self, '_object_id')`. When present, it uses `RELATIVE_QUERY_SELECTOR`, which calls `this.querySelector()` on the referenced object. Since shadow roots support `querySelector()` natively, `query()` with CSS selectors works automatically without any shadow-specific code.\n\n```python\n# This single line in FindElementsMixin enables shadow root searches:\nelif hasattr(self, '_object_id'):\n command = self._get_find_element_command(by, value, self._object_id)\n```\n\n`ShadowRoot` inherits `query()` and `find_or_wait_element()` from `FindElementsMixin`. However, `find()` and XPath-based `query()` are explicitly **blocked** on `ShadowRoot` (via the `_css_only` class flag) because shadow roots only support `querySelector()` / `querySelectorAll()` — XPath does not work inside shadow boundaries.\n\n!!! tip \"Architectural Consistency\"\n This is the same mechanism that makes `WebElement.find()` search within an element's children: the `_object_id` attribute signals \"search relative to me\" rather than \"search the whole document.\" `ShadowRoot`, `WebElement`, and `Tab` all share element-finding behavior through `FindElementsMixin`, with `ShadowRoot` restricted to CSS selectors only.\n\n### Class Relationships\n\n| Class | Has `_object_id` | Has `_connection_handler` | Find Scope |\n|-------|:-:|:-:|---|\n| `Tab` | No | Yes | Entire document |\n| `WebElement` | Yes | Yes | Within element's subtree |\n| `ShadowRoot` | Yes | Yes | Within shadow tree |\n\nAll three inherit from `FindElementsMixin`. The presence or absence of `_object_id` determines whether searches are document-global or scoped to a specific node.\n\n### Resolving Shadow Roots: backendNodeId Strategy\n\nPydoll deliberately uses `backendNodeId` instead of `nodeId` for shadow root resolution:\n\n| Property | `nodeId` | `backendNodeId` |\n|----------|----------|-----------------|\n| Requires `DOM.enable()` | Yes | No |\n| Stable across describe calls | No (0 when DOM not enabled) | Yes |\n| Works for shadow root resolution | Only when DOM enabled | Always |\n| Performance overhead | Higher (DOM domain tracking) | None |\n\nBy relying on `backendNodeId`, Pydoll avoids the overhead of enabling the DOM domain while maintaining reliable shadow root access. This is a pragmatic choice: most automation scenarios don't need the DOM domain's event stream, and enabling it adds memory and processing overhead for tracking every DOM mutation.\n\n## Closed Shadow Roots: Why CDP Access Works\n\nThis is the most commonly asked question: **if `element.shadowRoot` returns `null` for closed shadow roots in JavaScript, how can CDP access them?**\n\nThe answer lies in understanding the browser's architecture:\n\n```mermaid\ngraph TB\n subgraph \"JavaScript Runtime\"\n JS[\"JavaScript Code\"]\n API[\"Web APIs\\n(shadowRoot property)\"]\n end\n\n subgraph \"Browser Internals\"\n CDP_Layer[\"CDP Protocol Layer\"]\n DOM_Internal[\"Internal DOM Tree\"]\n end\n\n JS -->|\"element.shadowRoot\"| API\n API -->|\"mode == 'closed'\\n→ return null\"| JS\n CDP_Layer -->|\"DOM.describeNode\\npierce=true\"| DOM_Internal\n DOM_Internal -->|\"Always returns\\nfull shadow tree\"| CDP_Layer\n```\n\n**JavaScript access** goes through the Web API layer, which enforces the shadow mode restriction. When `mode='closed'`, the API returns `null`; this is an intentional access control boundary for web page code.\n\n**CDP access** operates below the Web API layer. It communicates directly with the browser's internal DOM representation. The `closed` mode restriction is a **JavaScript-level policy**, not a **DOM-level restriction**. The shadow tree still exists in the DOM; it's just hidden from JavaScript's view.\n\n!!! info \"Security Implications\"\n This is by design in the DevTools Protocol. CDP is intended for debugging and automation tools that need full DOM access. The `closed` mode protects shadow contents from other scripts on the same page (e.g., third-party scripts), not from the browser's debugging interface. This is the same reason browser DevTools can inspect closed shadow roots in the Elements panel.\n\n### Practical Verification\n\nYou can verify this behavior yourself:\n\n```python\nimport asyncio\nfrom pydoll.browser.chromium import Chrome\nfrom pydoll.protocol.dom.types import ShadowRootType\n\nasync def verify_closed_access():\n async with Chrome() as browser:\n tab = await browser.start()\n await tab.go_to('about:blank')\n\n # Create a closed shadow root via JavaScript\n await tab.execute_script(\"\"\"\n const host = document.createElement('div');\n host.id = 'test-host';\n document.body.appendChild(host);\n const shadow = host.attachShadow({ mode: 'closed' });\n shadow.innerHTML = '

Hidden content

';\n \"\"\")\n\n # JavaScript cannot access it:\n result = await tab.execute_script(\n \"return document.getElementById('test-host').shadowRoot\",\n return_by_value=True,\n )\n js_value = result['result']['result'].get('value')\n print(f\"JS shadowRoot: {js_value}\") # None\n\n # But Pydoll can:\n host = await tab.find(id='test-host')\n shadow = await host.get_shadow_root()\n print(f\"Shadow mode: {shadow.mode}\") # ShadowRootType.CLOSED\n\n secret = await shadow.query('.secret')\n text = await secret.text\n print(f\"Content: {text}\") # \"Hidden content\"\n\nasyncio.run(verify_closed_access())\n```\n\n## Nested Shadow Roots\n\nWeb components frequently compose other web components, creating multi-level shadow trees:\n\n```mermaid\ngraph TB\n subgraph \"Light DOM\"\n Host1[\"outer-component\\n(shadow host)\"]\n end\n\n subgraph \"Outer Shadow Tree\"\n SR1[\"#shadow-root (open)\"]\n Host2[\"inner-component\\n(shadow host)\"]\n P1[\"p.outer-text\"]\n end\n\n subgraph \"Inner Shadow Tree\"\n SR2[\"#shadow-root (closed)\"]\n Button[\"button.deep-btn\"]\n P2[\"p.inner-text\"]\n end\n\n Host1 -.-> SR1\n SR1 --> P1\n SR1 --> Host2\n Host2 -.-> SR2\n SR2 --> P2\n SR2 --> Button\n```\n\nPydoll handles this naturally by chaining `get_shadow_root()` calls. Each `ShadowRoot` produces `WebElement` instances that can themselves have shadow roots:\n\n```python\nouter_host = await tab.find(tag_name='outer-component')\nouter_shadow = await outer_host.get_shadow_root() # open\n\ninner_host = await outer_shadow.query('inner-component')\ninner_shadow = await inner_host.get_shadow_root() # closed, still works\n\ndeep_button = await inner_shadow.query('.deep-btn')\nawait deep_button.click()\n```\n\nEach level follows the same CDP resolution flow: `describeNode` then `resolveNode` then `ShadowRoot` with `_object_id` then `querySelector` via `callFunctionOn`.\n\n## Shadow Roots Inside IFrames\n\nA common real-world scenario involves shadow roots inside cross-origin iframes — for example, Cloudflare Turnstile captchas. This combines two isolation mechanisms: the iframe boundary and the shadow boundary.\n\n```mermaid\ngraph TB\n subgraph \"Main Page\"\n Host[\"div.widget\\n(shadow host)\"]\n end\n\n subgraph \"Shadow Tree\"\n SR1[\"#shadow-root\"]\n IFrame[\"iframe\\n(cross-origin)\"]\n end\n\n subgraph \"IFrame (OOPIF)\"\n Body[\"body\"]\n end\n\n subgraph \"IFrame Shadow Tree\"\n SR2[\"#shadow-root\"]\n Button[\"label.checkbox\"]\n end\n\n Host -.-> SR1\n SR1 --> IFrame\n IFrame -.->|\"separate process\"| Body\n Body -.-> SR2\n SR2 --> Button\n```\n\nPydoll handles this transparently through **iframe context propagation**. When a `ShadowRoot` is created, it inherits the iframe routing context from its host element:\n\n```python\n# The full chain: main page → shadow root → iframe → shadow root → element\nshadow_host = await tab.find(id='widget-container')\nfirst_shadow = await shadow_host.get_shadow_root()\n\niframe = await first_shadow.query('iframe')\nbody = await iframe.find(tag_name='body')\nsecond_shadow = await body.get_shadow_root()\n\n# click() works correctly — mouse events route through the OOPIF session\nbutton = await second_shadow.query('label.checkbox')\nawait button.click()\n```\n\n### How Context Propagation Works\n\nCross-origin iframes run in a separate browser process (Out-of-Process IFrame, or OOPIF). CDP commands for these iframes must be routed through a dedicated `sessionId`. Pydoll propagates this routing context automatically through the entire chain:\n\n1. **IFrame resolves its context**: `iframe.find()` establishes an `IFrameContext` with `session_id` and `session_handler` for the OOPIF\n2. **Child elements inherit context**: Elements found inside the iframe receive the `IFrameContext`\n3. **Shadow roots inherit from host**: `ShadowRoot` copies its host element's `_iframe_context`\n4. **Elements in shadow inherit from shadow root**: Elements found via `shadow.query()` receive the propagated context\n5. **Commands route correctly**: `_execute_command()` detects the inherited context and routes CDP commands (including `Input.dispatchMouseEvent` for `click()`) through the OOPIF session\n\nThis means coordinates from `DOM.getBoxModel` (which are relative to the iframe viewport) are correctly paired with mouse events dispatched to the same OOPIF session.\n\n## Finding Shadow Roots: find_shadow_roots()\n\n`Tab.find_shadow_roots()` traverses the entire DOM tree to collect all shadow roots found on the page.\n\n### How It Works\n\n```\nTab.find_shadow_roots()\n ├─ DOM.getDocument(depth=-1, pierce=true)\n │ └─ Returns full DOM tree with shadowRoots arrays\n ├─ Recursive tree walk: _collect_shadow_roots_from_tree()\n │ ├─ Collects shadowRoots entries with host backendNodeId\n │ ├─ Traverses children recursively\n │ └─ Traverses contentDocument (same-origin iframes)\n ├─ For each shadow root entry:\n │ ├─ DOM.resolveNode(backendNodeId) → objectId\n │ └─ Resolve host element (best-effort)\n └─ Returns list[ShadowRoot] with host references\n```\n\n### Timeout: Waiting for Shadow Roots\n\nShadow hosts are often injected asynchronously. `Tab.find_shadow_roots()` accepts a `timeout` parameter that polls every 0.5s until at least one shadow root is found or the timeout expires (raises `WaitElementTimeout`). Similarly, `WebElement.get_shadow_root()` also supports `timeout` for waiting on a specific element's shadow root:\n\n```python\n# Wait up to 10 seconds for shadow roots to appear\nshadow_roots = await tab.find_shadow_roots(timeout=10)\n\n# Wait for a shadow root on a specific element\nshadow = await element.get_shadow_root(timeout=5)\n```\n\n### Key Details\n\n- **`pierce=True`** in `DOM.getDocument` causes the browser to include `shadowRoots` arrays in node descriptions, allowing discovery of all shadow roots without navigating to each host individually.\n- **Same-origin iframe content** is included in the tree via `contentDocument` nodes. The traversal handles these.\n- Each returned `ShadowRoot` has a reference to its `host_element` (resolved best-effort via `DOM.resolveNode`).\n\n### Deep Traversal: Cross-Origin IFrames (OOPIFs)\n\nBy default, cross-origin iframes (OOPIFs) are **not** included in the DOM tree — their content lives in a separate browser process. Pass `deep=True` to also discover shadow roots inside OOPIFs:\n\n```python\nshadow_roots = await tab.find_shadow_roots(deep=True, timeout=10)\n```\n\nWhen `deep=True` is set, the method performs additional steps:\n\n```\nTab.find_shadow_roots(deep=True)\n ├─ ... (main document traversal as above) ...\n └─ _collect_oopif_shadow_roots()\n ├─ Browser-level ConnectionHandler (no page_id → browser endpoint)\n ├─ Target.getTargets() → filter type='iframe'\n └─ For each iframe target:\n ├─ Target.attachToTarget(targetId, flatten=True) → sessionId\n ├─ DOM.getDocument(depth=-1, pierce=True) with sessionId\n ├─ _collect_shadow_roots_from_tree() on OOPIF DOM\n └─ For each shadow root found:\n ├─ DOM.resolveNode(backendNodeId) with sessionId\n ├─ Resolve host element (best-effort) with sessionId\n ├─ Create IFrameContext(frame_id, session_handler, session_id)\n └─ Set IFrameContext on host element (or ShadowRoot directly)\n```\n\nThe returned `ShadowRoot` objects carry the OOPIF routing context (`IFrameContext`), so elements found via `shadow_root.query()` will automatically route CDP commands through the correct OOPIF session. This is critical for scenarios like Cloudflare Turnstile captchas, where the checkbox lives inside a closed shadow root within a cross-origin iframe.\n\n## Limitations and Edge Cases\n\n### Selector Strategies Inside Shadow Roots\n\n!!! warning \"CSS Selectors Only Inside Shadow Roots\"\n `find()` and XPath are **not supported** on `ShadowRoot` and will raise `NotImplementedError`. Always use `query()` with CSS selectors to search inside shadow roots.\n\nShadow roots natively implement `querySelector()` and `querySelectorAll()`, but **not** XPath evaluation. Pydoll enforces this by blocking `find()` (which may generate XPath internally) and XPath-based `query()` on `ShadowRoot`:\n\n| Method | Inside Shadow Root | Notes |\n|--------|:--:|---|\n| `query('css-selector')` | Supported | The only supported approach |\n| `find(...)` | Not supported | Raises `NotImplementedError` |\n| `query('//xpath')` | Not supported | Raises `NotImplementedError` |\n\n```python\nshadow = await host.get_shadow_root()\n\n# Supported: query() with CSS selectors\nbutton = await shadow.query('button.submit')\nemail = await shadow.query('#email-input')\nitems = await shadow.query('.item', find_all=True)\n\n# Not supported: find() and XPath raise NotImplementedError\n# shadow.find(id='email-input') # NotImplementedError\n# shadow.query('.//button') # NotImplementedError\n```\n\n### XPath Cannot Cross Shadow Boundaries\n\nXPath expressions from the document root cannot traverse shadow boundaries. This is a fundamental limitation of XPath, which was designed before Shadow DOM existed:\n\n```python\n# Won't find shadow content: document-level XPath cannot cross the boundary\nelement = await tab.find(xpath='//div[@id=\"host\"]//button')\n```\n\n### User-Agent Shadow Roots\n\nBrowser-internal shadow roots (e.g., `` placeholder styling, `