unstd 1.1.0__tar.gz → 2.0.0__tar.gz

{unstd-1.1.0 → unstd-2.0.0}/CHANGELOG.md

@@ -2,6 +2,175 @@
 
 <!-- towncrier release notes start -->
 
+## [2.0.0] - 2026-09-27
+
+### Breaking
+
+This is a 2.0 surface pass: every change below renames or removes a public name,
+and each old name fails at import rather than changing meaning in place.
+
+- `serde.b64` is one verb per direction. `b64s` / `b64u_s` → `encode(data, url=,
+  pad=)`, `b64d` / `b64u_d` → `decode(s, url=)`, `b64text` / `b64u_text` →
+  `decode_text`, `b64_json` / `unb64_json` → `encode_json` / `decode_json`.
+  `pad=False` is new - the unpadded base64url JWTs and bearer tokens use, which
+  callers were `rstrip("=")`-ing by hand - and url-safe `decode` now accepts
+  padded and unpadded input alike. Standard `decode` stays strict.
+- `ids.hash` is gone; it was three second names for `crypto.digest`. Content
+  hashes are `digest.hex(data)`, short ids `digest.hex(data, n)`, raw bytes
+  `digest.raw(data)` (was `sum_` / `hex_` / `hex_n` / `content_hash`).
+  `digest.of_parts(parts)` is `digest.Stream(parts).raw()`; `Stream.update_all`
+  went with it, and `Stream.sum_` / `hex_` are `raw` / `hex(n=None)`.
+  `digest.KDF_BYTES` folded into `DIGEST_BYTES` (both were 32).
+- `crypto.token.mac` / `mac_bytes` → `mac_hex` / `mac_raw`, so the return type is
+  in the name as it is in `digest`. `verify_mac` takes a tag in either form.
+  `equal` lives in `token` only, and `token.opaque` is
+  `rand.crypto.token_urlsafe` - it was a pass-through.
+- `time.dateutil` is `time.zoned`, holding only what needs `whenever`:
+  `wall` / `parse` / `now` / `instant` / `to_utc` (were `zoned_wall` /
+  `parse_zoned` / `zoned_now` / `parse_instant` / `zoned_to_utc`). The pure-stdlib
+  half - `parse_iso`, `parse_utc`, `parse_date`, `from_epoch_s`, `from_epoch_ms` -
+  moved to `timeutil`, so none of it needs the `time` extra any more.
+- `timeutil.span(start, end=None, *, unit, assume_utc=False)` replaces
+  `span_hours`, `span_minutes`, `age_days`, `minutes_until`, `minutes_since`, and
+  `hours_between`. Those five disagreed about whether a floating stamp was UTC
+  depending on which unit you asked in; `span` is strict unless told otherwise.
+  `iso_range`, `lookback`, `days_range`, and `day_offset` are removed.
+- `timeutil.iso(dt=None, *, ms=False)` replaces `utcnow_iso`, `utcnow_iso_ms`,
+  and `iso_fmt`; `today(utc=True)` replaces `utcnow_date_iso`; `today_iso` and
+  `date_fmt` are removed (`.isoformat()`); `human(tz="")` replaces `human_now`
+  and `human_now_tz`.
+- `timeutil.parse_date` returns `None` on bad input like every other parser
+  here, instead of raising.
+- `serde.structs.codec(...)` is removed; construct `structs.Codec(...)`.
+- `audio.wavx` drops the stutter: `read_wav` / `write_wav` / `read_blocks` /
+  `WavWriter` → `read` / `write` / `blocks` / `Writer`.
+- `fs.read_bytes`, `fs.read_text`, and `fs.iter_dir` are removed. They measured
+  slower than the `pathlib` methods they wrapped.
+- `proc.TimeoutError` is removed. It aliased `subprocess.TimeoutExpired`, which
+  does not subclass the builtin of that name.
+- `iters.take(iterable, n)` takes the iterable first, like `chunked`, `windowed`,
+  and `nth` beside it. The old order fails loudly (`'int' object is not
+  iterable`), never silently.
+- `iters.batched_with_key` is `iters.runs` - it groups consecutive runs by key;
+  it never batched. Its module is `iters.consecutive`.
+- `iters.partition(iterable, pred)` takes the iterable first, like every other
+  combinator in `iters`. The old order raises `TypeError` at the call.
+- `serde.ndjson.read(fp)` / `write(fp, rows)` → `load(fp)` / `dump(rows, fp)`,
+  the same shape as `jsonx.dump(obj, fp)` and `toml.dump(obj, fp)`. `dump` still
+  returns the record count.
+- `timeutil.now_tz(tz)` requires its zone. Called bare it was a second spelling
+  of `utcnow()`.
+- `toml`'s write half is `tomlkit`'s own functions rather than wrappers around
+  them, so `dumps` / `dump` accept `sort_keys=` and each name carries tomlkit's
+  types. On a base install each is a placeholder that raises naming the extra,
+  decided at import rather than re-checked per call.
+- `unstd.crypto` no longer re-exports the `blake3` class; it was the backend,
+  not a surface. The guard moved into `digest` / `token`, so `crypto.tls` - pure
+  stdlib - now imports on a base install instead of failing on a missing BLAKE3.
+- `crypto.tls.client_context(certfile=...)` alone loads the chain, which is the
+  combined cert-plus-key PEM most bundles ship as; it used to be ignored and the
+  client dialed without mTLS. A `keyfile` with no `certfile` raises `ValueError`.
+- The `ids` extra no longer pulls `blake3`; nothing under `ids` has used it since
+  `ids.hash` folded into `crypto.digest`. Depend on `unstd[crypto]` for digests.
+- `unstd.containers.guard` is gone. Its placeholder and `toml`'s copy of it are
+  one private helper, and every missing-backend name now raises the same
+  `unstd.<module>.<name> requires the '<extra>' extra` message.
+
+### Performance
+
+- `jsonx.dumps` 416 → 264 ns, `dumpb` 375 → 200 ns, `loads` 251 → 212 ns on a
+  small dict (raw orjson: ~180 ns). The fast path no longer detours through a
+  checking wrapper, and `loads` names its return type with an annotation instead
+  of a runtime `typing.cast` call.
+- `ndjson.dumpb` / binary `write` let orjson append each newline
+  (`OPT_APPEND_NEWLINE`) instead of concatenating a second `bytes` per row.
+- `rand`'s scalar draws are stdlib `random` on every install. Routing
+  `random()` / `choice` / `shuffle` through numpy's `Generator` one value at a
+  time was 5-7x slower than the stdlib draw; numpy still fills the bulk arrays.
+- `timeutil.wall` / `mono` / `mono_ns` / `perf` and `rand.crypto.*` are the stdlib
+  functions bound directly, with no forwarding frame.
+- `timeutil.iso` formats through `isoformat` (~2.6x faster than `strftime`), and
+  `epoch_ms` is exact integer math on `time_ns()`.
+- `structs.Codec.encode` / `decode` are msgspec's own bound methods.
+- `digest.hex(data, n)` asks the XOF for `n` bytes rather than slicing a full
+  hex string, and checks the width inline.
+- `jsonx.canonical` reuses one prebuilt encoder instead of letting `json.dumps`
+  construct a fresh one per call: ~1.25 µs → ~0.9 µs on a small dict, same bytes.
+- `b64.encode(url=True)` rides pybase64's `altchars` straight to `str`: 293 →
+  192 ns for 64 bytes unpadded.
+- `token.mac_hex` / `mac_raw` check the key inline - 943 → 674 ns - and `verify`
+  follows (2.1 → 1.6 µs).
+- `ndjson.loads` parses a clean blob in one comprehension over the backend
+  decoder and strips a line only when a direct parse fails: 338 → 187 µs per
+  1k records, level with a bare orjson loop. A bad line still re-walks the slow
+  path, so the error and its line number are unchanged.
+- `iters.windowed(step=1)` is staggered `tee` views zipped together, a C-level
+  walk: 4x on 10k items. `unique_everseen` skips the key call when there is no
+  key, and `last` indexes exact builtin sequences without an ABC probe (2x).
+- Pure forwarders are now the function they forwarded to: `timeutil.utcnow`
+  (`partial(datetime.now, UTC)`, 132 → 96 ns), `uid.parse` / `uid.derive`
+  (`UUID` / `uuid5`), `iters.flatten` (`chain.from_iterable`, 2x), `zoned.now`
+  (`ZonedDateTime.now`), and - with the `text` extra - `fuzz.ratio` /
+  `distance` / `jaro_winkler` as the rapidfuzz kernels (~25-40% per call). Clock
+  freezers that patch at the C layer (`time-machine`) still see the bound
+  references. The pure-Python fallbacks are held to the kernels by a property
+  test, since with the extra installed nothing else runs them. The fuzz scorers
+  take their two strings positionally.
+- `wavx.wrap_pcm` packs the 44-byte header with one `struct` call - byte-identical
+  to `wave`, pinned across widths, channel counts, and partial frames - 2.7x
+  faster on 32 KB.
+- `iters.partition` is the current `itertools` recipe - verdicts teed beside the
+  values and split with `compress` - so `pred` runs once per element instead of
+  once per side: 533 → 459 µs on 10k items with a trivial predicate, and half the
+  predicate calls whatever it costs.
+- `ndjson.dumps` joins orjson's row bytes and decodes once, and a text-mode
+  `dump` decodes each row's bytes rather than re-entering `jsonx.dumps`: ~20%
+  on both (399 → 317 µs and 547 → 421 µs per 1k rows).
+- `clone.asdict` tests dict keys and values for atoms inline instead of paying a
+  call per leaf: 5.2 → 3.8 µs on a dict-heavy record.
+- `rand.choices` unboxes the drawn index array once instead of calling `int()`
+  per element: 379 → 209 µs for 10k draws.
+
+### Fixed
+
+- `text.fuzz.best_match` / `extract` / `cdist` keep a choice scoring exactly at
+  `score_cutoff`, as documented. rapidfuzz's own cutoff drops boundary pairs
+  through a float round-trip (about 15% of random short pairs on 1.1), so every
+  fast path now scores in full and applies `>=` itself - at no measurable cost.
+  `cdist` also returns float64, so its scores equal `ratio`'s exactly.
+- `fs.atomic_write` / `atomic_writer` no longer flip the process-wide umask to
+  read it when creating a new file. Setting it to 0 and back left a window in
+  which any other thread creating a file got mode `0o666`/`0o777`. The temp file
+  is now opened at `0o666` so the kernel applies the umask, and an existing
+  destination's mode is still copied over.
+
+- `rex` accepts its own compiled patterns. On the irgx path `rex.compile(p)` and
+  `rex.search(p, s)` raised `TypeError` for a `p` this module had just returned,
+  because only stdlib's `re.Pattern` was recognized; stdlib takes either.
+- `rex.purge` clears irgx's pattern cache too, not just stdlib's.
+- A pattern irgx declines (backreferences, lookaround) is no longer re-attempted
+  on every call. irgx caches what it compiles, not what it refuses, so each
+  `rex.search(r"(\w+)\s+\1", ...)` paid a full compile attempt plus a raise -
+  about 1.8 ms, against 0.2 µs for stdlib.
+
+### Changed
+
+- `rex` keeps a bounded front cache like stdlib's `re._cache`, and hands flags to
+  irgx as its keyword arguments instead of building an inline `(?imsx-u)` prefix
+  through `RegexFlag` arithmetic. A module-level `rex.search` drops from ~5 µs to
+  ~0.8 µs - now twice as fast as `re.search` - and a compiled pattern's
+  `.pattern` is the caller's source again rather than carrying the prefix.
+- `rex.findall` rewrites irgx's `None` for an absent group only when one is
+  actually present, found by a C-level containment scan instead of rebuilding
+  every row. A two-group `findall` over 10 KB drops from ~940 µs to ~240 µs.
+- The `rex` extra requires `irregex>=2.6.0`. Below it, a replacement template's
+  octal escapes (`\07`, `\101`) and unknown non-letter escapes rendered different
+  text than stdlib with no error; 2.6.0 reads them the way `re` does. It also
+  makes a group-reading `rex.sub` and a grouped `rex.split` one call into the
+  engine instead of one per match, and stops a capped `subn`/`split` walking past
+  its cap - on 10 KB, templated `sub` goes from ~7x slower than `re.sub` to
+  about even, and `subn(..., count=5)` from ~130x to ~1.7x.
+
 ## [1.1.0] - 2026-09-27
 
 ### Fixed

{unstd-1.1.0 → unstd-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: unstd
-Version: 1.1.0
+Version: 2.0.0
 Summary: stdlib-faithful accelerated replacements behind optional extras
 Project-URL: Homepage, https://github.com/The-Billy-Company/unstd
 Project-URL: Repository, https://github.com/The-Billy-Company/unstd
@@ -30,7 +30,6 @@ Requires-Dist: sortedcontainers>=2.4; extra == 'containers'
 Provides-Extra: crypto
 Requires-Dist: blake3>=1.0; extra == 'crypto'
 Provides-Extra: ids
-Requires-Dist: blake3>=1.0; extra == 'ids'
 Requires-Dist: uuid-utils>=0.17; extra == 'ids'
 Provides-Extra: model
 Requires-Dist: pydantic-settings>=2.15; extra == 'model'
@@ -42,7 +41,7 @@ Requires-Dist: protobuf>=7.36; extra == 'proto'
 Provides-Extra: rand
 Requires-Dist: numpy>=2.5; extra == 'rand'
 Provides-Extra: rex
-Requires-Dist: irregex>=2.3.0; extra == 'rex'
+Requires-Dist: irregex>=2.6.0; extra == 'rex'
 Provides-Extra: serde
 Requires-Dist: msgspec>=0.21; extra == 'serde'
 Requires-Dist: orjson>=3.12; extra == 'serde'
@@ -84,9 +83,9 @@ python3 -m pip install 'unstd[serde,ids,crypto]'
 | Group | Extra | Backend / fallback |
 |---|---|---|
 | [`serde`](src/unstd/serde/README.md) | `unstd[serde]` | orjson / msgspec / pybase64 → stdlib `json`/`base64` |
-| [`ids`](src/unstd/ids/README.md) | `unstd[ids]` | blake3 / uuid-utils → `hash` requires the extra; `uid` falls back to stdlib UUIDv7 |
+| [`ids`](src/unstd/ids/README.md) | `unstd[ids]` | uuid-utils → `uid` falls back to stdlib UUIDv7 |
 | [`crypto`](src/unstd/crypto/README.md) | `unstd[crypto]` | blake3 (required; hashlib ships BLAKE2, a different algorithm) |
-| [`time`](src/unstd/time/README.md) | `unstd[time]` | `timeutil` is pure stdlib; `dateutil` requires `whenever`, and `timeutil`'s protobuf `Timestamp` bridge requires `unstd[proto]` |
+| [`time`](src/unstd/time/README.md) | `unstd[time]` | `timeutil` is pure stdlib; `zoned` requires `whenever`, and `timeutil`'s protobuf `Timestamp` bridge requires `unstd[proto]` |
 | [`model`](src/unstd/model/README.md) | `unstd[model]` | pydantic (required) |
 | [`rex`](src/unstd/rex/README.md) | `unstd[rex]` | irregex → stdlib `re` |
 | [`containers`](src/unstd/containers/README.md) | `unstd[containers]` | sortedcontainers + immutables (required) |

{unstd-1.1.0 → unstd-2.0.0}/README.md

@@ -27,9 +27,9 @@ python3 -m pip install 'unstd[serde,ids,crypto]'
 | Group | Extra | Backend / fallback |
 |---|---|---|
 | [`serde`](src/unstd/serde/README.md) | `unstd[serde]` | orjson / msgspec / pybase64 → stdlib `json`/`base64` |
-| [`ids`](src/unstd/ids/README.md) | `unstd[ids]` | blake3 / uuid-utils → `hash` requires the extra; `uid` falls back to stdlib UUIDv7 |
+| [`ids`](src/unstd/ids/README.md) | `unstd[ids]` | uuid-utils → `uid` falls back to stdlib UUIDv7 |
 | [`crypto`](src/unstd/crypto/README.md) | `unstd[crypto]` | blake3 (required; hashlib ships BLAKE2, a different algorithm) |
-| [`time`](src/unstd/time/README.md) | `unstd[time]` | `timeutil` is pure stdlib; `dateutil` requires `whenever`, and `timeutil`'s protobuf `Timestamp` bridge requires `unstd[proto]` |
+| [`time`](src/unstd/time/README.md) | `unstd[time]` | `timeutil` is pure stdlib; `zoned` requires `whenever`, and `timeutil`'s protobuf `Timestamp` bridge requires `unstd[proto]` |
 | [`model`](src/unstd/model/README.md) | `unstd[model]` | pydantic (required) |
 | [`rex`](src/unstd/rex/README.md) | `unstd[rex]` | irregex → stdlib `re` |
 | [`containers`](src/unstd/containers/README.md) | `unstd[containers]` | sortedcontainers + immutables (required) |

{unstd-1.1.0 → unstd-2.0.0}/bench/README.md

@@ -92,8 +92,8 @@ The harness earned its keep on the first run:
   real value is the shape beside it: handed an ndarray it already owns,
   `pack_array` is a memcpy and wins **159×**, and `unpack_array` returns a
   zero-copy view for **1667×**. Hold your data in an array, not a list.
-- **`hash.sum_`'s honest twin is `blake2b`, not `sha256`.** BLAKE2 is what
-  `hashlib` ships from the BLAKE family, so it is the thing `sum_` stands in for,
+- **`digest.raw`'s honest twin is `blake2b`, not `sha256`.** BLAKE2 is what
+  `hashlib` ships from the BLAKE family, so it is the thing `digest.raw` stands in for,
   and BLAKE3 beats it 1.7×. `sha256` is not a fair comparison in either
   direction: every ARMv8 and modern x86 core implements it in silicon, so
   `hashlib.sha256` is a hardware instruction and beats single-threaded BLAKE3

{unstd-1.1.0 → unstd-2.0.0}/bench/baseline.json

@@ -3,12 +3,12 @@
   "recorded": "2026-09-27",
   "host": "Darwin arm64 python3.13",
   "cases": {
-    "b64.b64d · 128 KiB": {
+    "b64.decode · 128 KiB": {
       "floor": 6.42,
       "measured": 8.94,
       "group": "serde"
     },
-    "b64.b64s · 128 KiB": {
+    "b64.encode · 128 KiB": {
       "floor": 11.77,
       "measured": 16.52,
       "group": "serde"
@@ -78,7 +78,7 @@
       "measured": 41.87,
       "group": "text"
     },
-    "hash.sum_ · 1 MiB": {
+    "digest.raw · 1 MiB": {
       "floor": 1.21,
       "measured": 1.72,
       "group": "ids"

{unstd-1.1.0 → unstd-2.0.0}/bench/cases.py

@@ -37,13 +37,14 @@ from typing import TYPE_CHECKING, Any
 
 from unstd.clone import asdict as clone_asdict
 from unstd.clone import deep
-from unstd.ids.hash import sum_
+from unstd.crypto.digest import raw as digest_raw
 from unstd.pack.binpack import pack_array, unpack_array
 from unstd.rand.draw import floats, ints
 from unstd.rex import compile as rex_compile
 from unstd.rex import findall as rex_findall
 from unstd.rex import search as rex_search
-from unstd.serde.b64 import b64d, b64s
+from unstd.serde.b64 import decode as b64_decode
+from unstd.serde.b64 import encode as b64_encode
 from unstd.serde.jsonx import dumps as jx_dumps
 from unstd.serde.jsonx import loads as jx_loads
 from unstd.text.fuzz import cdist, extract, ratio
@@ -220,20 +221,20 @@ case(
     base=json.loads,
 )
 case(
-    name="b64.b64s · 128 KiB",
+    name="b64.encode · 128 KiB",
     group="serde",
     backend="pybase64",
     payload=lambda: _BLOB,
-    accel=b64s,
+    accel=b64_encode,
     base=lambda p: base64.b64encode(p).decode("ascii"),
     note="pybase64 SIMD vs stdlib base64",
 )
 case(
-    name="b64.b64d · 128 KiB",
+    name="b64.decode · 128 KiB",
     group="serde",
     backend="pybase64",
     payload=lambda: _B64_TEXT,
-    accel=b64d,
+    accel=b64_decode,
     base=base64.b64decode,
 )
 
@@ -429,18 +430,18 @@ case(
 # ---------------------------------------------------------------- ids
 
 # The twin is blake2b, not sha256. BLAKE2 is what hashlib ships from the BLAKE
-# family, so it is the thing `sum_` actually stands in for — and a fair fight.
+# family, so it is the thing `digest.raw` actually stands in for — and a fair fight.
 # sha256 is *not* one: every ARMv8 and modern x86 core implements it in silicon,
 # so `hashlib.sha256` here is a hardware instruction and beats single-threaded
 # BLAKE3 (350 µs vs 453 µs on an M-series laptop). That is a fact about the chip,
 # not about the algorithm, and benchmarking against it would report a loss the
 # library cannot fix and a caller cannot act on.
 case(
-    name="hash.sum_ · 1 MiB",
+    name="digest.raw · 1 MiB",
     group="ids",
     backend="blake3",
     payload=lambda: _HASH_BLOB,
-    accel=sum_,
+    accel=digest_raw,
     base=lambda p: hashlib.blake2b(p).digest(),
     note="BLAKE3 vs hashlib's BLAKE2b — the stdlib's own BLAKE-family digest",
     equivalent=False,

{unstd-1.1.0 → unstd-2.0.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "unstd"
-version = "1.1.0"
+version = "2.0.0"
 description = "stdlib-faithful accelerated replacements behind optional extras"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -49,7 +49,6 @@ serde = [
   "pybase64>=1.5",
 ]
 ids = [
-  "blake3>=1.0",
   "uuid-utils>=0.17",
 ]
 crypto = [
@@ -69,7 +68,7 @@ model = [
   "pydantic-settings>=2.15",
 ]
 rex = [
-  "irregex>=2.3.0",
+  "irregex>=2.6.0",
 ]
 containers = [
   "sortedcontainers>=2.4",

{unstd-1.1.0 → unstd-2.0.0}/src/unstd/__init__.py

@@ -13,15 +13,17 @@ failing loud where no faithful substitute exists:
 - ``serde`` (``json`` / ``base64``) — ``jsonx`` (orjson) · ``b64`` (pybase64) ·
   ``ndjson`` (newline-delimited, rides ``jsonx``) · ``structs`` (msgspec, no
   stdlib equivalent). Behind the ``serde`` extra; the rest fall back to stdlib.
-- ``ids`` (``hashlib`` / ``uuid``) — ``hash`` (BLAKE3, fails loud) · ``uid``
-  (UUIDv7, falls back to a stdlib generator). Behind the ``ids`` extra.
-- ``crypto`` — BLAKE3 digests, key derivation, keyed MACs and the bearer
+- ``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`` (pure-stdlib clock seam, always available; its
-  protobuf ``Timestamp`` bridge is behind the ``proto`` extra) · ``dateutil``
-  (the ``whenever`` typed-instant seam, behind the ``time`` extra).
+- ``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).
@@ -33,7 +35,7 @@ failing loud where no faithful substitute exists:
 - ``rand`` (``random``) — numpy PCG64 bulk draws; security-sensitive draws stay
   on ``secrets`` regardless of the extra.
 - ``pack`` (``struct``) — numpy bulk pack/unpack.
-- ``clone`` (``copy``) — msgspec round-trip, falls back to ``copy.deepcopy``.
+- ``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.
@@ -43,8 +45,9 @@ failing loud where no faithful substitute exists:
 Import the module, not its members::
 
     from unstd.serde import jsonx, b64, structs, ndjson
-    from unstd.ids import hash, uid
-    from unstd.time import timeutil, dateutil
+    from unstd.ids import uid
+    from unstd.crypto import digest, token
+    from unstd.time import timeutil, zoned
     from unstd.model import StrictModel, FrozenModel, StrictSettings
 """
 

unstd-2.0.0/src/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-1.1.0 → unstd-2.0.0}/src/unstd/audio/README.md

@@ -11,20 +11,20 @@ writer.
 
 | File      | Role                                                                                                            |
 | --------- | ----------------------------------------------------------------------------------------------------------------- |
-| `wavx.py` | `read_wav`/`write_wav` (whole-file) · `read_blocks`/`WavWriter` (streaming) · `wrap_pcm` — numpy-native WAV samples ↔ file. |
+| `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_wav("in.wav")  # float32 in [-1, 1], sr = Hz
-wavx.write_wav("out.wav", samples, sr)  # PCM_16 by default
-ints, sr = wavx.read_wav("in.wav", dtype="int16")  # raw signed 16-bit
+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.WavWriter("out.wav", sr, channels=1) as w:
+with wavx.Writer("out.wav", sr, channels=1) as w:
     for chunk in synth_chunks:
         w.write(chunk)
-for block in wavx.read_blocks("in.wav", blocksize=4096):
+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
@@ -55,13 +55,13 @@ 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 — `WavWriter` / `read_blocks`
+## Streaming — `Writer` / `blocks`
 
-`read_wav`/`write_wav` buffer the whole file; a live pipeline (streaming TTS
-synthesis, STT playback) wants frames as they arrive instead. `WavWriter` is a
+`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; `read_blocks(path, blocksize)` is the read-side generator, `blocksize`
+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
@@ -74,7 +74,7 @@ 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_wav` would decode to an array and re-quantize back, paying two
+`write` would decode to an array and re-quantize back, paying two
 conversions and a quantization step to reproduce its own input.
 
 ## Prior art