Cleanup: assorted consistency & dead-code fixes (exhaustiveness, ExecHook provenance, type:ignore, lazy imports, en-GB, dead aliases)

[lodyai]

Summary

A cluster of small, individually-trivial consistency and dead-code fixes
surfaced by the refactoring audit. Grouped here as one gated cleanup; each is a
checklist item.

Tasks

• get_stream_backend exhaustiveness (cuprum/_backend.py:148-165) —
  the match requested: has no case _ and no terminal raise, so a future
  enum member falls off the end returning None typed as StreamBackend. Add
  case _: raise AssertionError(f"unreachable backend {requested!r}").
• ExecHook provenance (cuprum/__init__.py:45) — ExecHook is
  re-exported from cuprum.context though it is defined in cuprum.events:84,
  while ExecEvent is imported from cuprum.events. Import both from their
  definition site; drop ExecHook from context's public re-export.
• Spurious # type: ignore[assignment] (cuprum/logging_hooks.py:43-44)
  — fields are typed HookRegistration | None, so assigning None should not
  need the ignore. Verify and remove (or narrow with a specific reason).
• Dead FD aliases (cuprum/_pipeline_streams.py:103-110) —
  _extract_reader_fd / _extract_writer_fd are pure pass-throughs to
  _extract_stream_fd. Inline at the two call sites and delete.
• Lazy in-function imports / import cycle — the pipeline modules use
  in-function imports and a _sh_module() sys.modules service-locator
  (cuprum/_pipeline_internals.py:40-45; also _pipeline_config.py:49,
  _pipeline_stage_streams.py:62,84, _process_lifecycle.py:140,187-188) to
  dodge a real cycle. Relocate the shared dataclasses (_StageObservation,
  _EventDetails, result types) into a dependency-free leaf module so these
  become normal top-level imports, and delete the _pipeline_spawn.py re-export
  shim.
• en-GB spelling — cuprum/adapters/logging_adapter.py:96
  "Programme" -> "Program"; align mixed serialise / serializable prose to
  en-GB-oxendict (identifiers may stay ecosystem-standard).

Verification

• make check-fmt lint test green; make markdownlint for any doc touched.

References

• Cuprum refactoring audit — consistency / dead-code / smaller items.

[coderabbitai]

🔗 Related PRs

#55 - Guard tee backend selector reentry (#53) [merged]
leynos/netsuke#302 - Overhaul Netsuke CLI documentation contract [merged]
leynos/beatcue#10 - Run Pylint through the PyPy shim [merged]
leynos/agent-template-python#12 - Align Python template docs and scripting guidance with cuprum standards [merged]
#98 - Refresh repository documentation standards [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

✅ Successfully generated implementation plan.

💡 Use @coderabbitai <feedback> to replan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[coderabbitai]

Coding Plan

Summary

• Phase 1 tackles three isolated, single-file fixes (exhaustiveness, type ignores, spelling) that carry no risk of cross-module breakage.
• Phase 2 corrects ExecHook provenance and inlines dead FD aliases, updating the affected test patches to target the underlying helper.
• Phase 3 extracts shared pipeline dataclasses into a new leaf module _pipeline_types.py, converting all deferred and in-function imports to standard top-level imports and removing the now-obsolete _pipeline_spawn.py shim.

Design Choices

Design Choice 1: Test patch target after inlining FD aliases

Options Considered:

1. Patch _extract_stream_fd instead (affects all callers uniformly).
2. Introduce a new _fd_from_reader/_fd_from_writer pair solely for test seams.
3. Have tests patch _fd_from_transport, the lowest-level helper.

Chosen Option: 1

Rationale: Patching _extract_stream_fd is the simplest change; the tests already supply lambdas ignoring their argument, so behaviour is identical.

Design Choice 2: Leaf-module name for shared pipeline types

Options Considered:

1. _pipeline_types.py — mirrors the _types.py convention used elsewhere.
2. _pipeline_dataclasses.py — more explicit but verbose.

Chosen Option: 1

Rationale: _pipeline_types.py aligns with existing naming conventions and is succinct.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Quick Standalone Fixes

Address the three items that touch isolated code paths with no cross-file dependencies.

Task 1: Add match exhaustiveness to `get_stream_backend`

Ensure the match requested: statement cannot silently return None if the StreamBackend enum gains a new member.

• Open cuprum/_backend.py
• Append a catch-all arm after the case StreamBackend.AUTO: block:

  case _:
      raise AssertionError(f"unreachable backend {requested!r}")
  

• Confirm the function's return type remains StreamBackend (no | None)

Task 2: Remove spurious type-ignore comments in `logging_hooks.py`

The detach() method assigns None to fields already typed HookRegistration | None; the ignores are redundant.

• Open cuprum/logging_hooks.py
• Delete # type: ignore[assignment] from lines 43 and 44
• Run type-checker locally to confirm no new errors surface

Task 3: Correct en-GB spelling in `logging_adapter.py`

Align docstring prose with en-GB-oxendict rules whilst leaving identifiers in ecosystem-standard American spelling where appropriate.

• Line 93: change Programme being executed → Program being executed (matches the identifier cuprum_program)
• Line 203: rename the function _json_serializable → _json_serialisable
• Line 198: update the call site to _json_serialisable(value)
• Leave the docstring verb serialises unchanged (already correct)

🤖 Prompt for AI agents

Implement three isolated, single-file fixes across `_backend.py`,
`logging_hooks.py`, and `logging_adapter.py` — no cross-module changes are
required.

**Task 1: `cuprum/_backend.py` — match exhaustiveness**
- Locate the `match requested:` statement inside `get_stream_backend`
- Append a catch-all arm immediately after the `case StreamBackend.AUTO:` block:
  ~~~
  case _:
      raise AssertionError(f"unreachable backend {requested!r}")
  ~~~
- Verify the function's declared return type is `StreamBackend` with no `| None`
widening

**Task 2: `cuprum/logging_hooks.py` — remove spurious type-ignore comments**
- Delete `# type: ignore[assignment]` from lines 43 and 44 of the `detach()`
method
- The fields are already typed `HookRegistration | None`, so assigning `None` is
valid without suppression

**Task 3: `cuprum/logging_adapter.py` — en-GB spelling corrections**
- Line 93: replace `Programme being executed` with `Program being executed`
(aligns with the `cuprum_program` identifier)
- Line 203: rename the function `_json_serializable` → `_json_serialisable`
- Line 198: update the call site to use `_json_serialisable(value)`
- Leave the docstring verb `serialises` untouched (already correct)

Phase 2: Import Provenance and Dead-Alias Removal

Correct the re-export chain for ExecHook and inline the redundant FD-extraction wrappers.

Task 1: Import `ExecHook` from its definition site

ExecHook is defined in events.py yet reaches __init__.py via context.py. Import directly from events and drop the public re-export from context.

• cuprum/__init__.py:
  • Remove ExecHook from the from cuprum.context import (…) block (line 45)
  • Add ExecHook to the existing from cuprum.events import (…) block (around line 60)
• cuprum/context.py:
  • Keep the internal from cuprum.events import ExecHook (line 56) — it is still used for field annotations
  • Remove "ExecHook" from __all__ (line 793)

Task 2: Inline dead FD-extraction aliases

_extract_reader_fd and _extract_writer_fd are one-liner pass-throughs to _extract_stream_fd. Inline them and update tests.

• cuprum/_pipeline_streams.py:
  • Lines 275–276 inside _try_rust_pump_hop: replace the two calls with direct invocations of _extract_stream_fd(reader) and _extract_stream_fd(writer)
  • Delete the wrapper definitions at lines 103–110
• cuprum/unittests/test_pipeline_stream_backend_selection.py:
  • Lines 219–224 and 385–390: change the two monkeypatch.setattr calls per site to patch "_extract_stream_fd" instead, returning the appropriate FD value

🤖 Prompt for AI agents

Fix `ExecHook` import provenance and inline the dead FD-extraction aliases
across `__init__.py`, `context.py`, `_pipeline_streams.py`, and the associated
test file.

**Task 1: `ExecHook` re-export provenance — `cuprum/__init__.py` and
`cuprum/context.py`**
- In `cuprum/__init__.py`:
  - Remove `ExecHook` from the `from cuprum.context import (…)` block (line 45)
- Add `ExecHook` to the existing `from cuprum.events import (…)` block (around
line 60)
- In `cuprum/context.py`:
- Retain the internal `from cuprum.events import ExecHook` (line 56) — it
remains required for field annotations
  - Remove `"ExecHook"` from `__all__` (line 793)

**Task 2: Inline `_extract_reader_fd` / `_extract_writer_fd` —
`cuprum/_pipeline_streams.py`**
- Inside `_try_rust_pump_hop` at lines 275–276, replace calls to
`_extract_reader_fd(reader)` and `_extract_writer_fd(writer)` with direct calls
to `_extract_stream_fd(reader)` and `_extract_stream_fd(writer)`
- Delete the wrapper function definitions at lines 103–110

**Task 3: Update test patches —
`cuprum/unittests/test_pipeline_stream_backend_selection.py`**
- At lines 219–224 and 385–390, update the two `monkeypatch.setattr` calls per
site to target `"_extract_stream_fd"` instead of the now-deleted aliases
- The lambda return values remain unchanged

Phase 3: Eliminate Import-Cycle Workarounds

Extract shared dataclasses into a dependency-free leaf module, convert deferred imports to normal top-level imports, and delete the re-export shim.

Task 1: Create `_pipeline_types.py` leaf module

Centralise the shared dataclasses that downstream modules currently import via in-function or TYPE_CHECKING hacks.

• Create cuprum/_pipeline_types.py
• Move the following definitions verbatim from cuprum/_pipeline_internals.py:
  • _ExecutionHooks dataclass
  • _StageObservation dataclass (depends on _ExecutionHooks, _emit_exec_event, ExecEvent)
  • _EventDetails dataclass
• Import only from:
  • cuprum._observability (_emit_exec_event, _freeze_str_mapping, _merge_tags, _wait_for_exec_hook_tasks)
  • cuprum.context (current_context)
  • cuprum.events (ExecEvent)
  • Standard library (asyncio, dataclasses, time, typing)
  • Under TYPE_CHECKING: cuprum.sh types (SafeCmd, AfterHook, BeforeHook, ExecHook)
• Add an __all__ listing all exported symbols

Task 2: Update `_pipeline_internals.py` to import from the leaf module

Remove the relocated dataclass definitions and convert any deferred imports to top-level.

• Delete the class definitions for _ExecutionHooks, _StageObservation, _EventDetails
• Add a top-level import:

  from cuprum._pipeline_types import _ExecutionHooks, _StageObservation, _EventDetails
  

• Keep _run_before_hooks and other orchestration logic in place; they now reference the imported classes
• Delete the _sh_module() helper (lines 40–45) — it is no longer needed once the cycle is broken
• Replace any internal _sh_module().X calls with standard imports (import cuprum.sh types under TYPE_CHECKING where only annotations are required, or at top-level where runtime access is needed)

Task 3: Convert deferred imports in `_pipeline_stage_streams.py`

Replace in-function imports with top-level imports now that _pipeline_types.py exists.

• Add to top-level imports:

  from cuprum._pipeline_types import _EventDetails, _StageObservation
  

• Remove the TYPE_CHECKING-guarded import of _StageObservation from _pipeline_internals
• Delete the two in-function from cuprum._pipeline_internals import _EventDetails statements inside the stderr_on_line and stdout_on_line closures (lines 62, 84)

Task 4: Convert deferred imports in `_process_lifecycle.py`

Same treatment: top-level imports replace in-function cycle-avoidance.

• Add to top-level imports:

  from cuprum._pipeline_types import _EventDetails, _StageObservation
  

• Import _run_before_hooks at top level from _pipeline_internals (it no longer causes a cycle)
• Import _create_stage_capture_tasks at top level from _pipeline_streams
• Delete the in-function imports at lines 140, 187–188

Task 5: Convert deferred import in `_pipeline_config.py`

The _sh_module() call is now unnecessary.

• Remove the in-function from cuprum._pipeline_internals import _sh_module (line 49)
• Import cuprum.sh at top level (or the specific symbol ExecutionContext if that is all that is needed)
• Update _prepare_pipeline_config to use the direct import

Task 6: Delete `_pipeline_spawn.py` re-export shim

The shim exists solely to give _pipeline_internals a cycle-safe import point. With the cycle resolved, importers can go directly to _process_lifecycle.

• Delete cuprum/_pipeline_spawn.py
• In cuprum/_pipeline_internals.py, change:

  from cuprum._pipeline_spawn import _spawn_pipeline_processes
  

  to:

  from cuprum._process_lifecycle import _spawn_pipeline_processes
  

• Search the codebase for any other imports from _pipeline_spawn and redirect them similarly

🤖 Prompt for AI agents

Break the diamond import cycle by creating a new leaf module
`cuprum/_pipeline_types.py`, migrating shared dataclasses into it, converting
all deferred imports to top-level imports, and deleting the now-obsolete
`_pipeline_spawn.py` shim.

**Task 1: Create `cuprum/_pipeline_types.py`**
- Move `_ExecutionHooks`, `_StageObservation`, and `_EventDetails` verbatim from
`cuprum/_pipeline_internals.py`
- Restrict imports to: `cuprum._observability` (`_emit_exec_event`,
`_freeze_str_mapping`, `_merge_tags`, `_wait_for_exec_hook_tasks`),
`cuprum.context` (`current_context`), `cuprum.events` (`ExecEvent`), the
standard library (`asyncio`, `dataclasses`, `time`, `typing`), and — under
`TYPE_CHECKING` only — `cuprum.sh` types (`SafeCmd`, `AfterHook`, `BeforeHook`,
`ExecHook`)
- Declare `__all__` listing every exported symbol

**Task 2: Update `cuprum/_pipeline_internals.py`**
- Delete the class definitions for `_ExecutionHooks`, `_StageObservation`,
`_EventDetails`
- Add at top-level:
  ~~~
from cuprum._pipeline_types import _ExecutionHooks, _StageObservation,
_EventDetails
  ~~~
- Delete the `_sh_module()` helper (lines 40–45)
- Replace all `_sh_module().X` call sites with direct standard imports of
`cuprum.sh` symbols (under `TYPE_CHECKING` for annotations; at top-level for
runtime use)
- Retain `_run_before_hooks` and all other orchestration logic

**Task 3: Update `cuprum/_pipeline_stage_streams.py`**
- Add at top-level:
  ~~~
  from cuprum._pipeline_types import _EventDetails, _StageObservation
  ~~~
- Remove the `TYPE_CHECKING`-guarded import of `_StageObservation` from
`_pipeline_internals`
- Delete the two in-function `from cuprum._pipeline_internals import
_EventDetails` statements inside the `stderr_on_line` and `stdout_on_line`
closures (lines 62, 84)

**Task 4: Update `cuprum/_process_lifecycle.py`**
- Add at top-level:
  ~~~
  from cuprum._pipeline_types import _EventDetails, _StageObservation
  ~~~
- Import `_run_before_hooks` at top-level from `_pipeline_internals`
- Import `_create_stage_capture_tasks` at top-level from `_pipeline_streams`
- Delete the in-function imports at lines 140, 187–188

**Task 5: Update `cuprum/_pipeline_config.py`**
- Remove the in-function `from cuprum._pipeline_internals import _sh_module`
(line 49)
- Import `cuprum.sh` (or the specific symbol `ExecutionContext`) at top-level
- Update `_prepare_pipeline_config` to reference the direct import

**Task 6: Delete `cuprum/_pipeline_spawn.py`**
- Delete the file entirely
- In `cuprum/_pipeline_internals.py`, replace:
  ~~~
  from cuprum._pipeline_spawn import _spawn_pipeline_processes
  ~~~
  with:
  ~~~
  from cuprum._process_lifecycle import _spawn_pipeline_processes
  ~~~
- Search the entire codebase for any remaining imports from `_pipeline_spawn`
and redirect them to `_process_lifecycle`

Research

Cuprum is an async subprocess orchestration library. Pipeline execution flows through _pipeline_internals.py (orchestration), _process_lifecycle.py (spawn/cleanup), and _pipeline_streams.py (stream wiring). A diamond import cycle currently forces deferred in-function imports and a _sh_module() service-locator pattern. Public symbols are re-exported through cuprum/__init__.py, with ExecHook taking an indirect route via context.py even though it is defined in events.py. The adapters/ package provides structured-logging, metrics, and tracing integrations.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Implement three isolated, single-file fixes across `_backend.py`,
`logging_hooks.py`, and `logging_adapter.py` — no cross-module changes are
required.

**Task 1: `cuprum/_backend.py` — match exhaustiveness**
- Locate the `match requested:` statement inside `get_stream_backend`
- Append a catch-all arm immediately after the `case StreamBackend.AUTO:` block:
  ~~~
  case _:
      raise AssertionError(f"unreachable backend {requested!r}")
  ~~~
- Verify the function's declared return type is `StreamBackend` with no `| None`
widening

**Task 2: `cuprum/logging_hooks.py` — remove spurious type-ignore comments**
- Delete `# type: ignore[assignment]` from lines 43 and 44 of the `detach()`
method
- The fields are already typed `HookRegistration | None`, so assigning `None` is
valid without suppression

**Task 3: `cuprum/logging_adapter.py` — en-GB spelling corrections**
- Line 93: replace `Programme being executed` with `Program being executed`
(aligns with the `cuprum_program` identifier)
- Line 203: rename the function `_json_serializable` → `_json_serialisable`
- Line 198: update the call site to use `_json_serialisable(value)`
- Leave the docstring verb `serialises` untouched (already correct)
===============================================================================

Task: 2

Fix `ExecHook` import provenance and inline the dead FD-extraction aliases
across `__init__.py`, `context.py`, `_pipeline_streams.py`, and the associated
test file.

**Task 1: `ExecHook` re-export provenance — `cuprum/__init__.py` and
`cuprum/context.py`**
- In `cuprum/__init__.py`:
  - Remove `ExecHook` from the `from cuprum.context import (…)` block (line 45)
- Add `ExecHook` to the existing `from cuprum.events import (…)` block (around
line 60)
- In `cuprum/context.py`:
- Retain the internal `from cuprum.events import ExecHook` (line 56) — it
remains required for field annotations
  - Remove `"ExecHook"` from `__all__` (line 793)

**Task 2: Inline `_extract_reader_fd` / `_extract_writer_fd` —
`cuprum/_pipeline_streams.py`**
- Inside `_try_rust_pump_hop` at lines 275–276, replace calls to
`_extract_reader_fd(reader)` and `_extract_writer_fd(writer)` with direct calls
to `_extract_stream_fd(reader)` and `_extract_stream_fd(writer)`
- Delete the wrapper function definitions at lines 103–110

**Task 3: Update test patches —
`cuprum/unittests/test_pipeline_stream_backend_selection.py`**
- At lines 219–224 and 385–390, update the two `monkeypatch.setattr` calls per
site to target `"_extract_stream_fd"` instead of the now-deleted aliases
- The lambda return values remain unchanged
===============================================================================

Task: 3

Break the diamond import cycle by creating a new leaf module
`cuprum/_pipeline_types.py`, migrating shared dataclasses into it, converting
all deferred imports to top-level imports, and deleting the now-obsolete
`_pipeline_spawn.py` shim.

**Task 1: Create `cuprum/_pipeline_types.py`**
- Move `_ExecutionHooks`, `_StageObservation`, and `_EventDetails` verbatim from
`cuprum/_pipeline_internals.py`
- Restrict imports to: `cuprum._observability` (`_emit_exec_event`,
`_freeze_str_mapping`, `_merge_tags`, `_wait_for_exec_hook_tasks`),
`cuprum.context` (`current_context`), `cuprum.events` (`ExecEvent`), the
standard library (`asyncio`, `dataclasses`, `time`, `typing`), and — under
`TYPE_CHECKING` only — `cuprum.sh` types (`SafeCmd`, `AfterHook`, `BeforeHook`,
`ExecHook`)
- Declare `__all__` listing every exported symbol

**Task 2: Update `cuprum/_pipeline_internals.py`**
- Delete the class definitions for `_ExecutionHooks`, `_StageObservation`,
`_EventDetails`
- Add at top-level:
  ~~~
from cuprum._pipeline_types import _ExecutionHooks, _StageObservation,
_EventDetails
  ~~~
- Delete the `_sh_module()` helper (lines 40–45)
- Replace all `_sh_module().X` call sites with direct standard imports of
`cuprum.sh` symbols (under `TYPE_CHECKING` for annotations; at top-level for
runtime use)
- Retain `_run_before_hooks` and all other orchestration logic

**Task 3: Update `cuprum/_pipeline_stage_streams.py`**
- Add at top-level:
  ~~~
  from cuprum._pipeline_types import _EventDetails, _StageObservation
  ~~~
- Remove the `TYPE_CHECKING`-guarded import of `_StageObservation` from
`_pipeline_internals`
- Delete the two in-function `from cuprum._pipeline_internals import
_EventDetails` statements inside the `stderr_on_line` and `stdout_on_line`
closures (lines 62, 84)

**Task 4: Update `cuprum/_process_lifecycle.py`**
- Add at top-level:
  ~~~
  from cuprum._pipeline_types import _EventDetails, _StageObservation
  ~~~
- Import `_run_before_hooks` at top-level from `_pipeline_internals`
- Import `_create_stage_capture_tasks` at top-level from `_pipeline_streams`
- Delete the in-function imports at lines 140, 187–188

**Task 5: Update `cuprum/_pipeline_config.py`**
- Remove the in-function `from cuprum._pipeline_internals import _sh_module`
(line 49)
- Import `cuprum.sh` (or the specific symbol `ExecutionContext`) at top-level
- Update `_prepare_pipeline_config` to reference the direct import

**Task 6: Delete `cuprum/_pipeline_spawn.py`**
- Delete the file entirely
- In `cuprum/_pipeline_internals.py`, replace:
  ~~~
  from cuprum._pipeline_spawn import _spawn_pipeline_processes
  ~~~
  with:
  ~~~
  from cuprum._process_lifecycle import _spawn_pipeline_processes
  ~~~
- Search the entire codebase for any remaining imports from `_pipeline_spawn`
and redirect them to `_process_lifecycle`

💡 Iterate on the plan with: `@coderabbitai` <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!