unstd 3.1.0__cp313-cp313-win_amd64.whl

unstd/__init__.py

@@ -0,0 +1,86 @@
+"""unstd — the unstandardized library.
+
+Best-in-class native codecs behind small, **stdlib-faithful** surfaces: migrate a
+call site by swapping the import, not the call. The base install is pure stdlib —
+depending on ``unstd`` costs zero third-party closure — and each accelerated
+backend rides an optional extra with a guarded stdlib fallback, so a lightweight
+consumer never inherits a heavy dependency graph.
+
+Module groups (grown incrementally from the stdlib census) — each named for the
+stdlib surface it stands in for, and each either degrading to that surface or
+failing loud where no faithful substitute exists:
+
+- ``serde`` (``json`` / ``base64``) — ``jsonx`` (orjson/msgspec) · ``b64`` (pybase64) ·
+  ``ndjson`` (newline-delimited, rides ``jsonx``) · ``structs`` (msgspec, no
+  stdlib equivalent). Behind the ``serde`` extra; the rest fall back to stdlib.
+- ``ids`` (``uuid``) — ``uid``: UUIDv7 minting and v5 derivation, falling back to
+  a stdlib generator. Behind the ``ids`` extra.
+- ``crypto`` (``hashlib`` / ``hmac`` / ``ssl``) — BLAKE3 digests (content
+  hashes and short ids included), key derivation, keyed MACs and the bearer
+  envelope, constant-time compare, and a verifying TLS client policy. No
+  fallback: ``hashlib`` ships BLAKE2, which is a different algorithm, not a
+  slower one.
+- ``time`` — ``timeutil`` (clocks, RFC-3339 formatting, ISO parsing, instant
+  arithmetic — pure stdlib; its protobuf ``Timestamp`` bridge is behind the
+  ``proto`` extra) · ``zoned`` (DST-correct wall-clock time over ``whenever``,
+  behind the ``time`` extra).
+- ``model`` — the strict Pydantic wire-shape spine: ``StrictModel`` ·
+  ``FrozenModel`` · ``StrictSettings``. Behind the ``model`` extra (pydantic has
+  no stdlib equivalent, so there is no fallback).
+- ``rex`` (``re``) — irregex linear-time matching, falls back to ``re``; the
+  flag and type vocabulary is re-exported verbatim.
+- ``containers`` (``collections``) — always-sorted collections and a persistent
+  HAMT ``Map``. No faithful fallback (an ``O(n)`` stand-in would be a silent
+  lie), so the placeholders raise on construction.
+- ``rand`` (``random``) — numpy PCG64 bulk draws; security-sensitive draws stay
+  on ``secrets`` regardless of the extra.
+- ``pack`` (``struct``) — numpy bulk pack/unpack.
+- ``clone`` (``copy``) — an exact-type structural deep clone, pure stdlib.
+- ``text`` (``difflib``) — rapidfuzz similarity and fuzzy matching.
+- ``audio`` (``wave``) — soundfile read/write plus a streaming writer.
+- ``toml`` (``tomllib``) — reading is stdlib; writing needs tomlkit.
+- ``yaml`` — safe YAML 1.2 and comment-preserving edits; requires the ``yaml`` extra.
+- ``compress`` (``gzip``) — zlib-ng codecs behind ``gzipx``; the ``compress``
+  extra accelerates compression and inflation, with a stdlib fallback.
+- ``proc`` (``subprocess``) · ``fs`` (``os``) · ``iters`` (``itertools``) —
+  pure stdlib, no extra, always present in the base install.
+
+Import the module, not its members::
+
+    from unstd.serde import jsonx, b64, structs, ndjson
+    from unstd.ids import uid
+    from unstd.crypto import digest, token
+    from unstd.time import timeutil, zoned
+    from unstd.model import StrictModel, FrozenModel, StrictSettings
+"""
+
+from __future__ import annotations
+
+
+__version__: str
+
+# A reload should refresh a version cached by a previous attribute access.
+globals().pop("__version__", None)
+
+
+def __getattr__(name: str) -> str:
+    """Resolve and cache the installed version only when it is requested."""
+    if name != "__version__":
+        msg = f"module {__name__!r} has no attribute {name!r}"
+        raise AttributeError(msg)
+
+    # Metadata discovery imports a large stdlib closure and scans distributions.
+    # Submodule consumers (including native codecs) do not need to pay that cost.
+    from importlib.metadata import PackageNotFoundError, version
+
+    try:
+        resolved = version("unstd")
+    except PackageNotFoundError:  # source tree that was never installed
+        resolved = "0.0.0.dev0"
+    globals()[name] = resolved
+    return resolved
+
+
+def __dir__() -> list[str]:
+    """Include the lazy version attribute without resolving install metadata."""
+    return sorted({*globals(), "__version__"})

unstd/_extra.py

@@ -0,0 +1,28 @@
+"""The deferred-raise placeholder every capability without a stdlib fallback binds.
+
+Where a backend has no faithful substitute (a sorted container, a persistent
+trie, a TOML writer), its public name still has to exist so the module imports
+cleanly on a base install. :func:`missing` is that name: calling it raises an
+``ImportError`` naming the extra that fixes it, so a consumer that never touches
+the capability pays nothing, and one that does gets a one-line fix.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Never
+
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+
+def missing(qualname: str, extra: str) -> Callable[..., Never]:
+    """A stand-in for ``unstd.<qualname>`` that raises naming the ``extra`` it needs."""
+    msg = f"unstd.{qualname} requires the {extra!r} extra — install with: pip install 'unstd[{extra}]'"
+
+    def _raise(*_args: object, **_kwargs: object) -> Never:
+        raise ImportError(msg)
+
+    _raise.__name__ = _raise.__qualname__ = qualname.rpartition(".")[2]
+    _raise.__doc__ = f"Unavailable — {msg}."
+    return _raise

unstd/audio/README.md

@@ -0,0 +1,86 @@
+# `unstd.audio`
+
+Part of [`unstd`](../README.md). A stdlib-`wave`-faithful **replacement**
+that hands back sample _arrays_ instead of raw frame bytes — the shape a voice
+path (TTS/STT) actually wants. The stdlib `wave` module only exposes packed
+PCM byte strings; every call site then re-rolls the same `struct`/`array`
+unpacking. `unstd.audio` folds that decode into the reader and the encode into the
+writer.
+
+## Modules
+
+| File      | Role                                                                                                            |
+| --------- | ----------------------------------------------------------------------------------------------------------------- |
+| `wavx.py` | `read`/`write` (whole-file) · `blocks`/`Writer` (streaming) · `wrap_pcm` — numpy-native WAV samples ↔ file. |
+
+```python
+from unstd.audio import wavx
+
+samples, sr = wavx.read("in.wav")  # float32 in [-1, 1], sr = Hz
+wavx.write("out.wav", samples, sr)  # PCM_16 by default
+ints, sr = wavx.read("in.wav", dtype="int16")  # raw signed 16-bit
+
+# streaming — for a live TTS/STT pipeline, not a file already fully in memory:
+with wavx.Writer("out.wav", sr, channels=1) as w:
+    for chunk in synth_chunks:
+        w.write(chunk)
+for block in wavx.blocks("in.wav", blocksize=4096):
+    play(block)
+
+wavx.wrap_pcm(raw_pcm_bytes, sr, channels=1, width=2)  # header only, no decode
+```
+
+Mono is 1-D `(frames,)`; multichannel is 2-D `(frames, channels)` — the shape
+libsndfile/`soundfile` use. Float samples written are clamped to `[-1, 1]` then
+quantized; integer samples are written as-is.
+
+## Backend
+
+The `audio` extra (`pip install 'unstd[audio]'`) provides `soundfile==…` +
+`numpy==2.5.0`, so reads/writes ride **libsndfile** and samples are
+`numpy.ndarray`. Without it there are two guarded stdlib fallbacks:
+
+| Path                    | When                         | Samples             | Read widths | Write subtypes    |
+| ----------------------- | ---------------------------- | ------------------- | ----------- | ----------------- |
+| `soundfile` + `numpy`   | `audio` extra installed      | `ndarray`           | libsndfile  | libsndfile        |
+| stdlib `wave` + `numpy` | numpy present, no soundfile  | `ndarray`           | 8/16/32-bit | `PCM_16`/`PCM_32` |
+| stdlib `wave` + `array` | no numpy (pure-stdlib floor) | `list`/`list[list]` | 16-bit      | `PCM_16`          |
+
+The pure-stdlib floor deliberately trades ergonomics for zero dependencies:
+16-bit PCM only, Python lists, no vectorization. Wider widths / other subtypes
+raise a clear error pointing at the `audio` extra rather than silently degrading.
+
+**Fixed-point scaling is identical on every path** so a file written by one reads
+back consistently on another: a _w_-bit sample ↔ float via `± 2**(w-1)`, so
+`float32 → PCM16 → float32` round-trips lossless to within one quantization step
+(`1/32768`).
+
+## Streaming — `Writer` / `blocks`
+
+`read`/`write` buffer the whole file; a live pipeline (streaming TTS
+synthesis, STT playback) wants frames as they arrive instead. `Writer` is a
+context manager — `channels`/`subtype` are fixed up front (a stream has no
+complete array to infer them from), and each `.write(chunk)` call appends one
+chunk; `blocks(path, blocksize)` is the read-side generator, `blocksize`
+frames at a time. Fast path: `soundfile`'s own `SoundFile`/`blocks` streaming
+API. Fallback: stdlib `wave`'s `writeframesraw`/chunked `readframes`, which
+requires the write target be **seekable** (a real file path, or a file object
+opened on one) so `close()` can patch the RIFF/`data` sizes — a genuinely
+non-seekable sink (a raw socket) needs the `audio` extra.
+
+## `wrap_pcm` — a header, nothing else
+
+Some PCM never becomes samples: bytes straight off a wire (a codec's output, a
+socket frame, a transcription upload) just need a RIFF/WAVE container around
+them. `wrap_pcm(raw, samplerate, channels=1, width=2)` does exactly that — no
+scale, no clamp, no requantize — where routing the same bytes through
+`write` would decode to an array and re-quantize back, paying two
+conversions and a quantization step to reproduce its own input.
+
+## Prior art
+
+- **[`soundfile`](https://github.com/bastibe/python-soundfile)** (Bastian
+  Bechtold) — Python bindings over **[libsndfile](https://libsndfile.github.io/libsndfile/)**
+  (Erik de Castro Lopo), the fast path this module wraps.
+- The stdlib [`wave`](https://docs.python.org/3/library/wave.html) module — the
+  raw-frame surface `unstd.audio` replaces, and the fallback codec.

unstd/audio/__init__.py

@@ -0,0 +1,22 @@
+"""Audio I/O — numpy-native WAV read/write for voice paths.
+
+A stdlib-``wave``-faithful *replacement* that hands back sample **arrays** instead
+of raw frame bytes. The stdlib ``wave`` module only exposes packed PCM byte
+strings; every TTS/STT call site then re-rolls the same ``struct``/``array``
+unpacking. ``unstd.audio`` folds that decode into the reader and the encode into
+the writer, so the surface is samples-in / samples-out.
+
+Backend & fallback: the ``audio`` extra provides ``soundfile``
+(libsndfile bindings) + ``numpy``. When present, reads/writes ride libsndfile and
+samples are ``numpy`` arrays. Without the extra (a base ``unstd`` install) the
+module falls back to the stdlib ``wave`` module plus manual PCM↔numpy conversion,
+or — when ``numpy`` is also absent — the stdlib ``array`` module (reduced
+ergonomics: 16-bit PCM only, Python ``list`` samples). The public surface works
+everywhere; only the codec and the sample container differ.
+
+Import the module, not its members::
+
+    from unstd.audio import wavx
+"""
+
+from __future__ import annotations