v0.3.3 - First PyPI Release: Scale at the Root, Rung Glosses & CLI Recipe

dazzle-loglib v0.3.3

Gate-first diagnostic output for command-line tools: one signed verbosity axis crossed with consumer-declared channels, so -v/-q and --show scan:debug mean the same thing in every adopting project. Part of the DazzleLib stack — the library narrates and selects destinations; it deliberately does not own persistence, parsers, or help text.

This is the project's first GitHub release and first PyPI publication. The library is in alpha: the public surface is tracked (no silent drift — an import-stability canary enforces it) while the wider stack is still moving.

The library at a glance

from dazzle_loglib import ChannelDef, init_output, get_output

init_output(
    verbosity=1,                        # -4 (nothing) .. +5 (debug), 0 = default
    channel_defs=[
        ChannelDef("scan", "Discovery and scanning"),
        ChannelDef("git",  "Git operations"),
    ],
    strict_channels=True,               # unknown channel names fail loud
)

out = get_output()
out.emit(1, "scanned {n} entries", channel="scan", n=42)   # shows at -v
out.emit(2, "guard math: {d}", channel="scan", d=details)  # gated: costs one int compare

A gated call never formats its message. Destinations resolve at emit time (stderr by default), so stream-rebinding hosts (pythonw) and capture harnesses (redirect_stderr, capsys) just work.

What's new in v0.3.3

The verbosity scale is now importable from the package root

VERBOSITY_CONTINUUM, shows, rank_of, and the ten level constants were documented as tracked API but only reachable through submodules. They now live at the root, and verbosity_rungs() returns the scale as data — (name, rank, gloss) per rung, cold to warm — so a --help table is a loop instead of ten hand-copied strings:

  -4  -qqqq  nothing      Nothing at all -- exit code only (CI/headless)
  -3  -qqq   error        Errors only
  -2  -qq    warning      Errors and warnings
  -1  -q     minimal      Results only -- no hints
  +0         default      Default output, result-context hints
  +1  -v     extra        Progress, timing, summary info
  +2  -vv    diagnostics  Diagnostic detail (decision inputs, guard math)
  +3  -vvv   config       Configuration, algorithm selection
  +4  -vvvv  lite-debug   Light debug detail
  +5  -vvvvv debug        Full debug -- internal state, evaluation/call tracing

Glosses are ASCII by contract — they render correctly on Windows codepage 437/1252 consoles.

docs/cli-integration.md — the canonical wiring recipe

The library ships no argparse code by charter (a test enforces the boundary), so this page is where the wiring lives: flag declarations (-v/-q as counts, --show with type=parse_channel_spec for clean argparse errors), resolution precedence (explicit > CLI counts > environment > default), the env-var path for hooks and schedulers, keeping --json stdout byte-identical at every verbosity, and the single add_verbosity_flags() helper each consumer should own.

The recipe is executed by a committed check script, not just written — which is how two of this release's bugs were found.

Fixed: the default destination now resolves lazily

The manager captured sys.stderr at construction instead of storing the 'stderr' sentinel, so the emit-time resolution guarantee did not cover the default destination — the most common case. Hosts that rebind streams after import and harnesses that wrap output mid-run now get the stream that exists when the message is written. Pinned by a regression test.

Fixed: the documented --show round-trip

The integration doc serialized parsed specs with str(s) — the dataclass repr, which does not round-trip, leaving every --show flag silently inert. The recipe now uses the name:level form, the reserved spec slots (DEST:LOCATION:FORMAT) are documented as inert until routing lands, and two regression tests pin the round-trip and doc/recipe agreement.

Stability language: "tracked", not "locked"

docs/api-stability.md now makes the honest claim for a 0.3.x library: no silent drift (test-enforced) rather than no change, and it names where movement is expected — first-consumer adoption, the hierarchical-channel arc, a future CLI library.

Hardened by a mutation sweep

A fresh-context mutation sweep against this release found two mutants the previous 103-test suite could not kill; both were deliberate behavior, now pinned: --verbosity 0 wins outright even though 0 is falsy, and environment rung names resolve case-insensitively (Debug, DIAGNOSTICS). Suite: 107 tests.

Installation

pip install dazzle-loglib

Version history (0.x)

Version	Key change
v0.3.3	Current — scale at the root, rung glosses as data, CLI integration recipe, lazy default destination
v0.3.2	README on the house library pattern
v0.3.1	repokit-common tooling vendored; PEP 440-safe packaging (PIP_VERSION)
v0.3.0	Repository infrastructure — CI, release workflow, issue scaffolding
v0.2.0	Consumer-declared channel registry (ChannelDef), 10-rung signed scale, resolution precedence module, EmitterProtocol injection contract
v0.1.0-alpha	Extraction from the vendored log_lib lineage (Prime-Square-Sum → ghtraf → wtf-restarted → wtf-windows → dazzlecmd)

Earlier versions predate this repository's release history and have no release pages.

Platform support

Platform	Status
Windows 10/11	Tested (primary development platform)
Linux	CI-tested (GitHub Actions, Python 3.10–3.13)
macOS	Expected to work (pure Python, no platform-specific code)

Requirements

• Python >= 3.9 (CI-tested on 3.10–3.13)
• dazzle-lib >= 0.8.0 (the Continuum primitive)