Metadata-Version: 2.1
Name: ntp-time
Version: 0.0.0
Summary: A tool for obtaining accurate time using NTP servers.
Home-page: https://github.co.jp/
Author: bib_inf
Author-email: contact.bibinf@gmail.com
License: CC0 v1.0
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries
Classifier: License :: CC0 1.0 Universal (CC0 1.0) Public Domain Dedication
Description-Content-Type: text/markdown

English description follows Japanese.

## 📘 `ntp-time` ドキュメント（日本語）

### 概要

`ntp-time` は、NTP (Network Time Protocol) サーバーと同期した「比較的正確な時刻」を取得できる Python ライブラリです。標準の `time.time()` のように扱えるシンプルなインターフェースを持ちつつ、インターネット越しの時刻補正や、遅延の補償、バックグラウンド同期などの工夫がなされています。

### インストール

```bash
pip install ntp-time
```

### 使い方

```python
import ntp_time

# 正確な現在時刻を取得
t = ntp_time.now()

print(t)  # 例: 1743499065.294967 (float型のUNIXタイムスタンプ)
```

### 特徴

- `ntp_time.now()` は呼び出し時にネットワークアクセスを伴わないため、高頻度に呼び出しても高速かつ負荷が少ない。
- NTPサーバーを使った正確な時刻取得が可能。
- `time.time()` のように UNIX タイムスタンプ (float型) として利用可能。
- 通信遅延は自動的に補正されます（ただし完全な正確性は保証されません）。
- 補正の際、時刻が「巻き戻る」ことによる不具合を避けるため、補正は最大10秒かけて徐々に行われます。
- デフォルトで1分ごとに自動的に再同期（バックグラウンドスレッドで動作）。
- 同期先は `pool.ntp.org`（複数のNTPサーバーに自動分散）。
- NTP接続失敗時には、1秒、3秒、9秒、27秒後に再試行。すべて失敗した場合は例外を投げて停止。
- 起動から約10秒後には正確な時刻に収束。

### 注意点

- ライブラリ初期化後すぐの `now()` は、まだNTP同期されていないため、数秒間は時刻がずれている可能性があります。
- 時刻補正は常に「進む」方向になるとは限りません（ただし「戻る」場合は滑らかに補正されます）。
- 長時間動作させる場合や、正確な時刻が重要な処理では、`now()` の出力を定期的に確認することを推奨します。

---

## 📘 `ntp-time` Documentation (English)

### Overview

`ntp-time` is a lightweight Python library that provides relatively accurate current time using NTP (Network Time Protocol) servers. It mimics `time.time()` by returning UNIX timestamps (floats), while internally handling synchronization, delay compensation, and background updates.

### Features

- `ntp_time.now()` does **not** perform any network access at the time of the call — making it fast and safe for frequent use.
- Provides accurate current time using NTP servers.
- Returns UNIX timestamp as `float`, just like `time.time()`.
- Internet communication delays are compensated (note: not guaranteed to be perfectly accurate).
- To prevent issues from "time going backward," corrections are smoothed over 10 seconds.
- By default, synchronization happens every minute in a **background thread** — no need to manage it manually.
- Synchronizes with `pool.ntp.org`, which provides access to multiple reliable NTP servers.
- On connection failure, automatic retries occur after 1s, 3s, 9s, and 27s. If all fail, the program raises an exception and exits.
- Accurate time is typically established within the first ~10 seconds of runtime.

### Installation

```bash
pip install ntp-time
```

### Usage

```python
import ntp_time

# Get the accurate current time
t = ntp_time.now()

print(t)  # e.g., 1743499065.294967 (float UNIX timestamp)
```

### Notes

- `now()` may return slightly inaccurate values for the first few seconds after startup, until synchronization completes.
- Time correction does not guarantee only forward movement; if time goes "backward", the library interpolates smoothly over 10 seconds.
- For long-running processes or time-critical applications, consider monitoring the output of `now()` periodically.
