adafruit-circuitpython-ntp 3.3.7__tar.gz → 3.4.0__tar.gz

adafruit_circuitpython_ntp-3.4.0/.github/workflows/tests.yml

@@ -0,0 +1,32 @@
+# SPDX-FileCopyrightText: 2026 Ted Timmons
+#
+# SPDX-License-Identifier: MIT
+
+name: Run Tests
+
+on: [pull_request, push]
+
+jobs:
+  pytest:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.13"]
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install pytest
+        run: pip install pytest
+
+      # The suite needs no hardware and no network: it substitutes a `time`
+      # shim that enforces the 32-bit machine-word limit on localtime(), and
+      # the real-socket tests use loopback UDP against a local fake server.
+      - name: Run tests
+        run: python -m pytest tests/ -v

{adafruit_circuitpython_ntp-3.3.7 → adafruit_circuitpython_ntp-3.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: adafruit-circuitpython-ntp
-Version: 3.3.7
+Version: 3.4.0
 Summary: Network Time Protocol (NTP) helper for Python
 Author-email: Adafruit Industries <circuitpython@adafruit.com>
 License-Expression: MIT

{adafruit_circuitpython_ntp-3.3.7 → adafruit_circuitpython_ntp-3.4.0}/adafruit_circuitpython_ntp.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: adafruit-circuitpython-ntp
-Version: 3.3.7
+Version: 3.4.0
 Summary: Network Time Protocol (NTP) helper for Python
 Author-email: Adafruit Industries <circuitpython@adafruit.com>
 License-Expression: MIT

{adafruit_circuitpython_ntp-3.3.7 → adafruit_circuitpython_ntp-3.4.0}/adafruit_circuitpython_ntp.egg-info/SOURCES.txt

@@ -16,6 +16,7 @@ ruff.toml
 .github/workflows/failure-help-text.yml
 .github/workflows/release_gh.yml
 .github/workflows/release_pypi.yml
+.github/workflows/tests.yml
 LICENSES/CC-BY-4.0.txt
 LICENSES/MIT.txt
 LICENSES/Unlicense.txt
@@ -38,4 +39,12 @@ docs/_static/favicon.ico.license
 examples/ntp_connection_manager.py
 examples/ntp_cpython.py
 examples/ntp_set_rtc.py
-examples/ntp_simpletest.py
+examples/ntp_simpletest.py
+tests/README.md
+tests/README.md.license
+tests/conftest.py
+tests/harness.py
+tests/test_ntp_failover.py
+tests/test_poll_interval.py
+tests/test_real_sockets.py
+tests/test_response_validation.py

adafruit_circuitpython_ntp-3.4.0/adafruit_ntp.py

@@ -0,0 +1,225 @@
+# SPDX-FileCopyrightText: 2022 Scott Shawcroft for Adafruit Industries
+#
+# SPDX-License-Identifier: MIT
+
+"""
+`adafruit_ntp`
+================================================================================
+
+Network Time Protocol (NTP) helper for CircuitPython
+
+ * Author(s): Scott Shawcroft
+
+Implementation Notes
+--------------------
+**Hardware:**
+**Software and Dependencies:**
+
+ * Adafruit CircuitPython firmware for the supported boards:
+   https://github.com/adafruit/circuitpython/releases
+
+"""
+
+import struct
+import time
+
+from micropython import const
+
+try:
+    from typing import Sequence, Union
+except ImportError:
+    pass
+
+__version__ = "3.4.0"
+__repo__ = "https://github.com/adafruit/Adafruit_CircuitPython_NTP.git"
+
+NTP_TO_UNIX_EPOCH = 2208988800  # 1970-01-01 00:00:00
+PACKET_SIZE = const(48)
+# RFC 5905 constrains the poll interval to 2**4 through 2**17 seconds.
+NTP_MINPOLL = const(4)
+NTP_MAXPOLL = const(17)
+
+_DEFAULT_SERVERS = (
+    "0.adafruit.pool.ntp.org",
+    "1.adafruit.pool.ntp.org",
+    "2.adafruit.pool.ntp.org",
+    "3.adafruit.pool.ntp.org",
+)
+
+
+class NTP:
+    """Network Time Protocol (NTP) helper module for CircuitPython.
+    This module does not handle daylight savings or local time. It simply requests
+    UTC from a NTP server.
+
+    :param object socketpool: A socket provider such as CPython's `socket` module.
+    :param server: One NTP server hostname, or a sequence of them. Each name is resolved to a
+        single IP and the client fails over between them: on a failed query it moves to the next
+        server and rotates the failed one to the back of the list. Defaults to Adafruit's four
+        pool names.  For most reliable performance it is recommended to have 3+ pool names.
+    :type server: str or Sequence[str]
+    :param int port: The port of the ntp server to query.
+    :param float tz_offset: Timezone offset in hours from UTC. Only useful for timezone ignorant
+        CircuitPython. CPython will determine timezone automatically and adjust (so don't use
+        this.) For example, Pacific daylight savings time is -7.
+    :param float socket_timeout: UDP socket timeout, in seconds (default 1.0).
+    :param int cache_seconds: how many seconds to use a cached result from NTP server
+        (default 0, which respects NTP server's minimum).
+    :param int reresolve_interval: how often, in seconds, to rebuild the server IP list from DNS,
+        for long-running programs whose resolved members may go stale. The NTP Pool asks vendors
+        not to re-resolve more than once per hour, so keep this >= 3600 (default 3600).
+
+    """
+
+    def __init__(
+        self,
+        socketpool,
+        *,
+        server: Union[str, Sequence[str]] = _DEFAULT_SERVERS,
+        port: int = 123,
+        tz_offset: float = 0,
+        socket_timeout: float = 1.0,
+        cache_seconds: int = 0,
+        reresolve_interval: int = 3600,
+    ) -> None:
+        self._pool = socketpool
+        self._servers = (server,) if isinstance(server, str) else tuple(server)
+        self._port = port
+        self._packet = bytearray(PACKET_SIZE)
+        self._tz_offset = int(tz_offset * 60 * 60)
+        self._socket_timeout = socket_timeout
+        self._cache_seconds = cache_seconds
+        self._reresolve_interval = reresolve_interval
+
+        self._addresses = None
+        self._last_resolve_ns = 0
+
+        # This is our estimated start time for the monotonic clock. We adjust it based on the ntp
+        # responses.
+        self._monotonic_start_ns = 0
+
+        self.next_sync = 0
+
+    def _resolve_servers(self) -> None:
+        """Rebuild the cached IP list from DNS on first use and every reresolve_interval."""
+        now = time.monotonic_ns()
+        fresh = self._addresses is not None
+        if fresh and (now - self._last_resolve_ns) < self._reresolve_interval * 1_000_000_000:
+            return
+
+        addresses = []
+        for name in self._servers:
+            try:
+                address = self._pool.getaddrinfo(name, self._port)[0][4]
+            except OSError:
+                continue
+            if address not in addresses:
+                addresses.append(address)
+
+        if addresses:
+            self._addresses = addresses
+            self._last_resolve_ns = now
+        elif self._addresses is not None:
+            self._last_resolve_ns = now  # keep the stale list; rate-limit re-resolve during outages
+        else:
+            raise OSError("NTP: could not resolve any server")
+
+    def _query_server(self, address) -> None:
+        """Send one request to a single server and update the clock, or raise on failure."""
+        self._packet[0] = 0b00100011  # Not leap second, NTP version 4, Client mode
+        for i in range(1, PACKET_SIZE):
+            self._packet[i] = 0
+        with self._pool.socket(self._pool.AF_INET, self._pool.SOCK_DGRAM) as sock:
+            sock.settimeout(self._socket_timeout)
+            local_send_ns = time.monotonic_ns()
+            sock.sendto(self._packet, address)
+            received = sock.recv_into(self._packet)
+            local_recv_ns = time.monotonic_ns()
+
+        # A short read leaves timestamp fields reading as our own pre-send zeros.
+        if received is None or received < PACKET_SIZE:
+            raise ArithmeticError(f"NTP response was {received} bytes, expected {PACKET_SIZE}")
+
+        # Clamp poll to the RFC 5905 range so a corrupt byte can't derail the next sync.
+        poll = min(
+            max(struct.unpack_from("!B", self._packet, offset=2)[0], NTP_MINPOLL), NTP_MAXPOLL
+        )
+
+        srv_recv_s, srv_recv_f = struct.unpack_from("!II", self._packet, offset=32)
+        srv_send_s, srv_send_f = struct.unpack_from("!II", self._packet, offset=40)
+
+        # A pre-epoch timestamp is a zeroed or truncated field, not a real time.
+        if srv_recv_s < NTP_TO_UNIX_EPOCH or srv_send_s < NTP_TO_UNIX_EPOCH:
+            raise ArithmeticError("NTP response has an invalid timestamp")
+
+        # Convert the server times from NTP to UTC for local use
+        srv_recv_ns = (srv_recv_s - NTP_TO_UNIX_EPOCH) * 1_000_000_000 + (
+            srv_recv_f * 1_000_000_000 // 2**32
+        )
+        srv_send_ns = (srv_send_s - NTP_TO_UNIX_EPOCH) * 1_000_000_000 + (
+            srv_send_f * 1_000_000_000 // 2**32
+        )
+
+        # Best estimate of the offset between server UTC and board monotonic_ns time.
+        clock_offset = ((srv_recv_ns - local_send_ns) + (srv_send_ns - local_recv_ns)) // 2
+        cache_offset_s = max(2**poll, self._cache_seconds)
+
+        # Assign session state only after the response has fully validated.
+        self.next_sync = local_recv_ns + cache_offset_s * 1_000_000_000
+        self._monotonic_start_ns = clock_offset + self._tz_offset * 1_000_000_000
+
+    def _update_time_sync(self) -> None:
+        """Query servers with failover. Raises OSError if none respond within socket_timeout
+        seconds, ArithmeticError for substantially incorrect NTP results."""
+        self._resolve_servers()
+
+        # Try each server once, rotating a failure to the back; retry once if there is only one.
+        attempts = 2 if len(self._addresses) == 1 else 1
+        timeout_exc = None
+        response_exc = None
+        for _server in range(len(self._addresses)):
+            address = self._addresses[0]
+            for _attempt in range(attempts):
+                try:
+                    self._query_server(address)
+                    return
+                except OSError as exc:
+                    timeout_exc = exc
+                except ArithmeticError as exc:
+                    response_exc = exc
+                    break
+            self._addresses.append(self._addresses.pop(0))
+
+        # Prefer the timeout (ETIMEDOUT) so an all-servers-down result stays backward compatible.
+        raise timeout_exc or response_exc or OSError("NTP: no server responded")
+
+    @property
+    def datetime(self) -> time.struct_time:
+        """Current time from NTP server. Accessing this property causes the NTP time request,
+        unless there has already been a recent request.
+
+        :return: The current UTC time.
+        :rtype: time.struct_time
+        """
+        if time.monotonic_ns() > self.next_sync:
+            self._update_time_sync()
+
+        # Calculate the current time based on the current and start monotonic times
+        current_time_s = (time.monotonic_ns() + self._monotonic_start_ns) // 1_000_000_000
+
+        return time.localtime(current_time_s)
+
+    @property
+    def utc_ns(self) -> int:
+        """UTC (unix epoch) time in nanoseconds. Accessing this property causes the NTP time
+        request, unless there has already been a recent request. Raises OSError exception if
+        no response is received within socket_timeout seconds, ArithmeticError for substantially
+        incorrect NTP results.
+
+        :return: UTC time in nanoseconds since the unix epoch.
+        :rtype: int
+        """
+        if time.monotonic_ns() > self.next_sync:
+            self._update_time_sync()
+
+        return time.monotonic_ns() + self._monotonic_start_ns

{adafruit_circuitpython_ntp-3.3.7 → adafruit_circuitpython_ntp-3.4.0}/pyproject.toml

@@ -12,7 +12,7 @@ requires = [
 [project]
 name = "adafruit-circuitpython-ntp"
 description = "Network Time Protocol (NTP) helper for Python"
-version = "3.3.7"
+version = "3.4.0"
 readme = "README.rst"
 authors = [
     {name = "Adafruit Industries", email = "circuitpython@adafruit.com"}

adafruit_circuitpython_ntp-3.4.0/tests/README.md

@@ -0,0 +1,63 @@
+# tests
+
+Reproduction for [issue #35](https://github.com/adafruit/Adafruit_CircuitPython_NTP/issues/35)
+(`OverflowError: overflow converting long int to machine word`). Upstream ships
+no test suite, so this directory is self-contained.
+
+```bash
+python3 -m venv .venv && .venv/bin/pip install pytest
+.venv/bin/python -m pytest tests/ -v
+```
+
+## What's here
+
+| File | What |
+|---|---|
+| `test_response_validation.py` | The bug: short, zeroed, and truncated responses, driven through a fake socketpool |
+| `test_poll_interval.py` | The server's poll byte clamped to the RFC 5905 range before it sets the resync interval |
+| `test_real_sockets.py` | The same mechanisms shown with CPython's real UDP sockets |
+| `harness.py` | Fake socketpool + a `time` shim enforcing the 32-bit machine-word limit on `localtime()`, as a real board does |
+| `conftest.py` | `micropython.const` shim, and puts the repo root on `sys.path` so `import adafruit_ntp` works |
+
+Everything runs against `../adafruit_ntp.py` in the working tree. No hardware
+and no network are needed.
+
+## Why the `time` shim matters
+
+The failure only exists on a 32-bit board. `time.localtime()` there converts its
+argument to a **machine word**, and CPython's does not — so the bug that crashes
+a QT Py ESP32-S2 passes silently under plain CPython. `harness.board_time()`
+substitutes a `time` whose `localtime()` enforces the int32 limit and whose
+monotonic clock is controllable. That makes a board-only crash deterministic on
+a laptop.
+
+## Expected result
+
+```
+30 passed
+```
+
+## What the tests establish
+
+The library reuses one `bytearray` as both request and response buffer, zeroes
+it before sending, and discards `recv_into`'s return value — so it reads back
+its own zeros whenever a datagram fails to overwrite offsets 40-43. What that
+produces depends on where the datagram truncates:
+
+| bytes received | before the fix | now |
+|---|---|---|
+| 0-32 | `OverflowError` | `ArithmeticError` |
+| 33-40 | silently returned a time decades off (1962) | `ArithmeticError` |
+| 41-43 | silently wrong by weeks | `ArithmeticError` |
+| 44-48 | correct | correct |
+
+The 1962 row was the quieter half: `datetime` averages the server's receive and
+transmit timestamps, so a valid receive plus a zeroed transmit landed halfway
+between 1900 and now — inside int32, so nothing raised at all. A guard that only
+checked for a zero timestamp would not have caught the 41-43 row either; that
+one needs the length check.
+
+`test_real_sockets.py` confirms the mechanism outside the fake: buffer reuse and
+truncation over loopback UDP, an over-48-byte response being harmless, and —
+because the socket is never `connect()`ed — acceptance of a datagram from a
+source that is not the server.

adafruit_circuitpython_ntp-3.4.0/tests/README.md.license

@@ -0,0 +1,3 @@
+SPDX-FileCopyrightText: 2026 Ted Timmons
+
+SPDX-License-Identifier: MIT

adafruit_circuitpython_ntp-3.4.0/tests/conftest.py

@@ -0,0 +1,22 @@
+# SPDX-FileCopyrightText: 2026 Ted Timmons
+#
+# SPDX-License-Identifier: MIT
+
+"""Make the CircuitPython library importable under CPython.
+
+Two things are needed: a stand-in for the `micropython` module, which CPython
+does not have, and the repo root on sys.path so `import adafruit_ntp` finds the
+library next to this directory.
+"""
+
+import os
+import sys
+import types
+
+# adafruit_ntp does `from micropython import const`.
+if "micropython" not in sys.modules:
+    _mp = types.ModuleType("micropython")
+    _mp.const = lambda x: x
+    sys.modules["micropython"] = _mp
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))

adafruit_circuitpython_ntp-3.4.0/tests/harness.py

@@ -0,0 +1,128 @@
+# SPDX-FileCopyrightText: 2026 Ted Timmons
+#
+# SPDX-License-Identifier: MIT
+
+"""Test harness reproducing adafruit/Adafruit_CircuitPython_NTP issue #35.
+
+Issue #35: `OverflowError: overflow converting long int to machine word` raised
+from `NTP.datetime`. Root cause reported by the filer: the NTP response packet
+came back with a transmit-timestamp seconds field of 0, so the computed unix
+timestamp became roughly -2208988800 (i.e. NTP epoch minus unix epoch). On a
+32-bit CircuitPython board `time.localtime()` takes a *machine word*, and
+-2208988800 does not fit in int32, hence the OverflowError.
+
+To reproduce deterministically under CPython we substitute the module's `time`
+with a fake that (a) has a controllable monotonic clock and (b) enforces the
+int32 machine-word limit on `localtime()` exactly like a 32-bit MCU does.
+"""
+
+import contextlib
+import struct
+import time as _real_time
+
+INT32_MIN = -(2**31)
+INT32_MAX = 2**31 - 1
+
+NTP_TO_UNIX_EPOCH = 2208988800
+PACKET_SIZE = 48
+
+
+class FakeTime:
+    """Stand-in for CircuitPython's `time` on a 32-bit board.
+
+    `localtime()` on such a board converts its argument to a machine word, so
+    anything outside int32 raises OverflowError with this exact message.
+    """
+
+    def __init__(self, monotonic_s=90_000):
+        self.monotonic_s = monotonic_s
+        self.localtime_calls = []
+
+    def monotonic_ns(self):
+        return int(self.monotonic_s * 1_000_000_000)
+
+    def localtime(self, secs):
+        self.localtime_calls.append(secs)
+        if not INT32_MIN <= secs <= INT32_MAX:
+            raise OverflowError("overflow converting long int to machine word")
+        return _real_time.gmtime(secs)
+
+    # struct_time type is referenced only in annotations
+    struct_time = _real_time.struct_time
+
+
+def make_packet(*, transmit_s, recv_s=None, poll=6, frac=0):
+    """Build a 48-byte NTP server response."""
+    if recv_s is None:
+        recv_s = transmit_s
+    pkt = bytearray(PACKET_SIZE)
+    pkt[0] = 0b00100100  # LI=0, VN=4, mode=4 (server)
+    pkt[1] = 2  # stratum
+    pkt[2] = poll
+    struct.pack_into("!II", pkt, 32, recv_s, frac)  # receive timestamp
+    struct.pack_into("!II", pkt, 40, transmit_s, frac)  # transmit timestamp
+    return pkt
+
+
+class FakeSocket:
+    def __init__(self, response):
+        self.response = response
+        self.sent = []
+
+    def settimeout(self, t):
+        pass
+
+    def sendto(self, packet, addr):
+        self.sent.append((bytes(packet), addr))
+
+    def recv_into(self, buf):
+        if self.response is None:
+            # Simulates a recv that writes nothing: the caller's buffer keeps
+            # whatever it held (adafruit_ntp zeroes it before sending).
+            return 0
+        n = min(len(buf), len(self.response))
+        buf[:n] = self.response[:n]
+        return n
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        return False
+
+
+class FakePool:
+    """Minimal socketpool stand-in."""
+
+    AF_INET = 2
+    SOCK_DGRAM = 2
+
+    def __init__(self, responses):
+        # responses: list of packets (or None) returned by successive requests
+        self.responses = list(responses)
+        self.request_count = 0
+
+    def getaddrinfo(self, host, port):
+        return [(2, 2, 0, "", ("10.0.0.1", port))]
+
+    def socket(self, family, type_):
+        idx = min(self.request_count, len(self.responses) - 1)
+        self.request_count += 1
+        return FakeSocket(self.responses[idx])
+
+
+@contextlib.contextmanager
+def board_time(module, monotonic_s=90_000):
+    """Swap the module's `time` for the 32-bit-board fake."""
+    fake = FakeTime(monotonic_s)
+    original = module.time
+    module.time = fake
+    try:
+        yield fake
+    finally:
+        module.time = original
+
+
+def valid_unix_seconds(when=1_720_915_505):
+    """A real-world unix timestamp (2024-07-14, when issue #35 was filed)."""
+    return when + NTP_TO_UNIX_EPOCH