Josias 🤖

Automatize tarefas repetitivas no computador com Python.

1. Conheça o Josias

O Josias funciona como um assistente virtual: ele olha para a tela, encontra botões e textos, clica, digita e também trabalha em páginas da internet. Você controla tudo pelo mesmo robô, sem precisar aprender uma ferramenta diferente para cada tipo de tarefa.

Com ele, você pode:

• clicar em uma imagem salva, como a foto de um botão;
• encontrar e clicar em palavras usando OCR;
• digitar textos e usar atalhos do teclado;
• abrir sites, preencher campos e clicar em elementos da página;
• tentar novamente quando uma tela demora para carregar.

Instalação

Instale o Josias com:

pip install -U josias

Para o robô ler textos na tela, instale também o Tesseract OCR:

• Windows: use o instalador do UB-Mannheim.
• Ubuntu/Debian: sudo apt install tesseract-ocr tesseract-ocr-por
• macOS: brew install tesseract

O Tesseract só é procurado quando você usa uma função de texto. Se o seu robô apenas clicar em imagens ou trabalhar na internet, ele não precisa esperar pelo OCR ao iniciar.

2. O jeito moderno de usar

Crie o robô uma vez e use a mesma variável durante todo o trabalho:

from josias import ActionOptions, Josias

bot = Josias()

try:
    # Procura a imagem na tela e clica nela.
    bot.click_image("botao.png")

    # Lê a tela, encontra o texto e clica.
    bot.click_text("Confirmar", send="Pronto!")

    # A internet liga sozinha aqui!
    bot.web.open("https://google.com")
    bot.web.click("#entrar")
finally:
    bot.close()

O comando bot.close() fecha o navegador e limpa os arquivos temporários. Colocá-lo no finally garante a limpeza mesmo quando alguma etapa dá erro.

A parte Web acorda sozinha

Você não precisa criar outro objeto para usar a internet. Quando encontra bot.web, o Josias prepara o navegador naquele momento:

bot.web.open("https://pypi.org")
bot.web.type_text("input[name='q']", "Josias")
bot.web.click("button[type='submit']")

nome = bot.web.get_text(".package-snippet__name")
print(nome)

Se o seu robô nunca usar .web, essa parte não será carregada. Isso deixa o início mais rápido.

3. Três modos de trabalho prontos

Você pode usar Josias() normalmente ou escolher um modo já preparado. Esses modos economizam tempo porque as escolhas mais comuns já vêm prontas.

Modo Detetive (ou Teste)

bot = Josias.debug()

Bom para criar e testar o robô. Ele mostra um quadrado vermelho onde pretende clicar, conta no terminal tudo o que está fazendo e guarda imagens das tentativas de leitura.

Modo Turbo (ou Rápido)

bot = Josias.fast()

Bom para tarefas simples e telas rápidas. Ele não perde tempo esperando entre as ações, tenta poucas vezes e não mostra caixas de ajuda na tela.

Modo Insistente (ou Seguro)

bot = Josias.robust()

Bom para sistemas lentos ou instáveis. Ele espera mais, tenta várias vezes e usa o recurso de voltar um passo quando algo não aparece.

4. Cliques inteligentes e configurações extras

Os comandos mais usados são curtos:

bot.click_image("imagens/salvar.png")
bot.click_text("Enviar")

Também é possível clicar em um campo e digitar logo em seguida:

bot.click_text("Pesquisar", send="relatório mensal{enter}")

Quando um botão precisa de cuidado especial, use ActionOptions. Pense nessa classe como um bilhete com instruções extras para aquela ação:

from josias import ActionOptions

opcoes = ActionOptions(
    confidence=0.80,  # aceita uma imagem com pelo menos 80% de semelhança
    retries=5,        # tenta até 5 vezes
    timeout=20,       # espera por até 20 segundos
    wait="found",     # espera o botão aparecer
    overlay=True,     # mostra onde vai clicar
)

bot.click_image("imagens/botao_dificil.png", options=opcoes)

Para texto, a confiança usa uma escala de 0 a 100:

bot.click_text(
    "Finalizar pedido",
    options=ActionOptions(
        confidence=75,
        timeout=30,
        retries=4,
        backtrack=True,
    ),
)

As opções disponíveis são:

• confidence: quanto a imagem ou o texto precisa se parecer com o esperado;
• retries: quantas vezes o robô tenta;
• timeout: quantos segundos ele pode esperar;
• delay: pausa antes da ação;
• button: botão do mouse, como "left", "right" ou "double";
• backtrack: permite voltar um passo quando a ação falha;
• overlay: mostra ou esconde a caixa de clique;
• wait: use "found" para esperar aparecer ou "disappears" para esperar sumir;
• specific: faz uma procura mais exata pela imagem;
• filter_type: procura letras, números ou os dois durante a leitura.

5. Se você usava os comandos antigos

O código antigo ainda funciona:

bot.click_image("botao.png", confidence=0.8)

O Josias transforma esse comando para o novo formato e continua o trabalho. Ele também gera um DeprecationWarning, que alguns terminais e editores mostram como um alerta amarelo. Esse aviso não significa que o robô parou; ele apenas pede que você atualize o código quando puder.

O novo jeito é:

bot.click_image(
    "botao.png",
    options=ActionOptions(confidence=0.8),
)

Esse apoio aos comandos antigos existe para facilitar a mudança. Em uma versão futura, eles poderão ser removidos.

6. Como o robô enxerga

Quando você pede click_text("Confirmar"), o Josias trabalha como uma pessoa tentando ler uma placa difícil:

1. tira uma foto da parte da tela onde vai procurar;
2. olha essa foto por 19 lentes diferentes;
3. uma lente aumenta o contraste, outra clareia, outra inverte as cores e assim por diante;
4. envia cada versão ao Tesseract até encontrar o texto;
5. calcula onde o texto está e clica naquele ponto.

Isso ajuda em telas com letras pequenas, fundos coloridos e pouco contraste.

No Modo Detetive, essas fotos são guardadas na pasta debug_ocr. Assim, quando uma leitura falhar, você pode abrir a pasta e ver exatamente o que o robô tentou ler.

Você também pode escolher outra pasta:

bot = Josias.debug(debug_ocr_dir="minhas_tentativas_ocr")

7. Voltar um passo quando algo falha

Imagine estas três etapas:

1. clicar em Menu;
2. clicar em Relatórios;
3. clicar em Gerar PDF.

Se a terceira etapa falhar porque a tela ainda não carregou, o Josias pode voltar à segunda, clicar novamente em Relatórios e depois tentar Gerar PDF mais uma vez. É como um assistente humano que refaz o último passo antes de desistir.

Esse recurso faz sentido quando há uma sequência, pois o robô precisa ter um passo anterior ao qual voltar. Passe as tarefas em ordem e marque com "backtrack": True a etapa que pode precisar dessa ajuda:

tarefas = [
    {
        "type": "click_text",
        "text": "Menu",
        "region": (0, 0, 1920, 1080),
    },
    {
        "type": "click_text",
        "text": "Relatórios",
        "region": (0, 0, 1920, 1080),
    },
    {
        "type": "click_text",
        "text": "Gerar PDF",
        "region": (0, 0, 1920, 1080),
        "backtrack": True,
    },
]

resultados = bot.execute_tasks(tarefas)

O Josias tenta voltar para a tarefa anterior até duas vezes antes de seguir em frente. Cada resultado informa se a etapa deu certo.

8. Teclado e atalhos

Além dos cliques, o robô pode digitar e usar atalhos:

bot.type_text("Relatório concluído", interval=0.05)
bot.keyboard_command("Ctrl+S")

Também existem comandos especiais dentro do texto:

bot.type_text("{ctrl}a{del}novo nome.txt{enter}")

Nesse exemplo, o robô seleciona tudo, apaga, escreve o novo nome e pressiona Enter.

9. Uso rápido sem criar uma variável

Para scripts pequenos, existem funções prontas:

from josias import ActionOptions, click_image, click_text, close_shared_bot

click_image("imagens/abrir.png")
click_text(
    "Continuar",
    options=ActionOptions(timeout=15, wait="found"),
)

close_shared_bot()

Essas funções compartilham o mesmo robô com segurança, inclusive quando seu programa trabalha com várias threads.

Resumo

from josias import ActionOptions, Josias

bot = Josias.debug()

try:
    bot.click_image("imagens/iniciar.png")
    bot.click_text(
        "Confirmar",
        options=ActionOptions(timeout=15, retries=3, wait="found"),
    )
    bot.web.open("https://exemplo.com")
finally:
    bot.close()

• Comece com Josias.debug() enquanto estiver criando o robô.
• Troque para Josias.fast() quando a tela for rápida e previsível.
• Use Josias.robust() em sistemas lentos.
• Coloque ajustes especiais dentro de ActionOptions.
• Chame bot.close() ao terminar.

Licença

Josias é distribuído sob a licença MIT.