Repository navigation
Commit aee8110
feat(sdk): deprecation sweep + handle→guard + init/init_or_die unification (0.18.5 candidate) (#111)
* updv1
* docs(runtime): strip legacy/pre-fix/post-fix framing
- Remove "pre-fix", "post-fix", "legacy", "back-compat", "previously did",
"was removed", "v3.53 audit" framing from inline comments and docstrings.
- Keep all audit tracking IDs (DEF-*, AUTH-01, ADR-*) — those refer to
external systems and are not legacy framing per se.
- runtime.py -565 lines net (-311 lines of redundant context). 17 files
modified; no functional changes.
- pytest 1405 passed (1 skipped) with -W error::DeprecationWarning.
- Prod smoke @Protect → /execute round-trip ALLOW in 302ms.
* refactor(sdk): strip legacy pre/post-fix framing from docstrings
Removes 'pre-fix/post-fix', 'used to', 'previously', 'now we', and
audit-cycle prose from runtime.py, transport.py, decorators.py,
and 14 other modules. External ticket identifiers (DEF-*, ADR-*,
AUDIT P*, IDEM-01, CLOSE-ORPHAN) are preserved as anchors.
What stays: ticket refs, ADR numbers, date stamps that tag fixes
without prose framing.
What goes: 'pre-fix ... pre-fix this method ... Now we' blocks,
'audit ... previous version ... the prior code' commentary,
'was ... is now' chronology in docstrings.
1405 tests pass; -W error::DeprecationWarning clean.
Co-Authored-By: Claude Code <noreply@anthropic.com>
* refactor(sdk): drop framework extras + auto_instrument public surface
NullRun is a runtime decision layer, not a framework integration
library. The framework auto-instrumentation patches (langchain,
crewai, autogen, langgraph, llama-index, openai-agents) remain
in code as silent auto-detect hooks, but are no longer:
- advertised in pyproject.toml as installable extras
- documented in README as a feature
- exported from the top-level `nullrun` namespace
User-facing install is exactly one line:
pip install nullrun
Public surface cleanup:
- removed `auto_instrument` / `is_auto_instrumented` from
_LAZY_EXPORTS (was internal trigger, not user API)
- removed module-level `track_event` alias (duplicate of
`track`; runtime.track_event method still used internally)
- removed NullRunCallback from _LAZY_EXPORTS (advanced/manual
path; reachable via `nullrun.toolbox.langgraph` if ever needed)
README changes:
- dropped 'Framework adapters — auto-detected' section
- dropped framework-specific Examples bullets (langgraph,
crewai, autogen, llama-index)
- rewrote headline to 'works with any LLM SDK that uses httpx'
pyproject.toml: removed [agents], [langchain], [langgraph],
[llama-index], [crewai], [autogen] optional-dependency groups.
Kept [opentelemetry] (industry standard, not a framework) and [dev].
Co-Authored-By: Claude Code <noreply@anthropic.com>
* refactor(sdk): drop redundant @guarded decorator
The @nullrun.guarded decorator was a 3-line syntactic shortcut for
`with nullrun.handle()`. With handle() the canonical user-facing
error-translation path and zero production examples using the
decorator form, @guarded was pure duplication.
Removes:
- def guarded() from src/nullrun/_handle.py
- "guarded" from _LAZY_EXPORTS and __all__ in __init__.py
- 4 test_guarded_* tests from test_handle.py + test_dev_error_report.py
- dead import in examples/tools/synthetic_sdk_load.py
- examples/CONTRIBUTING.md doc reference
Adds:
- tests/test_init_or_die.py — splits init_or_die tests out of
test_handle.py so the two surfaces no longer share a file
Net: -520 lines, one way to translate NullRunError instead of two.
Co-Authored-By: Claude Code <noreply@anthropic.com>
* feat(sdk): auto-register atexit shutdown + unify init/init_or_die (0.18.3)
Surface changes (breaking):
* `nullrun.init_or_die()` removed. CLI fail-fast is now a parameter
on `init()`: `nullrun.init(fail_on_exit=True)` prints the same
four-line developer report and `sys.exit(1)` on configuration
failure. Default `init()` keeps embedder-friendly raise semantics.
* `nullrun.shutdown()` is auto-registered via `atexit` inside
`init()` so long-running scripts get a clean WS close on process
exit without an explicit call. Calling `shutdown()` manually
remains safe and idempotent.
Implementation:
* `init()` gains `fail_on_exit: bool = False`; the missing-API-key
branch renders the dev-error report and exits 1 when True,
otherwise raises `NullRunAuthenticationError` as before.
* `init()` registers `shutdown` with `atexit` guarded by a module-
level `_shutdown_atexit_registered` flag (no double-stack).
* `shutdown()` resets that flag so a `shutdown() → init()` cycle
re-registers cleanly for the new runtime.
Test coverage:
* `tests/test_init_or_die.py` replaced with
`tests/test_init_fail_on_exit.py` (3 tests, stubbed runtime).
* `tests/test_init_contract.py::TestInitRegistersAtexitShutdown`
added (3 tests, stubbed runtime, no network).
* `tests/test_handle.py` drops the `init_or_die` smoke assertion.
Docs:
* README Quickstart + `shutdown` docstring: no manual `atexit` call.
* `docs/errors/NR-C001.md`: no `init_or_die` mention.
* `CHANGELOG.md` 0.18.3 entry documents both breaking changes.
* `pyproject.toml` bumped to 0.18.3.
All 1403 tests pass. Ruff clean on touched files.
Co-Authored-By: Claude Code <noreply@anthropic.com>
* feat(sdk): rename handle->guard and drop top-level status() (0.18.4)
Surface changes (breaking):
* `nullrun.handle` renamed to `nullrun.guard`. Same `@contextmanager`
body (catches `NullRunError`, re-raises `WorkflowKilledInterrupt`,
renders the four-line developer report, `sys.exit(1)` on failure).
The verb `guard` was freed in 0.18.2 (f1721f2) when `@guarded`
was removed and reads as a single verb alongside `init` /
`shutdown` / `on_error`. Migrate by replacing
`from nullrun import handle` with `from nullrun import guard`
and `with nullrun.handle:` with `with nullrun.guard():`.
* Top-level `nullrun.status()` removed. Reach the snapshot via
`nullrun.get_runtime().status()` (returns the same frozen
`NullRunStatus` dataclass). The wrapper's only role was raising
`NullRunConfigError(NR-C004)` when no runtime was bound — that
path is now `get_runtime()`'s job.
Curated surface after 0.18.4: 20 names (was 21 in 0.18.3 — net -1
because `handle`->`guard` is in-place and `status` is removed).
Implementation:
* `src/nullrun/_handle.py`: rename `handle` -> `guard` (function
body unchanged). Module file name stays `_handle.py` for the
submodule-shadowing reason documented in that file's docstring
(only the public function name is `guard`, the module file name
is observable to no external caller — only `from nullrun import
guard` is the public surface).
* `src/nullrun/__init__.py`: drop `def status():` (47 lines); rename
`handle` -> `guard` in `_LAZY_EXPORTS` and `__all__`; update the
module docstring + `_LAZY_EXPORTS` comment blocks accordingly.
* `docs/errors/NR-C004.md`: replace `nullrun.status()` references
with `nullrun.get_runtime()` / `runtime.status()`; add a 0.18.4
note at the top calling out the wrapper removal.
Test coverage:
* Rename `tests/test_handle.py` -> `tests/test_guard.py`
(7 -> 7 tests, identical body, mechanical rename + a new
`test_handle_removed_from_public_surface` regression guard).
* Rewrite `tests/test_status.py`: 23 of 24 sites moved from
`nullrun.status()` to `rt.status()` on the local runtime. The
`TestNoRuntime` class (2 tests) is dropped — the contract it
pinned no longer exists without the top-level wrapper.
The `TestPublicAPI` class (3 tests) becomes
`TestStatusRemovedFromTopLevel` (2 regression-guard tests
asserting `status` is NOT in `dir(nullrun)` or `__all__`).
* `tests/test_dev_error_report.py`: handle -> guard throughout
(4 tests renamed, bodies unchanged).
All 1401 tests pass on Python 3.11 / Windows. Ruff clean on all
touched files. Coverage regenerates to 81.34% (above the
`fail_under = 80` gate) after dropping the stale `.coverage`
file that referenced a removed `extractor.py`.
Co-Authored-By: Claude Code <noreply@anthropic.com>
* fix(sdk): follow-up 0.18.4 rename sweep in docs/scripts
Sweep for any remaining stale references to the renamed
nullrun.handle / nullrun.status() symbols after the
0.18.4 cleanup (83421e0):
* scripts/smoke_prod.py — drop status import (F401), switch
the call site to nullrun.get_runtime().status().
* src/nullrun/__init__.py — comment about the CLI fail-fast
dev-error report: handle() → guard().
* src/nullrun/messages.py — NR-W004 docstring: nullrun.handle
→ nullrun.guard.
* tests/test_init_fail_on_exit.py — module docstring: handle()
→ guard().
* tests/test_messages.py — NR-W004 test docstring: handle()
→ guard().
* tests/test_typed_exceptions_full_audit.py — disambiguate the
comment from nullrun.handle() to ActionHandler.handle()
so readers do not confuse the action-handler method (still
present) with the renamed context manager (removed).
Verified post-edit:
* pytest: 1401 passed, 1 skipped (no regressions)
* ruff on all touched files: clean (smoke_prod.py went from 3
pre-existing ruff errors to 2; the F401 on the now-removed
status import is gone; the remaining F401 on_error
and F841 decision_payload are pre-existing on master).
* Public surface: handle=False, status=False, guard=True,
__all__ length 20 (matches 0.18.4 design).
* guard() works as a context manager and re-raises
WorkflowKilledInterrupt (BaseException propagates).
* Prod smoke against https://api.nullrun.io: @Protect round-trip
returns 'echo(hello-0.18.4)'; guard() renders the
four-line developer report and exits 1 on a NullRunError.
Co-Authored-By: Claude Code <noreply@anthropic.com>
* docs(sdk): drop stale init_or_die references in source docstrings
Follow-up to ccb2670 (0.18.3: init_or_die removal) and the 0.18.4
rename sweep. Two stale source-code comments still referenced
init_or_die by name even though the function was removed:
* src/nullrun/_handle.py: the docstring at the head of the module
explained how guard differs from the old init_or_die wrapper.
Rewrite to point at init(fail_on_exit=True) only — the historical
aside belongs in CHANGELOG.md, not next to guard's own contract.
* src/nullrun/decorators.py:339: the lazy auto-instrument comment
described a user who writes '@nullrun.protect without calling
init_or_die() first' would still get a runtime. The actual surface
is init() — the comment now reads correctly.
Functional code untouched. All 1401 tests pass on Python 3.11.
ruff check is clean on the touched hunks; pre-existing F401 in
decorators.py:43 (warnings import) and pre-existing ruff-format
whitespace around lines I did not touch are unrelated to this
change and remain for a separate follow-up.
* chore(sdk): remove unused imports + fix mypy errors leftover from deprecation sweep
Mechanical cleanup so ruff check src tests + mypy src/nullrun are
clean on the cleanup/deprecation-removal branch before merging to
master.
- 71 F401 (unused imports) auto-fixed by 'ruff check --fix'.
- 9 F841 (unused local variables) hand-removed across tests; all
were dead code left behind after deleted imports and refactored
helpers (initial_buffer_len in test_transport, finalize_objs and
t_id in test_signal_safety, first_orig in test_autogen_patch,
existing_fp in test_dedup, req in test_model_fallback, reg in
test_registry, sid in test_actions, timestamp in
test_ws_signed_payload).
- src/nullrun/business_impact.py: narrow BusinessImpact.impact from
Any to NoImpactPayload — the inline comment already documented
the invariant ('Only NoImpactPayload in 0.18.2') and the only
public ctor (BusinessImpact.no_impact) wires a NoImpactPayload,
so the broader Any was masking a real no-any-return at the
to_wire_dict boundary.
- src/nullrun/__init__.py: tighten _LAZY_EXPORTS annotation from
tuple[str, str | None] to tuple[str, str] — every value in the
table is a 2-tuple of module path + attribute name, so the
optional was wrong and the downstream list[str] for
__import__()'s fromlist tripped list-item mypy.
Verification:
ruff check src tests : All checks passed
mypy src/nullrun : Success: no issues found in 36 source files
pytest -q : 1401 passed, 1 skipped
---------
Co-authored-by: Claude Code <noreply@anthropic.com>1 parent ca83ec6 commit aee8110
107 files changed
Lines changed: 1892 additions & 15706 deletions
File tree
- docs/errors
- scripts
- src/nullrun
- breaker
- instrumentation
- integrations
- observability
- toolbox
- tests
- contract
Some content is hidden
Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.
Large diffs are not rendered by default.
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
5 | 5 | | |
6 | 6 | | |
7 | 7 | | |
8 | | - | |
9 | | - | |
| 8 | + | |
10 | 9 | | |
11 | 10 | | |
12 | 11 | | |
| |||
63 | 62 | | |
64 | 63 | | |
65 | 64 | | |
66 | | - | |
| 65 | + | |
67 | 66 | | |
68 | 67 | | |
69 | 68 | | |
| |||
211 | 210 | | |
212 | 211 | | |
213 | 212 | | |
214 | | - | |
| 213 | + | |
| 214 | + | |
| 215 | + | |
| 216 | + | |
215 | 217 | | |
216 | | - | |
217 | | - | |
218 | | - | |
219 | | - | |
| 218 | + | |
| 219 | + | |
| 220 | + | |
| 221 | + | |
| 222 | + | |
220 | 223 | | |
221 | | - | |
222 | | - | |
223 | | - | |
224 | | - | |
225 | | - | |
226 | | - | |
227 | | - | |
228 | | - | |
229 | | - | |
230 | | - | |
231 | | - | |
232 | | - | |
233 | | - | |
234 | | - | |
235 | | - | |
236 | | - | |
237 | | - | |
238 | | - | |
239 | | - | |
240 | | - | |
241 | 224 | | |
242 | 225 | | |
243 | 226 | | |
| |||
336 | 319 | | |
337 | 320 | | |
338 | 321 | | |
339 | | - | |
340 | | - | |
341 | | - | |
342 | | - | |
343 | 322 | | |
344 | 323 | | |
345 | 324 | | |
| |||
This file was deleted.
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
28 | 28 | | |
29 | 29 | | |
30 | 30 | | |
31 | | - | |
| 31 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
16 | 16 | | |
17 | 17 | | |
18 | 18 | | |
19 | | - | |
20 | | - | |
21 | | - | |
22 | | - | |
| 19 | + | |
| 20 | + | |
| 21 | + | |
| 22 | + | |
23 | 23 | | |
24 | 24 | | |
25 | 25 | | |
| |||
64 | 64 | | |
65 | 65 | | |
66 | 66 | | |
67 | | - | |
| 67 | + | |
68 | 68 | | |
69 | 69 | | |
70 | 70 | | |
| |||
75 | 75 | | |
76 | 76 | | |
77 | 77 | | |
78 | | - | |
| 78 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
1 | | - | |
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
2 | 8 | | |
3 | 9 | | |
4 | 10 | | |
5 | 11 | | |
6 | 12 | | |
7 | 13 | | |
8 | 14 | | |
9 | | - | |
| 15 | + | |
10 | 16 | | |
11 | 17 | | |
12 | 18 | | |
13 | | - | |
14 | | - | |
15 | | - | |
| 19 | + | |
| 20 | + | |
| 21 | + | |
| 22 | + | |
16 | 23 | | |
17 | 24 | | |
18 | 25 | | |
| |||
22 | 29 | | |
23 | 30 | | |
24 | 31 | | |
25 | | - | |
| 32 | + | |
26 | 33 | | |
27 | | - | |
| 34 | + | |
| 35 | + | |
28 | 36 | | |
29 | 37 | | |
30 | 38 | | |
31 | 39 | | |
32 | 40 | | |
33 | 41 | | |
34 | 42 | | |
35 | | - | |
| 43 | + | |
36 | 44 | | |
37 | 45 | | |
38 | 46 | | |
39 | 47 | | |
40 | 48 | | |
41 | 49 | | |
| 50 | + | |
42 | 51 | | |
43 | 52 | | |
44 | | - | |
| 53 | + | |
| 54 | + | |
45 | 55 | | |
46 | 56 | | |
47 | | - | |
| 57 | + | |
48 | 58 | | |
49 | 59 | | |
50 | 60 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
27 | 27 | | |
28 | 28 | | |
29 | 29 | | |
30 | | - | |
| 30 | + | |
31 | 31 | | |
32 | 32 | | |
33 | 33 | | |
| |||
44 | 44 | | |
45 | 45 | | |
46 | 46 | | |
47 | | - | |
48 | 47 | | |
49 | 48 | | |
50 | 49 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
6 | 6 | | |
7 | 7 | | |
8 | 8 | | |
9 | | - | |
| 9 | + | |
10 | 10 | | |
11 | 11 | | |
12 | 12 | | |
| |||
71 | 71 | | |
72 | 72 | | |
73 | 73 | | |
| 74 | + | |
| 75 | + | |
74 | 76 | | |
75 | 77 | | |
76 | 78 | | |
77 | 79 | | |
78 | | - | |
79 | | - | |
80 | | - | |
81 | | - | |
82 | | - | |
83 | | - | |
84 | | - | |
85 | | - | |
86 | | - | |
87 | | - | |
88 | | - | |
89 | | - | |
90 | | - | |
91 | | - | |
92 | | - | |
93 | | - | |
94 | | - | |
95 | | - | |
96 | | - | |
97 | | - | |
98 | | - | |
99 | | - | |
100 | | - | |
101 | | - | |
102 | | - | |
103 | | - | |
104 | | - | |
105 | | - | |
106 | | - | |
107 | | - | |
108 | | - | |
109 | | - | |
110 | | - | |
111 | | - | |
112 | | - | |
113 | | - | |
114 | | - | |
115 | | - | |
116 | | - | |
117 | | - | |
118 | 80 | | |
119 | 81 | | |
120 | 82 | | |
| |||
463 | 425 | | |
464 | 426 | | |
465 | 427 | | |
466 | | - | |
467 | | - | |
468 | | - | |
469 | | - | |
470 | | - | |
471 | | - | |
472 | | - | |
473 | | - | |
474 | | - | |
475 | | - | |
| 428 | + | |
| 429 | + | |
| 430 | + | |
| 431 | + | |
| 432 | + | |
| 433 | + | |
476 | 434 | | |
477 | 435 | | |
478 | | - | |
479 | 436 | | |
480 | | - | |
481 | | - | |
| 437 | + | |
482 | 438 | | |
483 | 439 | | |
484 | 440 | | |
| |||
0 commit comments