pyvizion 1.0.7

Biblioteca Python para automação de interface por imagem e texto

PyPI | Começar | Como funciona

O pyvizion é uma biblioteca Python: localiza um botão ou um texto na tela, clica e digita. Se o passo falhar, o backtrack refaz a ação anterior e tenta de novo.

Serve para aplicativos desktop que não expõem API: ERP, Oracle Forms, Delphi, Citrix. O alvo principal é o Windows; Linux e macOS funcionam quando o ambiente tem as mesmas dependências.

Os nomes e a ordem dos parâmetros seguem o bot-vision-suite 1.3.0. Quem já usa esses métodos troca o import; a busca na tela é implementação deste pacote.

from pyvizion import Vizion

vz = Vizion()
vz.click_image("menu.png", backtrack=True)
vz.click_text("Relatórios", backtrack=True)
vz.click_text("Confirmar", sendtext="{enter}")

A série publicada é a 1.0+. As versões 0.3.x no PyPI são outra API.

Começar

pip install pyvizion
python -m pyvizion doctor

Tesseract é obrigatório ao criar Vizion(). Sem ele a instância nem sobe (TesseractNotFoundError).

Idioma padrão do OCR: eng. Tela em português: Vizion({"tesseract_lang": "por"}) e o pacote por.

Como funciona

Você chama click_image("ok.png") ou click_text("Salvar"). A biblioteca tira um print, procura o alvo e clica no meio dele.

1. Tira o print: cerca de 5 ms, funciona com dois monitores.
2. Acha a imagem: você recorta o botão, salva numa pasta (imagens/ok.png) e passa o caminho. A biblioteca procura essa figura na tela. Funciona mesmo se o Windows estiver com a tela aumentada (125% ou 150%).
3. Acha o texto: Tesseract (inglês por padrão; tesseract_lang="por" se a tela for em português).
4. Clica e digita: no centro do alvo. use_virtual_mouse no Windows não mexe o cursor.
5. Se falhar: com backtrack=True, refaz o passo anterior. Também espera aparecer ou sumir.

Se o alvo não estiver na tela, devolve False ou None. Vale if not vz.click_text("OK"). Erro só se faltar Tesseract ou o PNG não existir.

O que melhorou

Os métodos são os mesmos do bot-vision-suite 1.3.0. O que mudou é o jeito de achar o alvo: mais rápido e mais estável com a tela aumentada e com mais de um monitor.

Os "5 ms" e o "6x" vêm do jeito de tirar o print e de ler só a área pedida, não de um teste oficial publicado.

Uso

Backtrack e esperas

vz = Vizion()
vz.click_image("menu.png", backtrack=True)
vz.click_text("Relatórios", backtrack=True)
vz.click_image("salvar.png", wait_until_found=True, wait_timeout=15)
vz.find_image("ampulheta.png", wait_until_disappears=True, wait_timeout=60)
vz.click_image("ok.png", wait_until_disappears=True, wait_timeout=10)

wait_until_disappears no find_* devolve a caixa se o alvo sumiu, None se ainda estiver visível. No click_*, o clique já valeu: devolve True mesmo se o alvo continuar na tela.

Sessão

vz.start_task_session()
vz.click_image("button1.png", backtrack=True)
vz.click_text("Clientes", backtrack=True)
ok, total = vz.end_task_session()

Lista de tarefas

from pyvizion import execute_tasks

execute_tasks([
    {"image": "button.png", "region": (100, 100, 200, 50), "backtrack": True},
    {"text": "Login", "sendtext": "usuario123{tab}senha{enter}"},
    {"type": "relative_image", "anchor_image": "aviso.png", "target_image": "ok.png"},
    {"type": "keyboard_command", "command": "Ctrl+S"},
])

Métodos

Assinaturas posicionais iguais às do bot-vision-suite 1.3.0.

Extras: wait_for_image, wait_for_text, wait_until_gone, image_exists, text_exists, find_all_images, click_any, find_any, read_text, focus_window, wait_window, window_region, list_windows, press, hotkey, scroll, drag, screenshot, click_image_near_text.

Também como funções: from pyvizion import click_image, find_text, execute_tasks, limpar_texto.

Parâmetros que importam

• region=(x, y, largura, altura): use sempre que puder. vz.window_region("Título") devolve a janela.
• specific=False: tenta a região e depois a tela, em várias escalas.
• mouse_button: "left", "right", "double", "move_to".
• filter_type: "letters", "numbers", "both". occurrence=2 é a segunda na ordem de leitura.
• wait_timeout: segundos da espera (padrão da config: 30).

click_* / find_* não levantam se o alvo sumiu. Ambiente quebrado sim: TesseractNotFoundError no Vizion(), ImageFileError se o PNG não existe. As classes ImageNotFoundError e TextNotFoundError existem para quem quiser capturar por nome.

Campos (sendtext)

Texto digitado logo após o clique. {chave} é tecla.

vz.click_text("Usuário", sendtext="admin{tab}senha123{enter}")

Macros: {enter} {tab} {esc} {del} {backspace} setas {f1} a {f12} {ctrl}a {ctrl+shift+s} {tab*3} {wait 1.5} {{ }}.

Citrix/RDP que não cola: Vizion({"typing_mode": "type"}).

Tipos de tarefa

tasks = [
    {"type": "focus_window", "title": "Oracle Applications"},
    {"type": "wait_image", "image": "tela.png", "timeout": 30},
    {"text": "Cliente", "sendtext": "12345{enter}", "required": True},
    {"type": "wait_image", "image": "ampulheta.png", "gone": True, "timeout": 60},
    {"image": "popup.png", "optional": True, "sendtext": "{enter}"},
]

Tipos: imagem, texto, relative_image, click, type_text, keyboard_command, wait_image / wait_text, extract_text, wait, focus_window, scroll.

Chaves comuns: mouse_button, delay, sendtext, backtrack, max_attempts, wait_until_found, wait_until_disappears, wait_timeout, optional, required, show_overlay.

Configuração

vz = Vizion({
    "tesseract_lang": "eng",
    "image_folders": ["./imagens"],
    "use_virtual_mouse": False,
    "show_overlay": False,
})
vz.config.set("show_overlay", True)
vz = Vizion("pyvizion.json")

Demais chaves (escalas, OCR, overlay, backtrack): veja src/pyvizion/config.py.

Linha de comando

python -m pyvizion doctor
python -m pyvizion screenshot tela.png
python -m pyvizion position
python -m pyvizion pick
python -m pyvizion ocr 100 200 300 40

Prática

1. Passe region (ou window_region) sempre que souber a área.
2. Recorte PNG pequeno e único: o ícone, não o formulário.
3. Prefira wait_until_gone a delay fixo.
4. Comece com focus_window("Título").
5. Para parar: mouse no canto superior esquerdo.

Desenvolvimento

pip install -e .[dev]
pytest

O site estático fica em docs/. Para ver localmente:

python -m http.server 8080 --directory docs

Licença

MIT. Texto em LICENSE.

Copyright © 2026 Josias Azevedo da Silva.

Os métodos públicos acompanham o bot-vision-suite (MIT). São pacotes distintos no PyPI.