pyvizion 0.3.0__tar.gz

pyvizion-0.3.0/.gitignore

@@ -0,0 +1,39 @@
+# Byte-compiled / cache
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.tox/
+.nox/
+
+# Virtualenvs and packaging
+.venv/
+venv/
+env/
+*.egg-info/
+.eggs/
+dist/
+build/
+
+# Editors / OS
+.idea/
+.vscode/
+*.swp
+Thumbs.db
+.DS_Store
+
+# Secrets and local env
+.env
+.env.*
+!.env.example
+
+# Screenshots / debug dumps
+*.png
+*.jpg
+!tests/fixtures/**

pyvizion-0.3.0/LICENSE

@@ -0,0 +1,5 @@
+Copyright (c) 2026 Josias Azevedo da Silva. All rights reserved.
+
+This software is proprietary and confidential. Unauthorized copying,
+distribution, modification, or use of this software, via any medium,
+is strictly prohibited without prior written permission.

pyvizion-0.3.0/PKG-INFO

@@ -0,0 +1,166 @@
+Metadata-Version: 2.5
+Name: pyvizion
+Version: 0.3.0
+Summary: RPA híbrido: Selenium no navegador e visão/OCR na tela, um só pipeline.
+Author: Josias Azevedo da Silva
+License: Copyright (c) 2026 Josias Azevedo da Silva. All rights reserved.
+        
+        This software is proprietary and confidential. Unauthorized copying,
+        distribution, modification, or use of this software, via any medium,
+        is strictly prohibited without prior written permission.
+License-File: LICENSE
+Keywords: browser-automation,computer-vision,desktop-automation,ocr,opencv,rpa,selenium,template-matching
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: Other/Proprietary License
+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 :: Scientific/Engineering :: Image Recognition
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: easyocr>=1.7.1
+Requires-Dist: mss>=9.0.0
+Requires-Dist: numpy>=1.24
+Requires-Dist: opencv-python-headless>=4.8
+Requires-Dist: pillow>=10.0.0
+Requires-Dist: psutil>=5.9.0
+Requires-Dist: pyautogui>=0.9.54
+Requires-Dist: pyperclip>=1.8.2
+Requires-Dist: pytesseract>=0.3.10
+Requires-Dist: pywin32>=306; sys_platform == 'win32'
+Requires-Dist: pywinauto>=0.6.8; sys_platform == 'win32'
+Requires-Dist: rapidfuzz>=3.0
+Requires-Dist: selenium>=4.15
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Vizion
+
+RPA em Python para **página no navegador** e **tela do Windows**. Você aponta o alvo — recorte PNG, palavra visível ou seletor Selenium — e o Vizion tenta achar: primeiro no DOM, depois por imagem, depois por OCR.
+
+```python
+from vizion import Bot
+
+bot = Bot()                       # área de trabalho
+# bot = Bot(webdriver.Chrome())   # Chrome já aberto
+
+bot.click(image="ok.png", timeout=10)
+bot.click(text="Salvar", sendtext="{enter}")
+bot.click(anchor="linha.png", target="editar.png")
+bot.wait(image="spinner.png", timeout=30, gone=True)
+bot.keyboard("Ctrl+S")
+print(bot.result())
+```
+
+Código em inglês (`click`, `timeout`, `image`). Só este README está em português.
+
+## Instalação
+
+```bash
+pip install pyvizion
+```
+
+O pacote no PyPI chama-se **pyvizion**; no código você continua com `from vizion import Bot`.
+
+Sobe Selenium, OpenCV, EasyOCR, Tesseract (wrapper), PyAutoGUI, mss e, no Windows, pywin32. O executável do Tesseract no sistema continua sendo um requisito do SO se você for usar esse backend.
+
+## Como o alvo é encontrado
+
+No **navegador** a ordem é:
+
+1. seletor DOM (`by` + `value`)
+2. texto visível no DOM
+3. iframe / shadow DOM
+4. recorte OpenCV (várias escalas, HiDPI)
+5. bordas Canny (tema claro/escuro)
+6. ORB + homografia
+7. OCR (EasyOCR, com Tesseract de reserva)
+8. scroll da página e nova passada
+
+No **desktop** os passos de DOM somem: recorte → Canny → ORB → OCR.
+
+O clique no browser usa coordenada CSS (PNG vs `innerWidth`), não pixel cru da screenshot. No desktop, pixel físico do `mss` vira coordenada lógica do SO.
+
+## Navegador
+
+```python
+from selenium import webdriver
+from selenium.webdriver.common.by import By
+from vizion import Vizion, VizionConfig
+
+pagina = Vizion.web(
+    webdriver.Chrome(),
+    config=VizionConfig(default_timeout=15, show_overlay=True),
+)
+pagina.get("https://intranet")
+pagina.find_and_click(by=By.ID, value="user", template="user.png", text="Usuário")
+pagina.wait_url("/home")
+```
+
+`find_and_click` aceita seletor, recorte e texto **ao mesmo tempo**: se o DOM falhar, a visão e o OCR entram.
+
+## Área de trabalho
+
+```python
+from vizion import Vizion, VizionConfig
+
+tela = Vizion.desktop(config=VizionConfig(use_virtual_mouse=True))
+tela.register_image("ok", "ok.png")
+tela.click_image("ok")
+tela.click_text("Confirmar")
+tela.keyboard("Ctrl+S")
+```
+
+`use_virtual_mouse=True` (Windows) clica sem deixar o cursor no alvo.
+
+Do desktop dá para abrir o Chrome e continuar no mesmo catálogo de imagens:
+
+```python
+tela = Vizion.desktop()
+pagina = tela.open_browser("https://intranet")
+pagina.find_and_click(by="id", value="user")
+tela.click_image("ok.png")
+```
+
+## Vários alvos iguais
+
+Quando o mesmo botão aparece várias vezes, passe uma âncora única e o recorte do botão:
+
+```python
+bot.click(anchor="aviso.png", target="ok.png")
+# ou
+tela.click_relative("aviso.png", "ok.png", max_distance=200)
+```
+
+## Lote de passos
+
+```python
+bot.run([
+    {"image": "menu.png", "timeout": 8},
+    {"anchor": "linha.png", "target": "editar.png"},
+    {"text": "Salvar", "sendtext": "{enter}"},
+    {"type": "keyboard", "command": "Ctrl+S"},
+])
+```
+
+O motor avançado (`Vizion.web` / `Vizion.desktop`) expõe o mesmo lote em `execute_tasks`.
+
+## Ajuste
+
+`VizionConfig` controla timeout, limiar OpenCV, overlay, idiomas OCR, mouse virtual. `print(doctor())` lista o que está instalado.
+
+No IDE, `help(VizionDriver.find_and_click)` mostra o contrato completo (seletor, recorte, OCR, overlay).
+
+## Licença
+
+Software proprietário. Ver `LICENSE`.
+
+Desenvolvido por Josias Azevedo da Silva.

pyvizion-0.3.0/README.md

@@ -0,0 +1,122 @@
+# Vizion
+
+RPA em Python para **página no navegador** e **tela do Windows**. Você aponta o alvo — recorte PNG, palavra visível ou seletor Selenium — e o Vizion tenta achar: primeiro no DOM, depois por imagem, depois por OCR.
+
+```python
+from vizion import Bot
+
+bot = Bot()                       # área de trabalho
+# bot = Bot(webdriver.Chrome())   # Chrome já aberto
+
+bot.click(image="ok.png", timeout=10)
+bot.click(text="Salvar", sendtext="{enter}")
+bot.click(anchor="linha.png", target="editar.png")
+bot.wait(image="spinner.png", timeout=30, gone=True)
+bot.keyboard("Ctrl+S")
+print(bot.result())
+```
+
+Código em inglês (`click`, `timeout`, `image`). Só este README está em português.
+
+## Instalação
+
+```bash
+pip install pyvizion
+```
+
+O pacote no PyPI chama-se **pyvizion**; no código você continua com `from vizion import Bot`.
+
+Sobe Selenium, OpenCV, EasyOCR, Tesseract (wrapper), PyAutoGUI, mss e, no Windows, pywin32. O executável do Tesseract no sistema continua sendo um requisito do SO se você for usar esse backend.
+
+## Como o alvo é encontrado
+
+No **navegador** a ordem é:
+
+1. seletor DOM (`by` + `value`)
+2. texto visível no DOM
+3. iframe / shadow DOM
+4. recorte OpenCV (várias escalas, HiDPI)
+5. bordas Canny (tema claro/escuro)
+6. ORB + homografia
+7. OCR (EasyOCR, com Tesseract de reserva)
+8. scroll da página e nova passada
+
+No **desktop** os passos de DOM somem: recorte → Canny → ORB → OCR.
+
+O clique no browser usa coordenada CSS (PNG vs `innerWidth`), não pixel cru da screenshot. No desktop, pixel físico do `mss` vira coordenada lógica do SO.
+
+## Navegador
+
+```python
+from selenium import webdriver
+from selenium.webdriver.common.by import By
+from vizion import Vizion, VizionConfig
+
+pagina = Vizion.web(
+    webdriver.Chrome(),
+    config=VizionConfig(default_timeout=15, show_overlay=True),
+)
+pagina.get("https://intranet")
+pagina.find_and_click(by=By.ID, value="user", template="user.png", text="Usuário")
+pagina.wait_url("/home")
+```
+
+`find_and_click` aceita seletor, recorte e texto **ao mesmo tempo**: se o DOM falhar, a visão e o OCR entram.
+
+## Área de trabalho
+
+```python
+from vizion import Vizion, VizionConfig
+
+tela = Vizion.desktop(config=VizionConfig(use_virtual_mouse=True))
+tela.register_image("ok", "ok.png")
+tela.click_image("ok")
+tela.click_text("Confirmar")
+tela.keyboard("Ctrl+S")
+```
+
+`use_virtual_mouse=True` (Windows) clica sem deixar o cursor no alvo.
+
+Do desktop dá para abrir o Chrome e continuar no mesmo catálogo de imagens:
+
+```python
+tela = Vizion.desktop()
+pagina = tela.open_browser("https://intranet")
+pagina.find_and_click(by="id", value="user")
+tela.click_image("ok.png")
+```
+
+## Vários alvos iguais
+
+Quando o mesmo botão aparece várias vezes, passe uma âncora única e o recorte do botão:
+
+```python
+bot.click(anchor="aviso.png", target="ok.png")
+# ou
+tela.click_relative("aviso.png", "ok.png", max_distance=200)
+```
+
+## Lote de passos
+
+```python
+bot.run([
+    {"image": "menu.png", "timeout": 8},
+    {"anchor": "linha.png", "target": "editar.png"},
+    {"text": "Salvar", "sendtext": "{enter}"},
+    {"type": "keyboard", "command": "Ctrl+S"},
+])
+```
+
+O motor avançado (`Vizion.web` / `Vizion.desktop`) expõe o mesmo lote em `execute_tasks`.
+
+## Ajuste
+
+`VizionConfig` controla timeout, limiar OpenCV, overlay, idiomas OCR, mouse virtual. `print(doctor())` lista o que está instalado.
+
+No IDE, `help(VizionDriver.find_and_click)` mostra o contrato completo (seletor, recorte, OCR, overlay).
+
+## Licença
+
+Software proprietário. Ver `LICENSE`.
+
+Desenvolvido por Josias Azevedo da Silva.

pyvizion-0.3.0/pyproject.toml

@@ -0,0 +1,91 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pyvizion"
+version = "0.3.0"
+description = "RPA híbrido: Selenium no navegador e visão/OCR na tela, um só pipeline."
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.10"
+authors = [
+    { name = "Josias Azevedo da Silva" },
+]
+keywords = [
+    "rpa",
+    "selenium",
+    "opencv",
+    "ocr",
+    "computer-vision",
+    "browser-automation",
+    "desktop-automation",
+    "template-matching",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: Other/Proprietary License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Scientific/Engineering :: Image Recognition",
+    "Typing :: Typed",
+]
+dependencies = [
+    "selenium>=4.15",
+    "opencv-python-headless>=4.8",
+    "numpy>=1.24",
+    "rapidfuzz>=3.0",
+    "easyocr>=1.7.1",
+    "pytesseract>=0.3.10",
+    "pyautogui>=0.9.54",
+    "mss>=9.0.0",
+    "Pillow>=10.0.0",
+    "pyperclip>=1.8.2",
+    "psutil>=5.9.0",
+    "pywin32>=306; sys_platform == 'win32'",
+    "pywinauto>=0.6.8; sys_platform == 'win32'",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+    "ruff>=0.5",
+    "mypy>=1.8",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/vizion"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/src",
+    "/tests",
+    "/README.md",
+    "/LICENSE",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+addopts = "-q --strict-markers"
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+ignore = ["SIM105"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+packages = ["vizion"]
+mypy_path = "src"

pyvizion-0.3.0/src/vizion/__init__.py

@@ -0,0 +1,178 @@
+"""Vizion — RPA híbrido: navegador (Selenium + visão + OCR) e desktop.
+
+Instalação::
+
+    pip install pyvizion
+
+O ``Bot`` escolhe o motor sozinho. Sem WebDriver é a tela; com Chrome
+é a página. Informe recorte, palavra ou os dois::
+
+    from vizion import Bot
+
+    bot = Bot()
+    bot.click(image="ok.png", timeout=10)
+    bot.click(text="Salvar", sendtext="{enter}")
+    bot.click(anchor="linha.png", target="editar.png")
+    bot.keyboard("Ctrl+S")
+
+API dos motores (``find_and_click`` tenta DOM, depois imagem, depois OCR)::
+
+    from selenium import webdriver
+    from vizion import Vizion, VizionConfig, doctor
+
+    pagina = Vizion.web(webdriver.Chrome())
+    pagina.get("https://intranet")
+    pagina.find_and_click(by="id", value="user", template="user.png", text="Usuário")
+
+    tela = Vizion.desktop()
+    tela.click_image("ok.png")
+    pagina = tela.open_browser("https://intranet")
+
+``help(VizionDriver.find_and_click)`` e ``print(doctor())`` no REPL.
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+from typing import Any
+
+from vizion.bot import Bot
+from vizion.core.config import DEFAULT_STRATEGIES, DESKTOP_STRATEGIES, VizionConfig
+from vizion.core.doctor import doctor
+from vizion.core.driver import VizionDriver
+from vizion.core.element import VizionElement
+from vizion.core.exceptions import (
+    VizionConfigError,
+    VizionCoordinateError,
+    VizionElementNotFoundException,
+    VizionError,
+    VizionImageError,
+    VizionOCRError,
+    VizionTimeoutError,
+)
+from vizion.core.tasks import Task
+from vizion.core.types import BoundingBox, MatchResult, Point, ViewportMetrics
+from vizion.desktop import VizionDesktop
+from vizion.ocr.engine import OCREngine
+from vizion.vision.matcher import TemplateMatcher
+from vizion.web import VizionWeb
+
+try:
+    __version__ = version("vizion")
+except PackageNotFoundError:  # pragma: no cover - árvore local sem instalação
+    __version__ = "0.3.0"
+
+
+class Vizion:
+    """Abre o motor web ou o de desktop.
+
+    :meth:`web` envolve um ``WebDriver``. :meth:`desktop` captura a tela.
+    Os dois respondem a ``find_and_click``. :meth:`bot` é o vocabulário
+    curto (``click``, ``wait``, ``keyboard``).
+
+    Examples
+    --------
+    >>> from selenium import webdriver
+    >>> from vizion import Vizion
+    >>> pagina = Vizion.web(webdriver.Chrome())
+    >>> pagina.get("https://example.com")
+    >>> pagina.click_text("More information")
+    >>> tela = Vizion.bot()
+    >>> tela.click(image="ok.png", timeout=8)
+    """
+
+    @staticmethod
+    def web(driver: Any, **kwargs: Any) -> VizionDriver:
+        """Envolve um Selenium WebDriver no motor híbrido de browser.
+
+        Parameters
+        ----------
+        driver :
+            Instância já criada (``webdriver.Chrome()``, Firefox, Edge…).
+        config :
+            :class:`~vizion.core.config.VizionConfig` opcional.
+        matcher, ocr, catalog :
+            Substitutos injetáveis (testes ou motores customizados).
+
+        Returns
+        -------
+        VizionDriver
+            Proxy do WebDriver: ``web.current_url`` continua funcionando.
+
+        Examples
+        --------
+        >>> from selenium import webdriver
+        >>> from selenium.webdriver.common.by import By
+        >>> from vizion import Vizion
+        >>> bot = Vizion.web(webdriver.Chrome())
+        >>> bot.get("https://example.com")
+        >>> bot.find_and_click(by=By.TAG_NAME, value="a", text="More")
+        """
+        return VizionDriver(driver, **kwargs)
+
+    @staticmethod
+    def desktop(**kwargs: Any) -> VizionDesktop:
+        """Abre o motor de desktop (captura de tela + mouse/teclado).
+
+        Parameters
+        ----------
+        config :
+            :class:`~vizion.core.config.VizionConfig`. No desktop as
+            estratégias DOM são ignoradas automaticamente.
+        grab, controller :
+            Injeção para testes (não usa mouse/tela reais).
+        catalog :
+            :class:`~vizion.core.catalog.ImageCatalog` compartilhado.
+
+        Examples
+        --------
+        >>> from vizion import Vizion, VizionConfig
+        >>> bot = Vizion.desktop(config=VizionConfig(show_overlay=True))
+        >>> bot.register_image("ok", "assets/ok.png")
+        >>> bot.start_session()
+        >>> bot.click_image("ok", backtrack=True)
+        >>> print(bot.end_session())
+        """
+        return VizionDesktop(**kwargs)
+
+    @staticmethod
+    def bot(driver: Any | None = None, **kwargs: Any) -> Bot:
+        """Automação com vocabulário mínimo (timeout, image, âncora, alvo).
+
+        Sem ``driver`` → desktop. Com WebDriver → browser. Sessão e
+        backtrack ligam sozinhos.
+
+        >>> bot = Vizion.bot()
+        >>> bot.click(image="salvar.png", timeout=10)
+        >>> bot.click(anchor="aviso.png", target="ok.png")
+        """
+        return Bot(driver, **kwargs)
+
+
+__all__ = [
+    "DEFAULT_STRATEGIES",
+    "DESKTOP_STRATEGIES",
+    "Bot",
+    "BoundingBox",
+    "MatchResult",
+    "OCREngine",
+    "Point",
+    "Task",
+    "TemplateMatcher",
+    "ViewportMetrics",
+    "Vizion",
+    "VizionConfig",
+    "VizionConfigError",
+    "VizionCoordinateError",
+    "VizionDesktop",
+    "VizionDriver",
+    "VizionElement",
+    "VizionElementNotFoundException",
+    "VizionError",
+    "VizionImageError",
+    "VizionOCRError",
+    "VizionTimeoutError",
+    "VizionWeb",
+    "__version__",
+    "doctor",
+]