pywebflx 0.1.0__tar.gz

pywebflx-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,39 @@
+name: CI
+
+on:
+  push:
+    branches: [master, main]
+  pull_request:
+    branches: [master, main]
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev]"
+
+      - name: Run unit tests
+        run: python -m pytest tests/ -v --ignore=tests/test_regression_e2e.py
+
+      - name: Build package
+        run: |
+          python -m pip install build
+          python -m build
+
+      - name: Verify extension in wheel
+        run: python -c "import pywebflx.cli; print(pywebflx.cli._get_extension_dir())"

pywebflx-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,33 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install build tools
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}

pywebflx-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+*.log
+site/

pywebflx-0.1.0/CLAUDE.md

@@ -0,0 +1,50 @@
+# PyWebFlx - Project Instructions
+
+## Overview
+
+PyWebFlx is a Python browser automation library that connects to already-open Chrome pages via Chrome Extension (Manifest V3) + WebSocket. The Python side runs a WebSocket server; the extension connects as a client.
+
+## Architecture
+
+- **Python package**: `src/pywebflx/` (async/await API)
+- **Chrome Extension**: `extension/` (Manifest V3, service worker)
+- **Documentation**: `docs/` (MkDocs Material, bilingual EN + PT-BR)
+- **Tests**: `tests/`
+
+## Documentation Rules
+
+- **ALWAYS** update documentation when changing the API, adding features, or modifying behavior.
+- Documentation lives in `docs/` with MkDocs Material + mkdocs-static-i18n.
+- Every `.md` file has a `.pt.md` counterpart (PT-BR translation). **Always update both**.
+- PT-BR docs must use proper accents (acentuacao correta).
+- After updating docs, deploy with: `"C:/Program Files/Python313/python.exe" -m mkdocs gh-deploy --force`
+- Do NOT mention UiPath in any documentation.
+
+## Key Commands
+
+```bash
+# Run tests
+"C:/Program Files/Python313/python.exe" -m pytest tests/ -v
+
+# Deploy docs
+"C:/Program Files/Python313/python.exe" -m mkdocs gh-deploy --force
+
+# Install in dev mode
+"C:/Program Files/Python313/python.exe" -m pip install -e ".[dev]"
+```
+
+## Conventions
+
+- Python path on this machine: `C:/Program Files/Python313/python.exe`
+- WebSocket port: 9819
+- All Python code uses async/await with asyncio
+- Extension uses chrome.scripting.executeScript (no eval/new Function due to CSP)
+- The `open` parameter in `use_browser()` follows: `"if_not_open"` (default), `"open"`, `"never"`
+- URL and title matching is partial (contains), not exact
+
+## Git
+
+- Remote: https://github.com/theflexa/pywebflx
+- Author: Flexa <the.flexa@outlook.com>
+- Docs site: https://theflexa.github.io/pywebflx/
+- Main branch: `master`

pywebflx-0.1.0/PKG-INFO

@@ -0,0 +1,90 @@
+Metadata-Version: 2.4
+Name: pywebflx
+Version: 0.1.0
+Summary: Browser automation for already-open Chrome pages via Extension + WebSocket
+Author-email: Flexa <the.flexa@outlook.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/theflexa/pywebflx
+Project-URL: Documentation, https://theflexa.github.io/pywebflx/
+Project-URL: Repository, https://github.com/theflexa/pywebflx
+Project-URL: Issues, https://github.com/theflexa/pywebflx/issues
+Keywords: browser,automation,chrome,rpa,websocket,scraping
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
+Classifier: Framework :: AsyncIO
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: websockets>=12.0
+Requires-Dist: loguru>=0.7.0
+Requires-Dist: click>=8.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: pytest-mock>=3.12; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+
+# PyWebFlx
+
+**Automação de navegador para páginas Chrome já abertas.**
+
+PyWebFlx conecta a páginas já abertas no Chrome via uma extensão (Manifest V3) + WebSocket. Diferente do Selenium, não cria sandbox — você automatiza o navegador real.
+
+## Instalacao
+
+```bash
+pip install pywebflx
+pywebflx install-extension
+```
+
+## Quick Start
+
+```python
+import asyncio
+from pywebflx import use_browser
+
+async def main():
+    async with use_browser(url="https://quotes.toscrape.com/") as browser:
+        # Inspect — entender a pagina
+        print(await browser.inspect(depth=5))
+
+        # Extrair dados
+        quotes = await browser.extract_data(
+            container="body",
+            row=".quote",
+            columns={"texto": ".text", "autor": ".author"}
+        )
+        for q in quotes:
+            print(f"{q['autor']}: {q['texto'][:60]}...")
+
+asyncio.run(main())
+```
+
+## Principais funcionalidades
+
+| Metodo | Descricao |
+|--------|-----------|
+| `use_browser()` | Conecta a aba por URL/titulo, abre se nao existir |
+| `click()` | Clica (CSS, XPath ou texto) |
+| `type_into()` | Digita em campos |
+| `get_text()` | Extrai texto de elemento |
+| `extract_data()` | Extrai dados estruturados (cards, listas) |
+| `extract_table()` | Extrai tabelas HTML com paginacao |
+| `inspect()` | Visao resumida do DOM (otimizado pra IA) |
+| `wait_element()` | Espera elemento aparecer |
+| `execute_js()` | Executa JavaScript na pagina |
+
+## Documentacao
+
+[https://theflexa.github.io/pywebflx/](https://theflexa.github.io/pywebflx/)
+
+## Licenca
+
+MIT

pywebflx-0.1.0/README.md

@@ -0,0 +1,57 @@
+# PyWebFlx
+
+**Automação de navegador para páginas Chrome já abertas.**
+
+PyWebFlx conecta a páginas já abertas no Chrome via uma extensão (Manifest V3) + WebSocket. Diferente do Selenium, não cria sandbox — você automatiza o navegador real.
+
+## Instalacao
+
+```bash
+pip install pywebflx
+pywebflx install-extension
+```
+
+## Quick Start
+
+```python
+import asyncio
+from pywebflx import use_browser
+
+async def main():
+    async with use_browser(url="https://quotes.toscrape.com/") as browser:
+        # Inspect — entender a pagina
+        print(await browser.inspect(depth=5))
+
+        # Extrair dados
+        quotes = await browser.extract_data(
+            container="body",
+            row=".quote",
+            columns={"texto": ".text", "autor": ".author"}
+        )
+        for q in quotes:
+            print(f"{q['autor']}: {q['texto'][:60]}...")
+
+asyncio.run(main())
+```
+
+## Principais funcionalidades
+
+| Metodo | Descricao |
+|--------|-----------|
+| `use_browser()` | Conecta a aba por URL/titulo, abre se nao existir |
+| `click()` | Clica (CSS, XPath ou texto) |
+| `type_into()` | Digita em campos |
+| `get_text()` | Extrai texto de elemento |
+| `extract_data()` | Extrai dados estruturados (cards, listas) |
+| `extract_table()` | Extrai tabelas HTML com paginacao |
+| `inspect()` | Visao resumida do DOM (otimizado pra IA) |
+| `wait_element()` | Espera elemento aparecer |
+| `execute_js()` | Executa JavaScript na pagina |
+
+## Documentacao
+
+[https://theflexa.github.io/pywebflx/](https://theflexa.github.io/pywebflx/)
+
+## Licenca
+
+MIT

pywebflx-0.1.0/docs/api/browser.md

@@ -0,0 +1,100 @@
+# use_browser
+
+Main entry point for PyWebFlx. Connects to a Chrome tab and returns a `BrowserContext` with all automation methods.
+
+## Signature
+
+```python
+async with use_browser(
+    url: str = None,
+    title: str = None,
+    open: str = "if_not_open",
+    config: PyWebFlxConfig = None,
+) as browser:
+    ...
+```
+
+## Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `url` | `str` | `None` | URL to search (partial match) and/or open |
+| `title` | `str` | `None` | Tab title to search (partial match) |
+| `open` | `str` | `"if_not_open"` | Opening behavior (see below) |
+| `config` | `PyWebFlxConfig` | `None` | Custom configuration |
+
+!!! info "Partial match"
+    Both `url` and `title` use **partial match** (contains). You don't need the full URL — just the fixed part is enough. This is especially useful for dynamic URLs:
+
+    ```python
+    # Matches any tab at mycon.gupy.io/candidates/...
+    async with use_browser(url="mycon.gupy.io/candidates") as browser:
+        ...
+    ```
+
+!!! tip "Combining `url` and `title`"
+    You can use both parameters together. The search uses **AND** logic — the tab must match both criteria:
+
+    ```python
+    # Tab must contain "gupy.io" in URL AND "Candidatos" in title
+    async with use_browser(url="gupy.io", title="Candidatos") as browser:
+        ...
+    ```
+
+### `open` parameter
+
+| Value | Behavior |
+|-------|----------|
+| `"if_not_open"` | Searches for an existing tab. If not found, opens the `url`. **(default)** |
+| `"open"` | Always opens a new tab with the `url`. |
+| `"never"` | Only connects to an existing tab. Never opens. |
+
+## Examples
+
+### Basic -- opens if not found
+
+```python
+async with use_browser(url="https://quotes.toscrape.com/") as browser:
+    await browser.click("#btn")
+```
+
+### Search by title
+
+```python
+async with use_browser(title="Portal Sicoob", open="never") as browser:
+    balance = await browser.get_text(".balance")
+```
+
+### Always open a new tab
+
+```python
+async with use_browser(url="https://example.com", open="open") as browser:
+    await browser.type_into("#email", text="user@email.com")
+```
+
+### With custom configuration
+
+```python
+from pywebflx import PyWebFlxConfig
+
+config = PyWebFlxConfig(default_timeout=30, retry_count=3)
+
+async with use_browser(url="https://example.com", config=config) as browser:
+    await browser.click("#btn", timeout=60)  # 60 overrides 30
+```
+
+### Multiple tabs
+
+```python
+async with use_browser(url="https://portal.com") as tab1:
+    async with use_browser(url="https://email.com") as tab2:
+        data = await tab1.get_text(".balance")
+        await tab2.type_into("#body", text=data)
+```
+
+## Exceptions
+
+| Exception | When |
+|-----------|------|
+| `BrowserNotFoundError` | Tab not found and `open="never"` |
+| `ExtensionNotConnectedError` | Chrome extension is not connected |

pywebflx-0.1.0/docs/api/browser.pt.md

@@ -0,0 +1,100 @@
+# use_browser
+
+Ponto de entrada principal do PyWebFlx. Conecta a uma aba do Chrome e retorna um `BrowserContext` com todos os métodos de automação.
+
+## Assinatura
+
+```python
+async with use_browser(
+    url: str = None,
+    title: str = None,
+    open: str = "if_not_open",
+    config: PyWebFlxConfig = None,
+) as browser:
+    ...
+```
+
+## Parâmetros
+
+| Parâmetro | Tipo | Padrão | Descrição |
+|-----------|------|--------|-----------|
+| `url` | `str` | `None` | URL para buscar (correspondência parcial) e/ou abrir |
+| `title` | `str` | `None` | Título da aba para buscar (correspondência parcial) |
+| `open` | `str` | `"if_not_open"` | Comportamento de abertura (veja abaixo) |
+| `config` | `PyWebFlxConfig` | `None` | Configuração personalizada |
+
+!!! info "Correspondência parcial"
+    Tanto `url` quanto `title` usam **correspondência parcial** (contém). Não é necessário a URL completa — basta o trecho fixo. Isso é especialmente útil para URLs dinâmicas:
+
+    ```python
+    # Encontra qualquer aba em mycon.gupy.io/candidates/...
+    async with use_browser(url="mycon.gupy.io/candidates") as browser:
+        ...
+    ```
+
+!!! tip "Combinando `url` e `title`"
+    Você pode usar ambos os parâmetros juntos. A busca usa lógica **AND** — a aba precisa corresponder aos dois critérios:
+
+    ```python
+    # Aba deve conter "gupy.io" na URL E "Candidatos" no título
+    async with use_browser(url="gupy.io", title="Candidatos") as browser:
+        ...
+    ```
+
+### Parâmetro `open`
+
+| Valor | Comportamento |
+|-------|---------------|
+| `"if_not_open"` | Busca uma aba existente. Se não encontrar, abre a `url`. **(padrão)** |
+| `"open"` | Sempre abre uma nova aba com a `url`. |
+| `"never"` | Apenas conecta a uma aba existente. Nunca abre. |
+
+## Exemplos
+
+### Básico -- abre se não encontrar
+
+```python
+async with use_browser(url="https://quotes.toscrape.com/") as browser:
+    await browser.click("#btn")
+```
+
+### Buscar por título
+
+```python
+async with use_browser(title="Portal Sicoob", open="never") as browser:
+    balance = await browser.get_text(".balance")
+```
+
+### Sempre abrir uma nova aba
+
+```python
+async with use_browser(url="https://example.com", open="open") as browser:
+    await browser.type_into("#email", text="user@email.com")
+```
+
+### Com configuração personalizada
+
+```python
+from pywebflx import PyWebFlxConfig
+
+config = PyWebFlxConfig(default_timeout=30, retry_count=3)
+
+async with use_browser(url="https://example.com", config=config) as browser:
+    await browser.click("#btn", timeout=60)  # 60 sobrescreve 30
+```
+
+### Múltiplas abas
+
+```python
+async with use_browser(url="https://portal.com") as tab1:
+    async with use_browser(url="https://email.com") as tab2:
+        data = await tab1.get_text(".balance")
+        await tab2.type_into("#body", text=data)
+```
+
+## Exceções
+
+| Exceção | Quando |
+|---------|--------|
+| `BrowserNotFoundError` | Aba não encontrada e `open="never"` |
+| `ExtensionNotConnectedError` | Extensão do Chrome não está conectada |

pywebflx-0.1.0/docs/api/config.md

@@ -0,0 +1,95 @@
+# Configuration
+
+`PyWebFlxConfig` controls timeouts, retries, WebSocket port, and logging.
+
+## Signature
+
+```python
+from pywebflx import PyWebFlxConfig
+
+config = PyWebFlxConfig(
+    default_timeout=10,
+    delay_between_actions=0.3,
+    retry_count=0,
+    on_error="raise",
+    ws_port=9819,
+    log_level="INFO",
+)
+```
+
+## Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `default_timeout` | `float` | `10` | Default timeout in seconds |
+| `delay_between_actions` | `float` | `0.3` | Delay between consecutive actions |
+| `retry_count` | `int` | `0` | Default retry attempts on failure |
+| `on_error` | `str` | `"raise"` | `"raise"` or `"continue"` |
+| `ws_port` | `int` | `9819` | WebSocket server port |
+| `log_level` | `str` | `"INFO"` | Log level |
+
+## Priority
+
+Parameter resolution follows this order:
+
+```
+action parameter  >  use_browser config  >  global defaults
+```
+
+```python
+# Global: timeout = 10 (default)
+# Config: timeout = 20
+# Action: timeout = 60 (wins)
+
+config = PyWebFlxConfig(default_timeout=20)
+
+async with use_browser(url="https://example.com", config=config) as browser:
+    await browser.click("#btn", timeout=60)  # uses 60
+    await browser.click("#btn2")             # uses 20
+```
+
+## Global defaults
+
+```python
+# Affect all new instances
+PyWebFlxConfig.set_defaults(default_timeout=15, retry_count=3)
+
+# Reset to original values
+PyWebFlxConfig.reset_defaults()
+```
+
+## Logging
+
+```python
+from pywebflx import configure_logging
+
+configure_logging(level="INFO")                        # console (default)
+configure_logging(level="DEBUG", sink="automation.log") # file
+configure_logging(level="DISABLED")                    # silent
+```
+
+### Levels
+
+| Level | What it logs |
+|-------|-------------|
+| `ERROR` | Final failure (after all retries) |
+| `WARN` | Retry, reconnection, fallback |
+| `INFO` | Action executed successfully |
+| `DEBUG` | Internal details (selector, JSON payload) |
+| `TRACE` | Everything (WebSocket bytes, partial DOM) |
+| `DISABLED` | Nothing |
+
+### Format
+
+```
+2026-03-28 14:32:05.123 [INFO]  [browser.click] #btn-save -> tab:42 -> success (120ms)
+2026-03-28 14:32:06.102 [WARN]  [browser.click] #btn-send -> tab:42 -> retry 1/3
+2026-03-28 14:32:08.001 [ERROR] [browser.extract_table] #table -> tab:42 -> failed: TabClosedError
+```
+
+### Per-action override
+
+```python
+await browser.click("#critical-btn", log_level="DEBUG")   # more detail
+await browser.click(row_selector, log_level="WARN")       # less noise in loops
+```

pywebflx-0.1.0/docs/api/config.pt.md

@@ -0,0 +1,95 @@
+# Configuração
+
+`PyWebFlxConfig` controla timeouts, retentativas, porta WebSocket e logging.
+
+## Assinatura
+
+```python
+from pywebflx import PyWebFlxConfig
+
+config = PyWebFlxConfig(
+    default_timeout=10,
+    delay_between_actions=0.3,
+    retry_count=0,
+    on_error="raise",
+    ws_port=9819,
+    log_level="INFO",
+)
+```
+
+## Parâmetros
+
+| Parâmetro | Tipo | Padrão | Descrição |
+|-----------|------|--------|-----------|
+| `default_timeout` | `float` | `10` | Timeout padrão em segundos |
+| `delay_between_actions` | `float` | `0.3` | Atraso entre ações consecutivas |
+| `retry_count` | `int` | `0` | Tentativas de retentativa padrão em caso de falha |
+| `on_error` | `str` | `"raise"` | `"raise"` ou `"continue"` |
+| `ws_port` | `int` | `9819` | Porta do servidor WebSocket |
+| `log_level` | `str` | `"INFO"` | Nível de log |
+
+## Prioridade
+
+A resolução de parâmetros segue esta ordem:
+
+```
+parâmetro da ação  >  config do use_browser  >  padrões globais
+```
+
+```python
+# Global: timeout = 10 (padrão)
+# Config: timeout = 20
+# Ação: timeout = 60 (vence)
+
+config = PyWebFlxConfig(default_timeout=20)
+
+async with use_browser(url="https://example.com", config=config) as browser:
+    await browser.click("#btn", timeout=60)  # usa 60
+    await browser.click("#btn2")             # usa 20
+```
+
+## Padrões globais
+
+```python
+# Afeta todas as novas instancias
+PyWebFlxConfig.set_defaults(default_timeout=15, retry_count=3)
+
+# Resetar para valores originais
+PyWebFlxConfig.reset_defaults()
+```
+
+## Logging
+
+```python
+from pywebflx import configure_logging
+
+configure_logging(level="INFO")                        # console (padrão)
+configure_logging(level="DEBUG", sink="automation.log") # arquivo
+configure_logging(level="DISABLED")                    # silencioso
+```
+
+### Níveis
+
+| Nível | O que registra |
+|-------|----------------|
+| `ERROR` | Falha final (após todas as retentativas) |
+| `WARN` | Retentativa, reconexão, fallback |
+| `INFO` | Ação executada com sucesso |
+| `DEBUG` | Detalhes internos (seletor, payload JSON) |
+| `TRACE` | Tudo (bytes WebSocket, DOM parcial) |
+| `DISABLED` | Nada |
+
+### Formato
+
+```
+2026-03-28 14:32:05.123 [INFO]  [browser.click] #btn-save -> tab:42 -> sucesso (120ms)
+2026-03-28 14:32:06.102 [WARN]  [browser.click] #btn-send -> tab:42 -> retentativa 1/3
+2026-03-28 14:32:08.001 [ERROR] [browser.extract_table] #table -> tab:42 -> falhou: TabClosedError
+```
+
+### Override por ação
+
+```python
+await browser.click("#critical-btn", log_level="DEBUG")   # mais detalhes
+await browser.click(row_selector, log_level="WARN")       # menos ruído em loops
+```