Merge branch 'main' of github.com-lucas:LucasAlvws/pydoll into issue-214

Author: LucasAlvws

.github/workflows/deploy-docs.yml

@@ -1,37 +1,41 @@
-name: Deploy MkDocs to GitHub Pages
+name: Deploy site + docs
 
 on:
   push:
-    branches:
-      - main
+    branches: [main]
 
 jobs:
   deploy:
     runs-on: ubuntu-latest
-
     steps:
-    - name: Code Checkout
-      uses: actions/checkout@v3
+      - name: Code Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
 
-    - name: Setup Python
-      uses: actions/setup-python@v4
-      with:
-        python-version: '3.x'
+      - name: Install Dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install mkdocs mkdocs-material pymdown-extensions mkdocstrings[python] mkdocs-static-i18n
 
-    - name: Install Dependencies
-      run: |
-        python -m pip install --upgrade pip
-        pip install mkdocs
-        pip install mkdocs-material
-        pip install pymdown-extensions
-        pip install mkdocstrings[python]
-        pip install mkdocs-static-i18n
+      # Build MkDocs em pasta temporária
+      - name: Build MkDocs into temp folder
+        run: mkdocs build --site-dir temp_docs
 
-    - name: Build the documentation
-      run: mkdocs build
+      # Criar estrutura final do site
+      - name: Prepare final site
+        run: |
+          mkdir -p site/docs
+          mkdir -p site/images
+          cp -r temp_docs/* site/docs/
+          cp -r public/* site/
 
-    - name: Deploy to GitHub Pages
-      uses: peaceiris/actions-gh-pages@v3
-      with:
-        github_token: ${{ secrets.GITHUB_TOKEN }}
-        publish_dir: ./site
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./site
+          cname: pydoll.tech

CHANGELOG.md

@@ -1,3 +1,15 @@
+## 2.6.0 (2025-08-10)
+
+### Feat
+
+- add DownloadTimeout exception for file download timeouts
+- add context manager for handling file downloads in Tab class
+
+### Refactor
+
+- add type checking for connection handler in mixin class
+- add type overloads for event callback in Browser class
+
 ## 2.5.0 (2025-08-07)
 
 ### Feat

README.md

@@ -8,16 +8,16 @@
     <a href="https://codecov.io/gh/autoscrape-labs/pydoll" >
         <img src="https://codecov.io/gh/autoscrape-labs/pydoll/graph/badge.svg?token=40I938OGM9"/>
     </a>
-    <img src="https://github.com/thalissonvs/pydoll/actions/workflows/tests.yml/badge.svg" alt="Tests">
-    <img src="https://github.com/thalissonvs/pydoll/actions/workflows/ruff-ci.yml/badge.svg" alt="Ruff CI">
-    <img src="https://github.com/thalissonvs/pydoll/actions/workflows/mypy.yml/badge.svg" alt="MyPy CI">
+    <img src="https://github.com/autoscrape-labs/pydoll/actions/workflows/tests.yml/badge.svg" alt="Tests">
+    <img src="https://github.com/autoscrape-labs/pydoll/actions/workflows/ruff-ci.yml/badge.svg" alt="Ruff CI">
+    <img src="https://github.com/autoscrape-labs/pydoll/actions/workflows/mypy.yml/badge.svg" alt="MyPy CI">
     <img src="https://img.shields.io/badge/python-%3E%3D3.10-blue" alt="Python >= 3.10">
     <a href="https://deepwiki.com/autoscrape-labs/pydoll"><img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki"></a>
 </p>
 
 
 <p align="center">
-  📖 <a href="https://autoscrape-labs.github.io/pydoll/">Documentation</a> •
+  📖 <a href="https://pydoll.tech/">Documentation</a> •
   🚀 <a href="#-getting-started">Getting Started</a> •
   ⚡ <a href="#-advanced-features">Advanced Features</a> •
   🤝 <a href="#-contributing">Contributing</a> •
@@ -97,6 +97,39 @@ await tab.request.get('https://api.example.com/data', headers=headers)
 
 This opens up incredible possibilities for automation scenarios where you need both browser interaction AND API efficiency!
 
+### New expect_download() context manager — robust file downloads made easy!
+Tired of fighting with flaky download flows, missing files, or racy event listeners? Meet `tab.expect_download()`, a delightful, reliable way to handle file downloads.
+
+- Automatically sets the browser’s download behavior
+- Works with your own directory or a temporary folder (auto-cleaned!)
+- Waits for completion with a timeout (so your tests don’t hang)
+- Gives you a handy handle to read bytes/base64 or check `file_path`
+
+Tiny example that just works:
+
+```python
+import asyncio
+from pathlib import Path
+from pydoll.browser import Chrome
+
+async def download_report():
+    async with Chrome() as browser:
+        tab = await browser.start()
+        await tab.go_to('https://example.com/reports')
+
+        target_dir = Path('/tmp/my-downloads')
+        async with tab.expect_download(keep_file_at=target_dir, timeout=10) as download:
+            # Trigger the download in the page (button/link/etc.)
+            await (await tab.find(text='Download latest report')).click()
+            # Wait until finished and read the content
+            data = await download.read_bytes()
+            print(f"Downloaded {len(data)} bytes to: {download.file_path}")
+
+asyncio.run(download_report())
+```
+
+Want zero-hassle cleanup? Omit `keep_file_at` and we’ll create a temp folder and remove it automatically after the context exits. Perfect for tests.
+
 ### Total browser control with custom preferences! (thanks to [@LucasAlvws](https://github.com/LucasAlvws))
 Want to completely customize how Chrome behaves? **Now you can control EVERYTHING!**<br>
 The new `browser_preferences` system gives you access to hundreds of internal Chrome settings that were previously impossible to change programmatically. We're talking about deep browser customization that goes way beyond command-line flags!
@@ -176,7 +209,7 @@ options.browser_preferences = {
 
 This level of control was previously only available to Chrome extension developers - now it's in your automation toolkit!
 
-Check the [documentation](https://autoscrape-labs.github.io/pydoll/features/#custom-browser-preferences/) for more details.
+Check the [documentation](https://pydoll.tech/docs/features/#custom-browser-preferences/) for more details.
 
 ### New `get_parent_element()` method
 Retrieve the parent of any WebElement, making it easier to navigate the DOM structure:
@@ -487,7 +520,7 @@ options.add_argument('--disable-dev-shm-usage')
 
 ## 📚 Documentation
 
-For complete documentation, detailed examples and deep dives into all Pydoll functionalities, visit our [official documentation](https://autoscrape-labs.github.io/pydoll/).
+For complete documentation, detailed examples and deep dives into all Pydoll functionalities, visit our [official documentation](https://pydoll.tech/).
 
 The documentation includes:
 - **Getting Started Guide** - Step-by-step tutorials

README_zh.md

@@ -195,6 +195,40 @@ options = ChromiumOptions()
 options.start_timeout = 20  # 等待 20 秒
 ```
 
+### 新的 expect_download() 上下文管理器 —— 稳健、优雅的文件下载！
+还在为不稳定的下载流程、丢失的文件或混乱的事件监听而头疼吗？`tab.expect_download()` 来了：一种可靠、简洁的下载方式。
+
+- 自动配置浏览器下载行为
+- 支持自定义下载目录或临时目录（自动清理！）
+- 内置超时等待，防止任务卡住
+- 提供便捷句柄：读取字节/BASE64，获取 `file_path`
+
+一个“开箱即用”的小示例：
+
+```python
+import asyncio
+from pathlib import Path
+from pydoll.browser import Chrome
+
+async def download_report():
+    async with Chrome() as browser:
+        tab = await browser.start()
+        await tab.go_to('https://example.com/reports')
+
+        target_dir = Path('/tmp/my-downloads')
+        async with tab.expect_download(keep_file_at=target_dir, timeout=10) as dl:
+            # 触发页面上的下载（按钮/链接等）
+            await (await tab.find(text='Download latest report')).click()
+
+            # 等待完成并读取内容
+            data = await dl.read_bytes()
+            print(f"已下载 {len(data)} 字节，保存至: {dl.file_path}")
+
+asyncio.run(download_report())
+```
+
+想要“零成本清理”？不传 `keep_file_at` 即可——我们会创建临时目录，并在上下文退出后自动清理。对测试场景非常友好。
+
 ## 📦 安装
 
 ```bash

cz.yaml

@@ -2,4 +2,4 @@
 commitizen:
   name: cz_conventional_commits
   tag_format: $version
-  version: 2.5.0
+  version: 2.6.0

docs/deep-dive/webelement-domain.md

@@ -73,6 +73,7 @@ classDiagram
         +get_attribute(name: str)
         +set_input_files(files: list[str])
         +scroll_into_view()
+        +wait_until()
         +take_screenshot(path: str)
         +text
         +inner_html
@@ -373,8 +374,19 @@ is_visible = await element._is_element_visible()
 
 # Check if element is the topmost at its position
 is_on_top = await element._is_element_on_top()
+
+# Check if element can be interacted with
+is_interactable = await element._is_element_interactable()
+
+# Wait until the element is ready for interaction
+await element.wait_until(is_visible=True, is_interactable=True, timeout=5)
+
+# Raises ``WaitElementTimeout`` if the conditions aren't met in time.
 ```
 
+If both ``is_visible`` and ``is_interactable`` are set to ``True``, the element
+must satisfy **both** conditions to proceed.
+
 These verifications are crucial for reliable automation, ensuring that elements can be interacted with before attempting operations.
 
 ## Position and Scrolling

docs/features.md

@@ -209,6 +209,61 @@ asyncio.run(background_bypass_example())
 
 Access websites that actively block automation tools without using third-party captcha solving services. This native captcha handling makes Pydoll suitable for automating previously inaccessible websites.
 
+## Reliable Download Handling with expect_download
+
+The `tab.expect_download()` context manager provides a robust, event-driven way to capture file downloads.
+
+- Configures browser download behavior for you
+- Supports persistent target directory (`keep_file_at`) or temporary directory with auto-cleanup
+- Exposes a `_DownloadHandle` with convenience methods
+- Includes timeout protection to avoid indefinite waits
+
+### API Overview
+
+```python
+async with tab.expect_download(
+    keep_file_at: Optional[str | Path] = None,
+    timeout: Optional[float] = None,
+) as handle:
+    ... # trigger download action in page
+```
+
+- `keep_file_at`: Target directory to keep the downloaded file. If `None`, a temporary directory is created and removed automatically when the context exits.
+- `timeout`: Maximum seconds to wait for completion (defaults to 60 if not provided).
+
+`handle` exposes:
+
+- `handle.file_path: Optional[str]` — final resolved path after completion
+- `await handle.read_bytes() -> bytes`
+- `await handle.read_base64() -> str`
+- `await handle.wait_started(timeout: Optional[float] = None) -> None`
+- `await handle.wait_finished(timeout: Optional[float] = None) -> None`
+
+### Usage Examples
+
+Persist file in a specific directory:
+
+```python
+async with tab.expect_download(keep_file_at='/tmp/dl', timeout=15) as dl:
+    await (await tab.find(text='Export CSV')).click()
+    data = await dl.read_bytes()
+    print('Saved at:', dl.file_path)
+```
+
+Use a temporary directory (auto-cleanup) for tests:
+
+```python
+async with tab.expect_download() as dl:
+    await (await tab.find(text='Download PDF')).click()
+    pdf_b64 = await dl.read_base64()
+    # temp directory is cleaned automatically when leaving the context
+```
+
+Notes:
+
+- When the page emits no completion event within the configured `timeout`, a `DownloadTimeout` exception is raised.
+- If the browser does not provide a `filePath`, the manager falls back to the suggested filename in the chosen directory.
+
 ## Multi-Tab Management
 
 Pydoll provides sophisticated tab management capabilities with a singleton pattern that ensures efficient resource usage and prevents duplicate Tab instances for the same browser tab.

docs/landing-sitemap.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+  <url>
+    <loc>https://pydoll.tech/</loc>
+    <changefreq>daily</changefreq>
+    <priority>1.0</priority>
+  </url>
+</urlset>