Metadata-Version: 2.4
Name: pyntp
Version: 0.1.1
Summary: Python library for accurate time from NTP servers with threaded and synchronous modes.
Author-email: Thomaz Pougy <thomazpougy@gmail.com>
License: MIT License
        
        Copyright (c) 2025 Thomaz Pougy
        
        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/tpougy/pyntp
Project-URL: Bug Tracker, https://github.com/tpougy/pyntp/issues
Project-URL: Original Package, https://pypi.org/project/ntp-time/
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Networking :: Time Synchronization
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: iter-backoff
Requires-Dist: ntplib>=0.4.0
Dynamic: license-file

# PyNTP Time

**PyNTP Time** é uma biblioteca Python leve e robusta para obter o tempo preciso de servidores NTP (Network Time Protocol). Ela oferece uma interface similar à `time.time()`, retornando timestamps UNIX (float), enquanto gerencia internamente a sincronização, compensação de atraso e atualizações.

Este pacote é um fork e uma refatoração do [ntp-time](https://pypi.org/project/ntp-time/), com o objetivo de modernizar a estrutura do código para uma abordagem orientada a objetos e oferecer maior flexibilidade na configuração.

## Funcionalidades Principais

- **Orientado a Objetos:** Configure e utilize o cliente NTP através de uma instância da classe `NTPTime`.
- **Servidor NTP Configurável:** Especifique o servidor NTP desejado ao instanciar o cliente.
- **Modos de Operação Flexíveis:**
  - **Threaded (Padrão):** Sincronização automática em segundo plano a cada X segundos (configurável), garantindo que chamadas a `now()` sejam rápidas e não realizem acesso à rede no momento da chamada.
  - **Síncrono:** Realiza a sincronização com o servidor NTP a cada chamada do método `now()`. Ideal para casos onde multithreading não é desejado ou para scripts de curta duração que necessitam do tempo mais atualizado possível no momento da consulta.
- **Compensação de Atraso:** Atrasos de comunicação com a Internet são compensados (nota: não há garantia de precisão perfeita).
- **Suavização de Tempo:** Para evitar problemas com o "tempo andando para trás", as correções são aplicadas gradualmente ao longo de um período configurável (padrão: 10 segundos).
- **Backoff Exponencial:** Em caso de falha na conexão, novas tentativas ocorrem com um intervalo crescente.

## Instalação

```bash
pip install pyntp-time
```

_(Nota: Quando o pacote estiver disponível no PyPI. Por enquanto, instale localmente ou via Git.)_

## Como Usar

### Modo Threaded (Padrão)

Neste modo, a sincronização ocorre em uma thread separada em intervalos regulares. O método `now()` retorna o tempo ajustado com base no último offset calculado, tornando-o muito rápido.

```python
import time
from pyntp import NTPTime

# Instancia o cliente NTP (usará pool.ntp.org por padrão e modo threaded)
ntp_client = NTPTime()

# Aguarde alguns segundos para a primeira sincronização em background (especialmente na primeira execução)
# Em aplicações de longa duração, isso não é um problema.
# Para scripts curtos, considere o modo síncrono ou uma espera inicial.
print("Aguardando a primeira sincronização em background...")
time.sleep(5) # Exemplo de espera, pode variar. Idealmente, a biblioteca deve lidar com isso internamente ou fornecer um status.

print("Tempo NTP (Threaded):")
for _ in range(5):
    t = ntp_client.now()
    print(f"Timestamp: {t}, Humano: {time.ctime(t)}")
    time.sleep(1)

# Você pode configurar o servidor e os intervalos:
# ntp_client_custom = NTPTime(ntp_server_url="time.google.com", adjust_interval=300, merge_time=5)
```

### Modo Síncrono (Não-Threaded)

Neste modo, cada chamada a `now()` bloqueará a execução para contatar o servidor NTP e obter o offset mais recente. Isso pode introduzir latência, mas garante que o tempo retornado é o mais atualizado possível no momento da chamada.

```python
import time
from pyntp import NTPTime

# Instancia o cliente NTP em modo síncrono
ntp_client_sync = NTPTime(threaded=False, ntp_server_url="time.cloudflare.com")

print("\nTempo NTP (Síncrono):")
# A primeira chamada pode demorar um pouco mais devido à sincronização inicial no construtor.
# As subsequentes também farão I/O de rede.
for i in range(3):
    print(f"Chamada {i+1}...")
    t_sync = ntp_client_sync.now()
    print(f"Timestamp: {t_sync}, Humano: {time.ctime(t_sync)}")
    time.sleep(1) # Pequena pausa para observar
```

## Configuração da Instância `NTPTime`

O construtor da classe `NTPTime` aceita os seguintes parâmetros:

- `ntp_server_url (str)`: URL do servidor NTP a ser utilizado. (Padrão: `"pool.ntp.org"`)
- `adjust_interval (int)`: Intervalo em segundos para a sincronização automática no modo threaded. (Padrão: `60` segundos)
- `merge_time (int)`: Tempo em segundos durante o qual a correção do offset é gradualmente aplicada. (Padrão: `10` segundos)
- `threaded (bool)`: Se `True` (padrão), opera em modo threaded. Se `False`, opera em modo síncrono.

## Contribuições

Contribuições são bem-vindas! Sinta-se à vontade para abrir issues ou pull requests.

## Licença

Este projeto é licenciado sob a Licença MIT. Veja o arquivo `LICENSE` para mais detalhes.

## Agradecimentos

- Este projeto é um fork e uma refatoração do excelente trabalho feito no pacote [ntp-time](https://pypi.org/project/ntp-time/).
