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

dominio_net-0.2.0-py3-none-any.whl

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

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:

.\.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:

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

Resultado esperado:

0.2.0

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

.\.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:

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

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

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

Uso básico

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

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.