Metadata-Version: 2.5
Name: chumicro-ntp
Version: 0.15.0
Summary: Runner-shaped SNTP client over an injected UDP socket: pure Python, cross-runtime.
Project-URL: Homepage, https://github.com/ChuMicro/ChuMicro
Project-URL: Documentation, https://chumicro.github.io/ChuMicro/ntp/stable/
Project-URL: Source, https://github.com/ChuMicro/ChuMicro/tree/main/libraries/ntp
Project-URL: Issues, https://github.com/ChuMicro/ChuMicro/issues
Project-URL: Bundle, https://github.com/ChuMicro/ChuMicro-Bundle
Author: ChuMicro
License-Expression: MIT
License-File: LICENSE
Keywords: circuitpython,embedded,esp32,microcontroller,micropython,ntp,rp2040,sntp,time
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Embedded Systems
Classifier: Topic :: System :: Hardware
Requires-Python: >=3.11
Requires-Dist: chumicro-sockets
Requires-Dist: chumicro-timing
Provides-Extra: test
Requires-Dist: chumicro-config; extra == 'test'
Requires-Dist: chumicro-pytest-device; extra == 'test'
Requires-Dist: chumicro-test-harness; extra == 'test'
Requires-Dist: chumicro-workspace; extra == 'test'
Requires-Dist: pytest; extra == 'test'
Description-Content-Type: text/markdown

# chumicro-ntp

<img src="https://raw.githubusercontent.com/ChuMicro/ChuMicro/main/support/docs/chumicro_tip.png"
align="left" width="64" style="margin-right: 16px; margin-bottom: 8px;">

**An SNTP (Simple Network Time Protocol) client that runs in your tick loop without blocking it.**

Polls one server, advances on each runner tick, and gives you the unix seconds when the response lands.  Pure Python, no compiled module, no `time.sleep()`.  Your LED keeps blinking through the network hop.  UDP transport is injected so apps with a custom socket layer don't drag `chumicro-sockets` into the device deploy.

<br clear="left">

> Part of the [ChuMicro](https://github.com/ChuMicro/ChuMicro) family: small, focused Python libraries for microcontrollers and laptops. [Browse all libraries.](https://github.com/ChuMicro/ChuMicro/tree/main/libraries)

## Install

```bash
# CircuitPython (after `circup bundle-add ChuMicro/ChuMicro-Bundle`)
circup install chumicro_ntp

# MicroPython
mpremote mip install github:ChuMicro/ChuMicro-Bundle/chumicro_ntp

# CPython
pip install chumicro-ntp
```

For bundle setup, pre-compiled `.mpy` bundles, the experimental channel, and details on PyPI naming, see the [chumicro INSTALL guide](https://github.com/ChuMicro/ChuMicro/blob/main/INSTALL.md).

## Quick example

```python
from chumicro_ntp import NTPClient
from chumicro_sockets import udp_socket
from chumicro_timing import ticks_ms

# On CircuitPython pass radio=wifi.adapter.radio (your chumicro-wifi
# WifiService's board radio); the kwarg is ignored on MP / CPython.
sock = udp_socket(radio=None)
sock.setblocking(False)                     # required: a blocking recv wedges on packet loss
client = NTPClient(socket=sock, server="pool.ntp.org")
request = client.query()
while not request.done:
    if client.check(ticks_ms()):
        client.handle(ticks_ms())
print("unix seconds:", request.unix_seconds)
```

`chumicro_sockets.udp_socket` builds the default bound UDP socket.  Pass any object satisfying the `sendto` / `recvfrom_into` / `close` / `setblocking` contract (see `NTPClient`'s docstring) to `NTPClient(socket=...)`.  `chumicro_sockets.udp_socket` and `chumicro_sockets.testing.FakeUDPSocket` are the built-in producers.  `NTPClient.from_config` wires that default itself through the shared `chumicro_sockets.sockets_factory` module, imported lazily, so apps with a custom UDP transport keep `chumicro-sockets` out of their device deploy.

## What's included

| Symbol | Purpose |
|---|---|
| `NTPClient(socket, *, server="pool.ntp.org", port=123, timeout_ms=5000, ticks=None)` | Runner-shaped SNTP client.  Single in-flight query at a time; mirrors `HttpClient.busy`. |
| `NTPClient.query()` | Send a request; returns a `NTPResult` to poll. |
| `NTPClient.check(now_ms)` / `handle(now_ms)` | Runner contract: handle drains the recv socket and detects timeouts. |
| `NTPClient.cancel()` | Abort an in-flight query. |
| `NTPResult` | Per-query handle.  `done`, `unix_seconds`, `error`. |
| `NTPError` | OSError subclass raised on protocol-level failures (short/malformed response, kiss-of-death, timeout, cancel). |
| `chumicro_sockets.udp_socket(radio=None)` | Built-in bound UDP socket for `NTPClient(socket=...)`.  `NTPClient.from_config` reaches it through the shared `chumicro_sockets.sockets_factory`; a custom transport skips that import and keeps `chumicro-sockets` out of the deploy. |

## Where this fits

Depends on [`chumicro-sockets`](https://github.com/ChuMicro/ChuMicro/tree/main/libraries/sockets) for UDP transport and [`chumicro-timing`](https://github.com/ChuMicro/ChuMicro/tree/main/libraries/timing) for ticks.  A single `pip install chumicro-ntp` brings the stack.  Used directly in app code; no other ChuMicro library depends on it.

## Platform support

Pure-Python; runs identically on CPython, MicroPython, and CircuitPython.

## Examples

| Example | What it shows |
|---|---|
| [`examples/ntp_query.py`](https://github.com/ChuMicro/ChuMicro/blob/main/libraries/ntp/examples/ntp_query.py) | Real query against `pool.ntp.org`: wifi up, UDP socket via factory, runner-shaped poll loop.  Cross-runtime (CP + MP). |

## Contributing

Issues, bug reports, and pull requests are welcome, and so is "I ran it on this board and here's what happened", some of the most useful feedback a hardware project can get.  Development happens in the [ChuMicro repository](https://github.com/ChuMicro/ChuMicro), whose contributing guide covers setup and the test workflow.

## Docs

📖 **[Stable docs](https://chumicro.github.io/ChuMicro/ntp/stable/)** · **[Experimental docs](https://chumicro.github.io/ChuMicro/ntp/experimental/)**

## Find this library

- **PyPI:** [chumicro-ntp](https://pypi.org/project/chumicro-ntp/)
- **Bundle:** [ChuMicro-Bundle](https://github.com/ChuMicro/ChuMicro-Bundle/tree/main/chumicro_ntp) (CircuitPython & MicroPython)
- **Experimental bundle:** [ChuMicro-Bundle-Experimental](https://github.com/ChuMicro/ChuMicro-Bundle-Experimental/tree/main/chumicro_ntp)
- **Source:** [libraries/ntp](https://github.com/ChuMicro/ChuMicro/tree/main/libraries/ntp)

## License

[MIT](https://github.com/ChuMicro/ChuMicro/blob/main/LICENSE)
