Metadata-Version: 2.4
Name: pyModbusTCPtools
Version: 0.1.2
Summary: Biblioteca Python para comunicação Modbus TCP resiliente com leitura e escrita tipada
Author: Jocivaldo Siqueira da Silva Júnior
License: MIT License
        
        Copyright (c) 2025 Jocivaldo Siqueira da Silva Júnior
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/siqueira89jr-hash/pyModbusTCPtools
Project-URL: Documentation, https://siqueira89jr-hash.github.io/pyModbusTCPtools
Project-URL: Repository, https://github.com/siqueira89jr-hash/pyModbusTCPtools
Project-URL: Issues, https://github.com/siqueira89jr-hash/pyModbusTCPtools/issues
Keywords: modbus,modbus-tcp,industrial,automation,plc
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Manufacturing
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: System :: Hardware
Classifier: License :: OSI Approved :: MIT License
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: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyModbusTCP>=0.2.0
Dynamic: license-file

# pyModbusTCPtools

**pyModbusTCPtools** é uma biblioteca Python focada em **comunicação Modbus TCP resiliente**, projetada para uso em **ambientes industriais reais**.

O objetivo da biblioteca é fornecer uma API clara, segura e robusta para leitura e escrita Modbus TCP, evitando código repetitivo, frágil ou improvisado comumente encontrado em aplicações industriais.

---

## Principais características

- Cliente Modbus TCP resiliente
- Reconexão automática com backoff exponencial e jitter
- Leitura e escrita segura de Coils e Discrete Inputs
- Leitura e escrita de Holding Registers e Input Registers
- Leitura e escrita **tipada**:
  - INT16 / UINT16
  - INT32 / UINT32
  - INT64 / UINT64
  - FLOAT32
  - FLOAT64
- Suporte completo a endianness:
  - Big Endian
  - Little Endian (word swap)
  - Byte swap
  - Word + byte swap
- Cache interno de endereços Modbus inválidos
- API pública para limpeza/inspeção do cache de endereços inválidos
- Exceções explícitas e bem definidas
- Logging estruturado
- Compatível com Python 3.8+
- API com type hints para melhor integração com IDEs e análise estática

---

## O que a biblioteca não é

Para evitar ambiguidades, **pyModbusTCPtools não é**:

- Uma API REST
- Um servidor Modbus
- Um SCADA
- Um framework genérico de automação

Trata-se de uma **biblioteca cliente Modbus TCP**, voltada exclusivamente à comunicação e conversão de dados.

---

## Instalação

Instalação via pip:

```bash
pip install pyModbusTCPtools
```

Instalação local a partir de wheel:

```bash
pip install pyModbusTCPtools-0.1.0-py3-none-any.whl
```

---

## Exemplo rápido

Leitura de um valor FLOAT32 a partir de Holding Registers:

```python
from pyModbusTCPtools import ModbusTCPResiliente, ModbusDataType, Endian

client = ModbusTCPResiliente(
    host="192.168.0.10",
    unit_id=1,
    timeout=3.0
)

valor = client.read_holding_typed_safe(
    addr=100,
    dtype=ModbusDataType.FLOAT32,
    endian=Endian.BE
)

if valor is not None:
    print(f"Valor lido: {valor}")
```

---

## Filosofia de projeto

A biblioteca foi desenvolvida com foco em:

- Robustez em ambientes industriais
- Tratamento explícito de falhas
- Reconexão automática sem intervenção do usuário
- API previsível e estável
- Compatibilidade com evolução futura

Falhas de comunicação são tratadas como **eventos normais**, não como exceções fatais.

---

## Documentação

A documentação completa inclui:

- Guia de instalação
- Quickstart
- Conceitos de Modbus e endianness
- Documentação da API
- Exemplos práticos de leitura, escrita e reconexão

Documentação online:

https://siqueira89jr-hash.github.io/pyModbusTCPtools

---

## Cache de endereços inválidos

Além do cache interno, a biblioteca expõe helpers para inspeção e limpeza:

- `clear_invalid_cache()` limpa o cache.
- `get_invalid_cache_snapshot()` retorna os endereços atualmente em quarentena.

---

## Testes

Para executar a suíte de testes:

```bash
PYTHONPATH=src python -m unittest discover -s tests
```

---

## Nota de compatibilidade

Para `UINT64` com `Endian.LE`/`Endian.LE_SWAP`, a ordem de registradores foi ajustada para alinhar o roundtrip
de encode/decode. Se sua aplicação dependia da ordem anterior, valide com o equipamento.

---

## Requisitos

- Python 3.8 ou superior
- Rede TCP/IP com acesso ao dispositivo Modbus
- Dispositivo compatível com Modbus TCP

---

## Licença

Este projeto é distribuído sob a licença **MIT**, permitindo uso comercial e industrial sem restrições.

---

## Status do projeto

- Versão atual: **0.1.1**
- Estável para uso funcional
- API ainda pode evoluir até a versão 1.0.0

---

## Contribuição

Contribuições são bem-vindas.

Sugestões, issues e pull requests podem ser enviados via GitHub.

---

## Autor

Jocivaldo Siqueira da Silva Júnior
