Metadata-Version: 2.4
Name: dominio-net
Version: 0.2.0
Summary: Automacao da interface do sistema Dominio por meio do pywinauto
Classifier: Development Status :: 3 - Alpha
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: pywinauto<0.7,>=0.6.9
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"

# dominio-net

Biblioteca Python para automatizar operações básicas da interface do sistema
Domínio no Windows. A implementação usa o backend UI Automation do
[`pywinauto`](https://pywinauto.readthedocs.io/) e expõe as seguintes operações:

- `launch_app`
- `perform_login`
- `get_main_window_after_login`
- `switch_module`
- `switch_company`
- `find_windows`

## Requisitos

- Windows com o sistema Domínio instalado;
- Python 3.10 ou superior;
- sessão gráfica desbloqueada durante a automação;
- permissão para executar o `contabil.exe` e interagir com suas janelas.

## Instalação

### Instalação pelo wheel (recomendada)

Baixe o arquivo `.whl` da versão desejada na página **Releases** do
repositório. Para a versão atual, o arquivo é:

```text
dominio_net-0.2.0-py3-none-any.whl
```

No projeto que utilizará a biblioteca, crie um ambiente virtual novo:

```powershell
cd "C:\caminho\do\seu-projeto"
py -m venv .venv
```

Instale o wheel usando o Python desse ambiente. Ajuste o caminho conforme o
local onde o arquivo foi baixado:

```powershell
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install "C:\Users\SEU_USUARIO\Downloads\dominio_net-0.2.0-py3-none-any.whl"
```

Confirme a instalação e a versão:

```powershell
.\.venv\Scripts\python.exe -c "import dominio_net; print(dominio_net.__version__)"
```

Resultado esperado:

```text
0.2.0
```

Também é possível validar os imports públicos:

```powershell
.\.venv\Scripts\python.exe -c "from dominio_net import launch_app, perform_login, get_main_window_after_login; print('Importação funcionando')"
```

No VS Code, execute `Python: Select Interpreter` pela paleta de comandos e
selecione:

```text
<pasta-do-projeto>\.venv\Scripts\python.exe
```

Para atualizar a biblioteca, baixe o wheel da nova versão e execute:

```powershell
.\.venv\Scripts\python.exe -m pip install --upgrade "C:\caminho\do\novo-wheel.whl"
```

## Uso básico

```python
from dominio_net import (
    AlertState,
    get_main_window_after_login,
    launch_app,
    perform_login,
    switch_company,
)

app = launch_app(r"C:\Contabil\contabil.exe")
perform_login(app, username="meu_usuario", password="minha_senha")

# Aguarda a tela principal e troca para Escrita Fiscal quando necessário.
main_window = get_main_window_after_login(app)

alert_state = AlertState()
switch_company(
    app,
    company_code=123,
    company_name="Empresa de exemplo",
    alert_state=alert_state,
)
```

## API

### `launch_app(app_path, *, backend="uia", start_timeout=None, start_options=None)`

Inicia o executável e devolve a instância conectada de `Application`. Os
argumentos opcionais de `start_options` são encaminhados para
`pywinauto.Application.start`.

### `perform_login(app, username, password, ...)`

Aguarda a janela `Conectando ...`, preenche usuário (`auto_id="1005"`) e senha
(`auto_id="1007"`) e confirma no botão `OK` (`auto_id="1003"`). Os títulos,
identificadores, timeout e espera final podem ser configurados. A senha não é
registrada nos logs nem incluída nas mensagens de erro.

### `get_main_window_after_login(app, ...)`

Aguarda uma janela cujo título corresponda a `Domínio.*`. Por padrão verifica
se o módulo `Escrita Fiscal` está no título e chama `switch_module` caso não
esteja. Diferentemente da função original, esta versão **devolve a janela
principal**, facilitando a composição com outras automações.

### `switch_module(app, module_name="Escrita Fiscal", ...)`

Abre o seletor de módulos pela coordenada configurada e seleciona o item pelo
nome. A coordenada original `(20, 50)` continua sendo o padrão, mas pode ser
substituída por `menu_coordinates=(x, y)`.

### `switch_company(app, company_code, ...)`

Abre a troca de empresas com F8, seleciona a pesquisa por código, preenche o
código e acessa a empresa. `AlertState` conserva entre chamadas a informação
de que houve um alerta na empresa anterior.

### `find_windows(main_window, max_attempt=5, ...)`

Procura a janela `Atenção` e tenta acionar, nessa ordem, os botões `OK` e
`Não`. Retorna `True` quando uma janela foi tratada e `False` quando nenhuma
foi encontrada.

## Exceções

Todas as falhas da biblioteca derivam de `DominioAutomationError`:

- `DominioLaunchError`
- `DominioLoginError`
- `DominioMainWindowError`
- `DominioModuleError`
- `DominioCompanyError`
- `DominioCompanyAlertError`

```python
from dominio_net import DominioAutomationError, launch_app

try:
    app = launch_app(r"C:\Contabil\contabil.exe")
except DominioAutomationError as error:
    print(f"Não foi possível controlar o Domínio: {error}")
```

## Observações de estabilidade

Os títulos e `auto_id` usados são os observados no `rpa-mit`. Atualizações do
Domínio podem alterar esses identificadores. `switch_module` ainda depende de
uma coordenada de tela para abrir o seletor de módulos; por isso a sessão deve
estar visível e com escala/resolução compatíveis.
