| Name | browser-core JSON |
| Version |
2.4.0
JSON |
| download |
| home_page | None |
| Summary | Um framework robusto e configurável para automação de navegadores, com gestão de perfis, sessões e uma CLI. |
| upload_time | 2025-07-28 17:21:00 |
| maintainer | None |
| docs_url | None |
| author | gabigolo |
| requires_python | >=3.8 |
| license | MIT |
| 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
[](https://badge.fury.io/py/browser-core)
[](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[](https://badge.fury.io/py/browser-core)\n[](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"
}
