ntp-time 0.0.0

English description follows Japanese.

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

概要

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

インストール

pip install ntp-time

使い方

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

pip install ntp-time

Usage

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.