browser-core


Namebrowser-core JSON
Version 2.4.0 PyPI version JSON
download
home_pageNone
SummaryUm framework robusto e configurável para automação de navegadores, com gestão de perfis, sessões e uma CLI.
upload_time2025-07-28 17:21:00
maintainerNone
docs_urlNone
authorgabigolo
requires_python>=3.8
licenseMIT
keywords automation selenium web browser framework
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # Browser-Core

[![Versão PyPI](https://badge.fury.io/py/browser-core.svg)](https://badge.fury.io/py/browser-core)
[![Licença: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**Browser-Core** é uma plataforma completa para orquestração de navegadores. O projeto nasceu para simplificar
automações em larga escala, garantindo isolamento total dos ambientes e reprodutibilidade dos estados de cada sessão.

Neste documento você encontrará uma visão detalhada de como funciona o framework, dicas de utilização e todos os
recursos disponíveis.

## Sumário

1. [Introdução](#introdução)
2. [Instalação](#instalação)
3. [Conceitos Fundamentais](#conceitos-fundamentais)
4. [Fluxo de Trabalho](#fluxo-de-trabalho)
5. [Exemplos de Uso](#exemplos-de-uso)
6. [Comandos da CLI](#comandos-da-cli)
7. [Dicas Avançadas](#dicas-avançadas)
8. [Contribuindo](#contribuindo)
9. [Licença](#licença)

---

## Introdução

Automatizar tarefas de navegador exige controle refinado sobre perfis, versões de drivers e paralelismo. O *
*Browser-Core** abstrai essa complexidade oferecendo:

- Camadas de snapshots reutilizáveis para capturar o estado exato do navegador (cookies, localStorage, extensões, etc.).
- Workers isolados que partem desses snapshots e executam tarefas independentes em paralelo.
- Integração transparente com Selenium e Playwright, bastando escolher o motor desejado.
- Uma CLI poderosa para manipular snapshots e gerenciar o armazenamento local.

Com esses componentes é possível escalar automações para centenas de execuções mantendo total rastreabilidade.

---

## Instalação

A instalação mais simples é via [PyPI](https://pypi.org/project/browser-core/):

```bash
pip install browser-core
```

Isso disponibiliza a biblioteca para uso em scripts Python e também instala a ferramenta de linha de comando
`browser-core`.

---

## Conceitos Fundamentais

**Snapshots em Camadas**
: Permitem criar "imagens" do navegador e derivar novos estados a partir delas. Assim você registra um login ou
configuração apenas uma vez e reutiliza em milhares de execuções.

**Workers Isolados**
: Cada worker é iniciado a partir de um snapshot específico e executa a tarefa em um perfil totalmente separado dos
demais.

**Drivers Gerenciados**
: O projeto baixa e armazena a versão exata do WebDriver para o navegador escolhido, evitando incompatibilidades em
diferentes máquinas.

**Arquitetura Multi‑engine**
: Tanto Selenium quanto Playwright podem ser utilizados com a mesma API de alto nível.

**CLI Integrada**
: Inclui comandos para criar snapshots base, listar estados existentes, inspecionar metadados e limpar todos os
artefatos.

---

## Fluxo de Trabalho

O uso típico divide-se em duas fases: criação dos snapshots e execução das tarefas.

### 1. Preparar os Snapshots

1. **Criar o Snapshot Base** – Perfil limpo com a versão de navegador desejada:

   ```bash
   browser-core snapshots create-base chrome-base
   ```

2. **Derivar um Snapshot com Estado** – Por exemplo, realizar login em um site e salvar esse estado:

   ```python
   # scripts/create_login_snapshot.py
   import os
   from browser_core import Orchestrator, Worker, create_selector
   from browser_core.types import SelectorType
   
   APP_USER = os.getenv("APP_USER")
   APP_PASSWORD = os.getenv("APP_PASSWORD")

   def perform_login(worker: Worker):
       """Função que executa a lógica de login."""

       worker.navigate_to("https://app.exemplo.com/login")
       worker.get(create_selector("input[name='email']", SelectorType.CSS)).send_keys(APP_USER)
       worker.get(create_selector("input[name='password']", SelectorType.CSS)).send_keys(APP_PASSWORD)
       worker.get(create_selector("button[type='submit']", SelectorType.CSS)).click()
       worker.get(create_selector("#dashboard", SelectorType.CSS)) # Aguarda o carregamento

   def main():
       """Função principal para orquestrar a criação do snapshot."""
       Orchestrator().create_snapshot_from_task(
           base_snapshot_id="chrome-base",
           new_snapshot_id="app_logged_in",
           setup_function=perform_login,
           metadata={"description": "Sessão autenticada"}
       )
       print("Snapshot 'app_logged_in' criado com sucesso!")

   if __name__ == "__main__":
       main()
   ```

### 2. Executar Tarefas em Paralelo

Com o snapshot `app_logged_in` pronto, processe uma série de itens utilizando vários workers:

```python
# scripts/run_tasks.py
from browser_core import Orchestrator, Worker, create_selector, default_settings
from browser_core.types import SelectorType


def fetch_report(worker: Worker, report_id: str):
    """Função que cada worker executará para buscar um relatório."""
    worker.navigate_to(f"https://app.exemplo.com/reports/{report_id}")
    table = worker.get(create_selector("#report-data-table", SelectorType.CSS)).text
    return {"report_id": report_id, "length": len(table)}

def main():
    """Função principal para executar as tarefas em paralelo."""
    REPORTS = ["Q1-2024", "Q2-2024", "Q3-2024", "Q4-2024"]
    settings = default_settings()
    settings["browser"]["headless"] = True

    results = Orchestrator(settings).run_tasks_in_squad(
        squad_size=2,
        base_snapshot_id="app_logged_in",
        task_items=REPORTS,
        worker_setup_function=lambda w: True,  # Função de setup simples
        item_processing_function=fetch_report,
    )
    print(results)

if __name__ == "__main__":
    main()
```

---

## Exemplos de Uso

O exemplo acima demonstra a execução de tarefas em paralelo utilizando snapshots para reaproveitar o estado de login.

---

## Comandos da CLI

A ferramenta `browser-core` auxilia na criação e manutenção dos snapshots e do armazenamento:

- **Criar snapshot base**
    ```bash
    browser-core snapshots create-base <snapshot-id>
    ```

- **Listar snapshots existentes**
    ```bash
    browser-core snapshots list
    ```

- **Inspecionar um snapshot**
    ```bash
    browser-core snapshots inspect <snapshot-id>
    ```
- **Criar snapshot a partir de uma tarefa**
    ```bash
    browser-core snapshots create-from-task --base <id-base> --new <id-novo> \
        --setup-script path/setup.py --setup-function func
    ```
- **Depurar um snapshot**
    ```bash
    browser-core snapshots debug <snapshot-id>
    ```
- **Executar tarefas em esquadrão**
    ```bash
    browser-core run --snapshot <id> --tasks-file dados.csv \
        --worker-script worker.py --worker-function processa
    ```

- **Limpar armazenamento**
    ```bash
    browser-core storage clean --force
    ```

Todas as opções estão disponíveis com `browser-core --help`.

---

## Dicas Avançadas

- **Modo headless ou gráfico**: Defina `settings["browser"]["headless"]` para alternar entre execução invisível ou com
  janela aberta.
- **Uso de proxies e variáveis de ambiente**: É possível configurar proxies ou outras opções de driver diretamente nas
  definições de `Settings`.
- **Persistência de logs**: Cada execução cria uma pasta com registros detalhados em `tasks_logs_dir`, auxiliando
  depuração e auditoria.
- **API de Elementos mais rica**: `ElementProxy` agora possui métodos como `hover()`, `scroll_to_view()` e
  utilidades de espera (`wait_for_visible`, `wait_for_clickable`). Também é possível obter múltiplos elementos com
  `worker.get_all()` e coletar seus textos com `get_texts()`.
- **Pré-aquecimento do WebDriver**: O Orchestrator garante que o driver necessário seja baixado uma única vez antes
  de iniciar os workers, evitando conflitos em execuções paralelas.
- **Extensibilidade**: A estrutura de `Worker` e `Orchestrator` permite implementar tarefas complexas com facilidade,
  reutilizando funções comuns de manipulação de página.

---

## Contribuindo

Contribuições são bem-vindas! Para configurar o ambiente de desenvolvimento:

1. Clone o repositório:
   ```bash
   git clone https://github.com/gabrielbarbosel/browser-core.git
   cd browser-core
   ```

2. Crie um ambiente virtual:
   ```bash
   python -m venv .venv
   source .venv/bin/activate
   ```

3. Instale as dependências de desenvolvimento:
   ```bash
   pip install -e ".[dev]"
   ```

4. Execute as verificações locais:
   ```bash
   black -q src
   pytest -q
   ```

---

## Licença

Distribuído sob a licença MIT. Consulte o arquivo [LICENSE](LICENSE) para mais detalhes.

            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "browser-core",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.8",
    "maintainer_email": null,
    "keywords": "automation, selenium, web, browser, framework",
    "author": "gabigolo",
    "author_email": null,
    "download_url": "https://files.pythonhosted.org/packages/83/e3/7e9b41695bacfc8220adf5cef437da12e9e02fabf7a3dd98c2e3fa64040c/browser_core-2.4.0.tar.gz",
    "platform": null,
    "description": "# Browser-Core\n\n[![Vers\u00e3o PyPI](https://badge.fury.io/py/browser-core.svg)](https://badge.fury.io/py/browser-core)\n[![Licen\u00e7a: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n**Browser-Core** \u00e9 uma plataforma completa para orquestra\u00e7\u00e3o de navegadores. O projeto nasceu para simplificar\nautoma\u00e7\u00f5es em larga escala, garantindo isolamento total dos ambientes e reprodutibilidade dos estados de cada sess\u00e3o.\n\nNeste documento voc\u00ea encontrar\u00e1 uma vis\u00e3o detalhada de como funciona o framework, dicas de utiliza\u00e7\u00e3o e todos os\nrecursos dispon\u00edveis.\n\n## Sum\u00e1rio\n\n1. [Introdu\u00e7\u00e3o](#introdu\u00e7\u00e3o)\n2. [Instala\u00e7\u00e3o](#instala\u00e7\u00e3o)\n3. [Conceitos Fundamentais](#conceitos-fundamentais)\n4. [Fluxo de Trabalho](#fluxo-de-trabalho)\n5. [Exemplos de Uso](#exemplos-de-uso)\n6. [Comandos da CLI](#comandos-da-cli)\n7. [Dicas Avan\u00e7adas](#dicas-avan\u00e7adas)\n8. [Contribuindo](#contribuindo)\n9. [Licen\u00e7a](#licen\u00e7a)\n\n---\n\n## Introdu\u00e7\u00e3o\n\nAutomatizar tarefas de navegador exige controle refinado sobre perfis, vers\u00f5es de drivers e paralelismo. O *\n*Browser-Core** abstrai essa complexidade oferecendo:\n\n- Camadas de snapshots reutiliz\u00e1veis para capturar o estado exato do navegador (cookies, localStorage, extens\u00f5es, etc.).\n- Workers isolados que partem desses snapshots e executam tarefas independentes em paralelo.\n- Integra\u00e7\u00e3o transparente com Selenium e Playwright, bastando escolher o motor desejado.\n- Uma CLI poderosa para manipular snapshots e gerenciar o armazenamento local.\n\nCom esses componentes \u00e9 poss\u00edvel escalar automa\u00e7\u00f5es para centenas de execu\u00e7\u00f5es mantendo total rastreabilidade.\n\n---\n\n## Instala\u00e7\u00e3o\n\nA instala\u00e7\u00e3o mais simples \u00e9 via [PyPI](https://pypi.org/project/browser-core/):\n\n```bash\npip install browser-core\n```\n\nIsso disponibiliza a biblioteca para uso em scripts Python e tamb\u00e9m instala a ferramenta de linha de comando\n`browser-core`.\n\n---\n\n## Conceitos Fundamentais\n\n**Snapshots em Camadas**\n: Permitem criar \"imagens\" do navegador e derivar novos estados a partir delas. Assim voc\u00ea registra um login ou\nconfigura\u00e7\u00e3o apenas uma vez e reutiliza em milhares de execu\u00e7\u00f5es.\n\n**Workers Isolados**\n: Cada worker \u00e9 iniciado a partir de um snapshot espec\u00edfico e executa a tarefa em um perfil totalmente separado dos\ndemais.\n\n**Drivers Gerenciados**\n: O projeto baixa e armazena a vers\u00e3o exata do WebDriver para o navegador escolhido, evitando incompatibilidades em\ndiferentes m\u00e1quinas.\n\n**Arquitetura Multi\u2011engine**\n: Tanto Selenium quanto Playwright podem ser utilizados com a mesma API de alto n\u00edvel.\n\n**CLI Integrada**\n: Inclui comandos para criar snapshots base, listar estados existentes, inspecionar metadados e limpar todos os\nartefatos.\n\n---\n\n## Fluxo de Trabalho\n\nO uso t\u00edpico divide-se em duas fases: cria\u00e7\u00e3o dos snapshots e execu\u00e7\u00e3o das tarefas.\n\n### 1. Preparar os Snapshots\n\n1. **Criar o Snapshot Base** \u2013 Perfil limpo com a vers\u00e3o de navegador desejada:\n\n   ```bash\n   browser-core snapshots create-base chrome-base\n   ```\n\n2. **Derivar um Snapshot com Estado** \u2013 Por exemplo, realizar login em um site e salvar esse estado:\n\n   ```python\n   # scripts/create_login_snapshot.py\n   import os\n   from browser_core import Orchestrator, Worker, create_selector\n   from browser_core.types import SelectorType\n   \n   APP_USER = os.getenv(\"APP_USER\")\n   APP_PASSWORD = os.getenv(\"APP_PASSWORD\")\n\n   def perform_login(worker: Worker):\n       \"\"\"Fun\u00e7\u00e3o que executa a l\u00f3gica de login.\"\"\"\n\n       worker.navigate_to(\"https://app.exemplo.com/login\")\n       worker.get(create_selector(\"input[name='email']\", SelectorType.CSS)).send_keys(APP_USER)\n       worker.get(create_selector(\"input[name='password']\", SelectorType.CSS)).send_keys(APP_PASSWORD)\n       worker.get(create_selector(\"button[type='submit']\", SelectorType.CSS)).click()\n       worker.get(create_selector(\"#dashboard\", SelectorType.CSS)) # Aguarda o carregamento\n\n   def main():\n       \"\"\"Fun\u00e7\u00e3o principal para orquestrar a cria\u00e7\u00e3o do snapshot.\"\"\"\n       Orchestrator().create_snapshot_from_task(\n           base_snapshot_id=\"chrome-base\",\n           new_snapshot_id=\"app_logged_in\",\n           setup_function=perform_login,\n           metadata={\"description\": \"Sess\u00e3o autenticada\"}\n       )\n       print(\"Snapshot 'app_logged_in' criado com sucesso!\")\n\n   if __name__ == \"__main__\":\n       main()\n   ```\n\n### 2. Executar Tarefas em Paralelo\n\nCom o snapshot `app_logged_in` pronto, processe uma s\u00e9rie de itens utilizando v\u00e1rios workers:\n\n```python\n# scripts/run_tasks.py\nfrom browser_core import Orchestrator, Worker, create_selector, default_settings\nfrom browser_core.types import SelectorType\n\n\ndef fetch_report(worker: Worker, report_id: str):\n    \"\"\"Fun\u00e7\u00e3o que cada worker executar\u00e1 para buscar um relat\u00f3rio.\"\"\"\n    worker.navigate_to(f\"https://app.exemplo.com/reports/{report_id}\")\n    table = worker.get(create_selector(\"#report-data-table\", SelectorType.CSS)).text\n    return {\"report_id\": report_id, \"length\": len(table)}\n\ndef main():\n    \"\"\"Fun\u00e7\u00e3o principal para executar as tarefas em paralelo.\"\"\"\n    REPORTS = [\"Q1-2024\", \"Q2-2024\", \"Q3-2024\", \"Q4-2024\"]\n    settings = default_settings()\n    settings[\"browser\"][\"headless\"] = True\n\n    results = Orchestrator(settings).run_tasks_in_squad(\n        squad_size=2,\n        base_snapshot_id=\"app_logged_in\",\n        task_items=REPORTS,\n        worker_setup_function=lambda w: True,  # Fun\u00e7\u00e3o de setup simples\n        item_processing_function=fetch_report,\n    )\n    print(results)\n\nif __name__ == \"__main__\":\n    main()\n```\n\n---\n\n## Exemplos de Uso\n\nO exemplo acima demonstra a execu\u00e7\u00e3o de tarefas em paralelo utilizando snapshots para reaproveitar o estado de login.\n\n---\n\n## Comandos da CLI\n\nA ferramenta `browser-core` auxilia na cria\u00e7\u00e3o e manuten\u00e7\u00e3o dos snapshots e do armazenamento:\n\n- **Criar snapshot base**\n    ```bash\n    browser-core snapshots create-base <snapshot-id>\n    ```\n\n- **Listar snapshots existentes**\n    ```bash\n    browser-core snapshots list\n    ```\n\n- **Inspecionar um snapshot**\n    ```bash\n    browser-core snapshots inspect <snapshot-id>\n    ```\n- **Criar snapshot a partir de uma tarefa**\n    ```bash\n    browser-core snapshots create-from-task --base <id-base> --new <id-novo> \\\n        --setup-script path/setup.py --setup-function func\n    ```\n- **Depurar um snapshot**\n    ```bash\n    browser-core snapshots debug <snapshot-id>\n    ```\n- **Executar tarefas em esquadr\u00e3o**\n    ```bash\n    browser-core run --snapshot <id> --tasks-file dados.csv \\\n        --worker-script worker.py --worker-function processa\n    ```\n\n- **Limpar armazenamento**\n    ```bash\n    browser-core storage clean --force\n    ```\n\nTodas as op\u00e7\u00f5es est\u00e3o dispon\u00edveis com `browser-core --help`.\n\n---\n\n## Dicas Avan\u00e7adas\n\n- **Modo headless ou gr\u00e1fico**: Defina `settings[\"browser\"][\"headless\"]` para alternar entre execu\u00e7\u00e3o invis\u00edvel ou com\n  janela aberta.\n- **Uso de proxies e vari\u00e1veis de ambiente**: \u00c9 poss\u00edvel configurar proxies ou outras op\u00e7\u00f5es de driver diretamente nas\n  defini\u00e7\u00f5es de `Settings`.\n- **Persist\u00eancia de logs**: Cada execu\u00e7\u00e3o cria uma pasta com registros detalhados em `tasks_logs_dir`, auxiliando\n  depura\u00e7\u00e3o e auditoria.\n- **API de Elementos mais rica**: `ElementProxy` agora possui m\u00e9todos como `hover()`, `scroll_to_view()` e\n  utilidades de espera (`wait_for_visible`, `wait_for_clickable`). Tamb\u00e9m \u00e9 poss\u00edvel obter m\u00faltiplos elementos com\n  `worker.get_all()` e coletar seus textos com `get_texts()`.\n- **Pr\u00e9-aquecimento do WebDriver**: O Orchestrator garante que o driver necess\u00e1rio seja baixado uma \u00fanica vez antes\n  de iniciar os workers, evitando conflitos em execu\u00e7\u00f5es paralelas.\n- **Extensibilidade**: A estrutura de `Worker` e `Orchestrator` permite implementar tarefas complexas com facilidade,\n  reutilizando fun\u00e7\u00f5es comuns de manipula\u00e7\u00e3o de p\u00e1gina.\n\n---\n\n## Contribuindo\n\nContribui\u00e7\u00f5es s\u00e3o bem-vindas! Para configurar o ambiente de desenvolvimento:\n\n1. Clone o reposit\u00f3rio:\n   ```bash\n   git clone https://github.com/gabrielbarbosel/browser-core.git\n   cd browser-core\n   ```\n\n2. Crie um ambiente virtual:\n   ```bash\n   python -m venv .venv\n   source .venv/bin/activate\n   ```\n\n3. Instale as depend\u00eancias de desenvolvimento:\n   ```bash\n   pip install -e \".[dev]\"\n   ```\n\n4. Execute as verifica\u00e7\u00f5es locais:\n   ```bash\n   black -q src\n   pytest -q\n   ```\n\n---\n\n## Licen\u00e7a\n\nDistribu\u00eddo sob a licen\u00e7a MIT. Consulte o arquivo [LICENSE](LICENSE) para mais detalhes.\n",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "Um framework robusto e configur\u00e1vel para automa\u00e7\u00e3o de navegadores, com gest\u00e3o de perfis, sess\u00f5es e uma CLI.",
    "version": "2.4.0",
    "project_urls": {
        "Bug Tracker": "https://github.com/gabrielbarbosel/browser-core/issues",
        "Homepage": "https://github.com/gabrielbarbosel/browser-core",
        "Repository": "https://github.com/gabrielbarbosel/browser-core"
    },
    "split_keywords": [
        "automation",
        " selenium",
        " web",
        " browser",
        " framework"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "a471358103db4ab0b8c351c558f71126b32c64fc70fde2a5e5e7d94ef3c68570",
                "md5": "e57f7a7bf3d1deed951ee9fe41d9a701",
                "sha256": "779aacfc4607eef785f50d1efb9c1a3567799912f308fda78a6350c3bf310bde"
            },
            "downloads": -1,
            "filename": "browser_core-2.4.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "e57f7a7bf3d1deed951ee9fe41d9a701",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.8",
            "size": 54746,
            "upload_time": "2025-07-28T17:20:58",
            "upload_time_iso_8601": "2025-07-28T17:20:58.781676Z",
            "url": "https://files.pythonhosted.org/packages/a4/71/358103db4ab0b8c351c558f71126b32c64fc70fde2a5e5e7d94ef3c68570/browser_core-2.4.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "83e37e9b41695bacfc8220adf5cef437da12e9e02fabf7a3dd98c2e3fa64040c",
                "md5": "e49541419bb4a381bf30ac1b787ad038",
                "sha256": "c4e442121c4053cc7188b93b05c9bcee1b115707c127772d21891cf268e07a91"
            },
            "downloads": -1,
            "filename": "browser_core-2.4.0.tar.gz",
            "has_sig": false,
            "md5_digest": "e49541419bb4a381bf30ac1b787ad038",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.8",
            "size": 45709,
            "upload_time": "2025-07-28T17:21:00",
            "upload_time_iso_8601": "2025-07-28T17:21:00.430086Z",
            "url": "https://files.pythonhosted.org/packages/83/e3/7e9b41695bacfc8220adf5cef437da12e9e02fabf7a3dd98c2e3fa64040c/browser_core-2.4.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-07-28 17:21:00",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "gabrielbarbosel",
    "github_project": "browser-core",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "lcname": "browser-core"
}
        
Elapsed time: 1.91300s