Metadata-Version: 2.4
Name: josias
Version: 0.4.0
Summary: Biblioteca Python avançada para automação de interface gráfica com OCR e processamento de imagem avançado
Author: Josias Azevedo da Silva
License: MIT
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyAutoGUI>=0.9.54
Requires-Dist: pytesseract>=0.3.13
Requires-Dist: opencv-python>=4.9.0
Requires-Dist: Pillow>=10.0.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: pyperclip>=1.8.2
Requires-Dist: PyYAML>=6.0
Requires-Dist: selenium>=4.10.0
Requires-Dist: psutil>=5.9.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Dynamic: license-file

# 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:

```bash
pip install -U josias
```

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

- **Windows:** use o instalador do
  [UB-Mannheim](https://github.com/UB-Mannheim/tesseract/wiki).
- **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:

```python
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:

```python
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)

```python
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)

```python
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)

```python
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:

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

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

```python
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:

```python
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:

```python
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:

```python
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 é:

```python
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:

```python
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:

```python
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:

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

Também existem comandos especiais dentro do texto:

```python
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:

```python
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

```python
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.
