josias 0.1.0__tar.gz

josias-0.1.0/.gitignore

@@ -0,0 +1,38 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.eggs/
+dist/
+build/
+*.egg
+
+# Ambientes virtuais
+.venv/
+venv/
+env/
+
+# Testes e cobertura
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# SO
+.DS_Store
+Thumbs.db
+
+# Projeto
+examples/output/
+*.log
+
+# Build PyPI
+*.whl
+*.tar.gz

josias-0.1.0/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+Todas as mudanças relevantes deste projeto serão documentadas neste arquivo.
+
+O formato segue [Keep a Changelog](https://keepachangelog.com/) e o versionamento [SemVer](https://semver.org/).
+
+## [0.1.0] - 2026-06-30
+
+### Adicionado
+
+- Classe principal `Josias` com context manager
+- Automação DOM via Selenium com seletores amigáveis
+- Navegação, abas, esperas e interação com iframes
+- Visão computacional: OCR (Tesseract) e detecção de imagem (OpenCV)
+- Executor de tarefas com backtrack inteligente
+- Suporte a Chrome, Firefox e Edge
+- Extras opcionais `[vision]` e `[dev]`

josias-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Josias Automation
+
+Permission 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:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE 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.

josias-0.1.0/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: josias
+Version: 0.1.0
+Summary: Biblioteca Python de automação web com Selenium e visão computacional.
+Project-URL: Homepage, https://github.com/JosiasAz/josias
+Project-URL: Documentation, https://github.com/JosiasAz/josias#readme
+Project-URL: Repository, https://github.com/JosiasAz/josias
+Project-URL: Issues, https://github.com/JosiasAz/josias/issues
+Project-URL: Changelog, https://github.com/JosiasAz/josias/blob/main/CHANGELOG.md
+Author: Josias Automation
+License-Expression: MIT
+License-File: LICENSE
+Keywords: automation,computer-vision,josias,ocr,rpa,selenium,web
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: opencv-python-headless>=4.8.0
+Requires-Dist: pillow>=10.0.0
+Requires-Dist: selenium>=4.15.0
+Provides-Extra: dev
+Requires-Dist: build>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
+Requires-Dist: pytest>=7.4.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Requires-Dist: twine>=4.0.0; extra == 'dev'
+Provides-Extra: vision
+Requires-Dist: pytesseract>=0.3.10; extra == 'vision'
+Description-Content-Type: text/markdown
+
+# Josias
+
+Biblioteca Python para automação web com **Selenium** e **visão computacional** — simples, limpa e pronta para escalar.
+
+Parte do ecossistema **Josias**, uma plataforma completa de automação RPA.
+
+## Instalação
+
+```bash
+pip install josias
+
+# Com OCR (requer Tesseract instalado no sistema)
+pip install josias[vision]
+
+# Desenvolvimento local
+pip install -e ".[dev,vision]"
+```
+
+### Pré-requisitos
+
+- Python 3.10+
+- Google Chrome, Firefox ou Edge
+- [Tesseract OCR](https://github.com/UB-Mannheim/tesseract/wiki) — necessário apenas para recursos de OCR
+
+## Uso rápido
+
+```python
+from josias import Josias
+
+with Josias() as bot:
+    bot.open("https://example.com")
+
+    # DOM — seletores CSS simples
+    bot.click("#login")
+    bot.type("#email", "usuario@email.com")
+    bot.type("#password", "senha123", submit=True)
+
+    # Esperas
+    bot.wait_for("#dashboard")
+
+    # Visão computacional (OCR + imagem)
+    bot.click_text("Confirmar")
+    bot.click_image("assets/botao_ok.png")
+```
+
+## Seletores
+
+| Formato | Exemplo | Descrição |
+|---------|---------|-----------|
+| CSS (padrão) | `"#login"`, `".btn"` | Seletor CSS |
+| XPath | `"xpath://button"` | XPath explícito |
+| ID | `"id:username"` | Por atributo id |
+| Texto | `"text:Entrar"` | Por texto visível na página |
+
+## Configuração
+
+```python
+from josias import Josias, Config, VisionConfig
+from josias.types import Browser
+
+config = Config(
+    browser=Browser.CHROME,
+    headless=True,
+    window_size=(1920, 1080),
+    default_timeout=15.0,
+    vision=VisionConfig(
+        confidence_threshold=80.0,
+        tesseract_lang="por",
+    ),
+)
+
+with Josias(config) as bot:
+    bot.open("https://example.com")
+```
+
+## Tarefas com backtrack
+
+Execute sequências de ações com retry automático entre etapas:
+
+```python
+with Josias() as bot:
+    bot.open("https://app.exemplo.com")
+
+    bot.run([
+        {"text": "Login", "sendtext": "usuario", "backtrack": True},
+        {"text": "Senha", "sendtext": "123456", "backtrack": True},
+        {"image": "submit.png", "backtrack": True, "confidence": 0.9},
+    ])
+```
+
+## Arquitetura
+
+```
+src/josias/
+├── bot.py           # Classe principal
+├── config.py        # Configuração centralizada
+├── browser/         # Gerenciamento Selenium
+├── dom/             # Seletores e interação DOM
+├── vision/          # OCR e detecção de imagem
+├── actions/         # Mouse, teclado e tarefas
+└── waits.py         # Esperas explícitas
+```
+
+## Publicação no PyPI
+
+```bash
+python -m build
+python -m twine check dist/*
+python -m twine upload dist/*
+```
+
+Ou crie uma **Release** no GitHub — o workflow publica automaticamente via Trusted Publishing.
+
+## Roadmap
+
+- [x] Core Selenium com API simplificada
+- [x] Visão computacional (OCR + imagem)
+- [x] Executor de tarefas com backtrack
+- [ ] Orquestrador Josias
+- [ ] Plugins (Excel, AWS, e-mail)
+- [ ] CLI e deploy de bots
+
+## Licença
+
+MIT — veja [LICENSE](LICENSE).

josias-0.1.0/README.md

@@ -0,0 +1,125 @@
+# Josias
+
+Biblioteca Python para automação web com **Selenium** e **visão computacional** — simples, limpa e pronta para escalar.
+
+Parte do ecossistema **Josias**, uma plataforma completa de automação RPA.
+
+## Instalação
+
+```bash
+pip install josias
+
+# Com OCR (requer Tesseract instalado no sistema)
+pip install josias[vision]
+
+# Desenvolvimento local
+pip install -e ".[dev,vision]"
+```
+
+### Pré-requisitos
+
+- Python 3.10+
+- Google Chrome, Firefox ou Edge
+- [Tesseract OCR](https://github.com/UB-Mannheim/tesseract/wiki) — necessário apenas para recursos de OCR
+
+## Uso rápido
+
+```python
+from josias import Josias
+
+with Josias() as bot:
+    bot.open("https://example.com")
+
+    # DOM — seletores CSS simples
+    bot.click("#login")
+    bot.type("#email", "usuario@email.com")
+    bot.type("#password", "senha123", submit=True)
+
+    # Esperas
+    bot.wait_for("#dashboard")
+
+    # Visão computacional (OCR + imagem)
+    bot.click_text("Confirmar")
+    bot.click_image("assets/botao_ok.png")
+```
+
+## Seletores
+
+| Formato | Exemplo | Descrição |
+|---------|---------|-----------|
+| CSS (padrão) | `"#login"`, `".btn"` | Seletor CSS |
+| XPath | `"xpath://button"` | XPath explícito |
+| ID | `"id:username"` | Por atributo id |
+| Texto | `"text:Entrar"` | Por texto visível na página |
+
+## Configuração
+
+```python
+from josias import Josias, Config, VisionConfig
+from josias.types import Browser
+
+config = Config(
+    browser=Browser.CHROME,
+    headless=True,
+    window_size=(1920, 1080),
+    default_timeout=15.0,
+    vision=VisionConfig(
+        confidence_threshold=80.0,
+        tesseract_lang="por",
+    ),
+)
+
+with Josias(config) as bot:
+    bot.open("https://example.com")
+```
+
+## Tarefas com backtrack
+
+Execute sequências de ações com retry automático entre etapas:
+
+```python
+with Josias() as bot:
+    bot.open("https://app.exemplo.com")
+
+    bot.run([
+        {"text": "Login", "sendtext": "usuario", "backtrack": True},
+        {"text": "Senha", "sendtext": "123456", "backtrack": True},
+        {"image": "submit.png", "backtrack": True, "confidence": 0.9},
+    ])
+```
+
+## Arquitetura
+
+```
+src/josias/
+├── bot.py           # Classe principal
+├── config.py        # Configuração centralizada
+├── browser/         # Gerenciamento Selenium
+├── dom/             # Seletores e interação DOM
+├── vision/          # OCR e detecção de imagem
+├── actions/         # Mouse, teclado e tarefas
+└── waits.py         # Esperas explícitas
+```
+
+## Publicação no PyPI
+
+```bash
+python -m build
+python -m twine check dist/*
+python -m twine upload dist/*
+```
+
+Ou crie uma **Release** no GitHub — o workflow publica automaticamente via Trusted Publishing.
+
+## Roadmap
+
+- [x] Core Selenium com API simplificada
+- [x] Visão computacional (OCR + imagem)
+- [x] Executor de tarefas com backtrack
+- [ ] Orquestrador Josias
+- [ ] Plugins (Excel, AWS, e-mail)
+- [ ] CLI e deploy de bots
+
+## Licença
+
+MIT — veja [LICENSE](LICENSE).

josias-0.1.0/examples/01_hello_web.py

@@ -0,0 +1,23 @@
+"""Exemplo 1 — Automação web básica com DOM (Selenium)."""
+
+from josias import Josias
+
+
+def main() -> None:
+    with Josias() as bot:
+        bot.open("https://example.com")
+
+        # Verifica título da página
+        print(f"Título: {bot.title}")
+
+        # Interação via seletores CSS (padrão)
+        heading = bot.get_text("h1")
+        print(f"Cabeçalho: {heading}")
+
+        # Navegação
+        bot.open("https://example.com")
+        bot.wait(1)
+
+
+if __name__ == "__main__":
+    main()

josias-0.1.0/examples/02_dom_automation.py

@@ -0,0 +1,37 @@
+"""Exemplo 2 — Automação DOM completa (formulários, esperas, seletores)."""
+
+from josias import Config, Josias
+from josias.types import Browser
+
+
+def main() -> None:
+    config = Config(
+        browser=Browser.CHROME,
+        headless=False,
+        default_timeout=15.0,
+    )
+
+    with Josias(config) as bot:
+        bot.open("https://www.selenium.dev/selenium/web/web-form.html")
+
+        # Seletores CSS (padrão)
+        bot.type("#my-text-id", "Josias Automation")
+        bot.type("input[name='my-password']", "senha123")
+
+        # Dropdown
+        bot.click("select[name='my-select']")
+        bot.click("option[value='2']")
+
+        # Checkbox
+        bot.click("input[type='checkbox']")
+
+        # Submit
+        bot.click("button")
+
+        # Espera mensagem de sucesso
+        bot.wait_for("#message")
+        print(f"Resultado: {bot.get_text('#message')}")
+
+
+if __name__ == "__main__":
+    main()

josias-0.1.0/examples/03_vision_automation.py

@@ -0,0 +1,41 @@
+"""Exemplo 3 — Automação com visão computacional (OCR + imagem)."""
+
+from josias import Config, Josias, VisionConfig
+
+
+def main() -> None:
+    config = Config(
+        headless=False,
+        vision=VisionConfig(
+            confidence_threshold=75.0,
+            tesseract_lang="eng",
+        ),
+    )
+
+    with Josias(config) as bot:
+        bot.open("https://example.com")
+
+        # OCR — encontra e clica em texto visível na página
+        if bot.click_text("Learn more"):
+            print("Clicou em 'Learn more' via OCR")
+        else:
+            print("Texto não encontrado via OCR")
+
+        # Screenshot para debug
+        bot.screenshot("examples/output/example.png")
+        print("Screenshot salvo em examples/output/example.png")
+
+        # Lista de tarefas com backtrack
+        bot.start_task_session()
+        results = bot.run(
+            [
+                {"text": "Example", "backtrack": True, "delay": 1},
+                {"text": "Domain", "backtrack": True, "delay": 1},
+            ]
+        )
+        ok, total = bot.end_task_session()
+        print(f"Tarefas: {results} | Sessão: {ok}/{total}")
+
+
+if __name__ == "__main__":
+    main()

josias-0.1.0/pyproject.toml

@@ -0,0 +1,71 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "josias"
+version = "0.1.0"
+description = "Biblioteca Python de automação web com Selenium e visão computacional."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [{ name = "Josias Automation" }]
+keywords = ["automation", "selenium", "rpa", "web", "ocr", "computer-vision", "josias"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Testing",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "selenium>=4.15.0",
+    "pillow>=10.0.0",
+    "opencv-python-headless>=4.8.0",
+    "numpy>=1.24.0",
+]
+
+[project.optional-dependencies]
+vision = ["pytesseract>=0.3.10"]
+dev = [
+    "pytest>=7.4.0",
+    "pytest-cov>=4.1.0",
+    "ruff>=0.1.0",
+    "build>=1.0.0",
+    "twine>=4.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/JosiasAz/josias"
+Documentation = "https://github.com/JosiasAz/josias#readme"
+Repository = "https://github.com/JosiasAz/josias"
+Issues = "https://github.com/JosiasAz/josias/issues"
+Changelog = "https://github.com/JosiasAz/josias/blob/main/CHANGELOG.md"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/josias"]
+
+[tool.hatch.build.targets.sdist]
+only-include = [
+    "src/josias",
+    "examples",
+    "tests",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "pyproject.toml",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"

josias-0.1.0/src/josias/__init__.py

@@ -0,0 +1,40 @@
+"""
+Josias — Automação web com Selenium e visão computacional.
+
+Uso rápido::
+
+    from josias import Josias
+
+    with Josias() as bot:
+        bot.open("https://example.com")
+        bot.click("#login")
+        bot.type("#email", "user@email.com")
+        bot.click_text("Entrar")
+"""
+
+from .bot import Josias
+from .config import Config, VisionConfig
+from .exceptions import (
+    BrowserNotStartedError,
+    ElementNotFoundError,
+    JosiasError,
+    TaskExecutionError,
+    VisionNotAvailableError,
+)
+from .types import Browser, MatchResult, Region, SelectorType
+
+__version__ = "0.1.0"
+__all__ = [
+    "Josias",
+    "Config",
+    "VisionConfig",
+    "Browser",
+    "Region",
+    "MatchResult",
+    "SelectorType",
+    "JosiasError",
+    "BrowserNotStartedError",
+    "ElementNotFoundError",
+    "VisionNotAvailableError",
+    "TaskExecutionError",
+]

josias-0.1.0/src/josias/actions/__init__.py

@@ -0,0 +1,6 @@
+"""Ações de alto nível."""
+
+from .mouse import KeyboardActions, MouseActions
+from .tasks import TaskRunner
+
+__all__ = ["KeyboardActions", "MouseActions", "TaskRunner"]

josias-0.1.0/src/josias/actions/mouse.py

@@ -0,0 +1,105 @@
+"""Ações de mouse e teclado no navegador."""
+
+from __future__ import annotations
+
+from selenium.webdriver.common.action_chains import ActionChains
+from selenium.webdriver.common.by import By
+from selenium.webdriver.common.keys import Keys
+from selenium.webdriver.remote.webdriver import WebDriver
+
+
+class MouseActions:
+    """Cliques por coordenada na viewport do navegador."""
+
+    def __init__(self, driver: WebDriver) -> None:
+        self._driver = driver
+        self._x = 0
+        self._y = 0
+
+    def _move_to(self, x: int, y: int) -> None:
+        mx = x - self._x
+        my = y - self._y
+        self._x = x
+        self._y = y
+
+        scale = self._driver.execute_script("return window.devicePixelRatio") or 1
+        ActionChains(self._driver).move_by_offset(mx / scale, my / scale).perform()
+
+    def move_to(self, x: int, y: int) -> None:
+        self._move_to(x, y)
+
+    def click_at(
+        self,
+        x: int,
+        y: int,
+        *,
+        button: str = "left",
+        clicks: int = 1,
+    ) -> None:
+        self._move_to(x, y)
+        chain = ActionChains(self._driver)
+        for _ in range(clicks):
+            if button == "right":
+                chain.context_click()
+            elif button == "double":
+                chain.double_click()
+            else:
+                chain.click()
+        chain.perform()
+
+    def click_center(self, x: int, y: int, width: int, height: int, **kwargs) -> None:
+        cx = x + width // 2
+        cy = y + height // 2
+        self.click_at(cx, cy, **kwargs)
+
+    def reset_position(self) -> None:
+        self._x = 0
+        self._y = 0
+
+
+class KeyboardActions:
+    """Digitação e atalhos de teclado."""
+
+    def __init__(self, driver: WebDriver) -> None:
+        self._driver = driver
+
+    def type_text(self, text: str, *, interval: float = 0.0) -> None:
+        body = self._driver.find_element(By.TAG_NAME, "body")
+        for char in text:
+            body.send_keys(char)
+            if interval > 0:
+                import time
+
+                time.sleep(interval)
+
+    def send_keys(self, *keys) -> None:
+        body = self._driver.find_element(By.TAG_NAME, "body")
+        body.send_keys(*keys)
+
+    def shortcut(self, combo: str) -> None:
+        """Executa atalho como ``Ctrl+S`` ou ``Alt+Tab``."""
+        parts = [p.strip() for p in combo.split("+")]
+        modifiers = {
+            "ctrl": Keys.CONTROL,
+            "control": Keys.CONTROL,
+            "alt": Keys.ALT,
+            "shift": Keys.SHIFT,
+            "meta": Keys.META,
+            "cmd": Keys.META,
+        }
+        chain = ActionChains(self._driver)
+        pressed = []
+        for part in parts[:-1]:
+            key = modifiers.get(part.lower())
+            if key:
+                chain.key_down(key)
+                pressed.append(key)
+        last = parts[-1].lower()
+        if last in modifiers:
+            chain.key_down(modifiers[last])
+            pressed.append(modifiers[last])
+        else:
+            chain.send_keys(parts[-1])
+        for key in reversed(pressed):
+            chain.key_up(key)
+        chain.perform()