cuprum 0.1.0__tar.gz

cuprum-0.1.0/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.3
+Name: cuprum
+Version: 0.1.0
+Summary: cuprum package
+Author: Payton McIntosh
+Author-email: Payton McIntosh <pmcintosh@df12.net>
+License: ISC
+Requires-Python: >=3.12
+Project-URL: Homepage, https://df12.studio/docs.html
+Project-URL: Repository, https://github.com/leynos/cuprum
+Description-Content-Type: text/markdown
+
+# cuprum
+
+Typed, async command execution for Python—so you can ditch the shell scripts
+without losing your mind.
+
+## What is this?
+
+If you've ever written a Python script that calls out to external commands,
+you've probably experienced the joys of `subprocess`: stringly-typed arguments,
+mysterious failures, and output that vanishes into the void. Cuprum is here to
+help.
+
+We give you a **typed, safe approach to running external programs**. Instead of
+passing arbitrary strings to a shell, you work with a curated catalogue of
+approved executables. Each command carries metadata about its project, so
+downstream tooling knows how to filter noise from logs or where to find
+documentation.
+
+Cuprum is async-first but provides synchronous wrappers for scripts that don't
+need the full async machinery. Whether you're building deployment helpers, CI
+glue, or maintenance scripts, we want "Python instead of Bash" to feel like an
+upgrade rather than a chore.
+
+## Quick taste
+
+```python
+from cuprum import ECHO, ExecutionContext, sh
+
+# Create a builder for a curated program
+echo = sh.make(ECHO)
+
+# Build a command with typed arguments
+cmd = echo("-n", "hello, cuprum!")
+
+# Run it (async)
+result = await cmd.run(echo=True)
+if result.ok:
+    print(f"Output: {result.stdout}")
+
+# Or run it synchronously
+result = cmd.run_sync()
+```
+
+## Features
+
+- **Catalogue-based safety** – Only approved programs can run; unknown
+  executables raise `UnknownProgramError`.
+- **Typed command building** – `sh.make()` returns builders that validate
+  arguments and carry project metadata.
+- **Async-first execution** – `await cmd.run()` with capture/echo toggles,
+  environment overlays, and working directory control.
+- **Synchronous convenience** – `cmd.run_sync()` when you don't need async.
+- **Graceful cancellation** – Cancelled tasks send `SIGTERM`, wait briefly,
+  then escalate to `SIGKILL`.
+- **Structured results** – `CommandResult` gives you exit code, pid, stdout,
+  stderr, and an `ok` helper.
+- **Zero dependencies** – Just Python 3.12+ and the standard library.
+
+## Installation
+
+```shell
+pip install cuprum
+```
+
+Or with [uv](https://docs.astral.sh/uv/):
+
+```shell
+uv add cuprum
+```
+
+## Status
+
+Cuprum is in early development. The typed command core and execution runtime
+are complete (Phase 1 of the [roadmap](docs/roadmap.md)), but context-scoped
+allowlists and hooks are still on the way. The API may shift as we learn what
+works best.
+
+## Documentation
+
+For the full guide—including how to build your own program catalogues, write
+project-specific builders, and control execution contexts—see the
+[users' guide](docs/users-guide.md).
+
+## Why "cuprum"?
+
+The name is a tip of the hat to [Plumbum](https://plumbum.readthedocs.io/), the
+library that showed us shell-like scripting in Python could actually be
+pleasant. "Cuprum" is Latin for copper—another metal used in pipes—and we hope
+to carry that spirit forward with a focus on type safety and explicit
+allowlists.
+
+## Licence
+
+[ISC](LICENSE)

cuprum-0.1.0/README.md

@@ -0,0 +1,94 @@
+# cuprum
+
+Typed, async command execution for Python—so you can ditch the shell scripts
+without losing your mind.
+
+## What is this?
+
+If you've ever written a Python script that calls out to external commands,
+you've probably experienced the joys of `subprocess`: stringly-typed arguments,
+mysterious failures, and output that vanishes into the void. Cuprum is here to
+help.
+
+We give you a **typed, safe approach to running external programs**. Instead of
+passing arbitrary strings to a shell, you work with a curated catalogue of
+approved executables. Each command carries metadata about its project, so
+downstream tooling knows how to filter noise from logs or where to find
+documentation.
+
+Cuprum is async-first but provides synchronous wrappers for scripts that don't
+need the full async machinery. Whether you're building deployment helpers, CI
+glue, or maintenance scripts, we want "Python instead of Bash" to feel like an
+upgrade rather than a chore.
+
+## Quick taste
+
+```python
+from cuprum import ECHO, ExecutionContext, sh
+
+# Create a builder for a curated program
+echo = sh.make(ECHO)
+
+# Build a command with typed arguments
+cmd = echo("-n", "hello, cuprum!")
+
+# Run it (async)
+result = await cmd.run(echo=True)
+if result.ok:
+    print(f"Output: {result.stdout}")
+
+# Or run it synchronously
+result = cmd.run_sync()
+```
+
+## Features
+
+- **Catalogue-based safety** – Only approved programs can run; unknown
+  executables raise `UnknownProgramError`.
+- **Typed command building** – `sh.make()` returns builders that validate
+  arguments and carry project metadata.
+- **Async-first execution** – `await cmd.run()` with capture/echo toggles,
+  environment overlays, and working directory control.
+- **Synchronous convenience** – `cmd.run_sync()` when you don't need async.
+- **Graceful cancellation** – Cancelled tasks send `SIGTERM`, wait briefly,
+  then escalate to `SIGKILL`.
+- **Structured results** – `CommandResult` gives you exit code, pid, stdout,
+  stderr, and an `ok` helper.
+- **Zero dependencies** – Just Python 3.12+ and the standard library.
+
+## Installation
+
+```shell
+pip install cuprum
+```
+
+Or with [uv](https://docs.astral.sh/uv/):
+
+```shell
+uv add cuprum
+```
+
+## Status
+
+Cuprum is in early development. The typed command core and execution runtime
+are complete (Phase 1 of the [roadmap](docs/roadmap.md)), but context-scoped
+allowlists and hooks are still on the way. The API may shift as we learn what
+works best.
+
+## Documentation
+
+For the full guide—including how to build your own program catalogues, write
+project-specific builders, and control execution contexts—see the
+[users' guide](docs/users-guide.md).
+
+## Why "cuprum"?
+
+The name is a tip of the hat to [Plumbum](https://plumbum.readthedocs.io/), the
+library that showed us shell-like scripting in Python could actually be
+pleasant. "Cuprum" is Latin for copper—another metal used in pipes—and we hope
+to carry that spirit forward with a focus on type safety and explicit
+allowlists.
+
+## Licence
+
+[ISC](LICENSE)

cuprum-0.1.0/cuprum/__init__.py

@@ -0,0 +1,99 @@
+"""cuprum package.
+
+Provides a typed programme catalogue system for managing curated, allowlisted
+executables. Re-exports core types and the default catalogue for convenience.
+
+Example:
+>>> from cuprum import DEFAULT_CATALOGUE, ECHO
+>>> entry = DEFAULT_CATALOGUE.lookup(ECHO)
+>>> entry.project_name
+'core-ops'
+
+"""
+
+from __future__ import annotations
+
+from cuprum.catalogue import (
+    CORE_OPS_PROJECT,
+    DEFAULT_CATALOGUE,
+    DEFAULT_PROJECTS,
+    DOC_TOOL,
+    DOCUMENTATION_PROJECT,
+    ECHO,
+    LS,
+    ProgramCatalogue,
+    ProgramEntry,
+    ProjectSettings,
+    UnknownProgramError,
+)
+from cuprum.context import (
+    AfterHook,
+    AllowRegistration,
+    BeforeHook,
+    CuprumContext,
+    ExecHook,
+    ForbiddenProgramError,
+    HookRegistration,
+    after,
+    allow,
+    before,
+    current_context,
+    get_context,
+    observe,
+    scoped,
+)
+from cuprum.events import ExecEvent
+from cuprum.logging_hooks import LoggingHookRegistration, logging_hook
+from cuprum.program import Program
+from cuprum.sh import (
+    CommandResult,
+    ExecutionContext,
+    Pipeline,
+    PipelineResult,
+    SafeCmd,
+    SafeCmdBuilder,
+)
+
+from . import sh
+
+PACKAGE_NAME = "cuprum"
+
+__all__ = [
+    "CORE_OPS_PROJECT",
+    "DEFAULT_CATALOGUE",
+    "DEFAULT_PROJECTS",
+    "DOCUMENTATION_PROJECT",
+    "DOC_TOOL",
+    "ECHO",
+    "LS",
+    "PACKAGE_NAME",
+    "AfterHook",
+    "AllowRegistration",
+    "BeforeHook",
+    "CommandResult",
+    "CuprumContext",
+    "ExecEvent",
+    "ExecHook",
+    "ExecutionContext",
+    "ForbiddenProgramError",
+    "HookRegistration",
+    "LoggingHookRegistration",
+    "Pipeline",
+    "PipelineResult",
+    "Program",
+    "ProgramCatalogue",
+    "ProgramEntry",
+    "ProjectSettings",
+    "SafeCmd",
+    "SafeCmdBuilder",
+    "UnknownProgramError",
+    "after",
+    "allow",
+    "before",
+    "current_context",
+    "get_context",
+    "logging_hook",
+    "observe",
+    "scoped",
+    "sh",
+]

cuprum-0.1.0/cuprum/_observability.py

@@ -0,0 +1,77 @@
+"""Internal helpers for structured execution event emission."""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+import types
+import typing as typ
+
+if typ.TYPE_CHECKING:
+    import collections.abc as cabc
+
+    from cuprum.events import ExecEvent, ExecHook
+
+
+def _freeze_str_mapping(
+    mapping: cabc.Mapping[str, str] | None,
+) -> cabc.Mapping[str, str] | None:
+    if mapping is None:
+        return None
+    return types.MappingProxyType(dict(mapping))
+
+
+def _merge_tags(*tags: cabc.Mapping[str, object] | None) -> cabc.Mapping[str, object]:
+    merged: dict[str, object] = {}
+    for mapping in tags:
+        if not mapping:
+            continue
+        merged.update(mapping)
+    return types.MappingProxyType(merged)
+
+
+def _emit_exec_event(
+    hooks: tuple[ExecHook, ...],
+    event: ExecEvent,
+    *,
+    pending_tasks: list[asyncio.Task[None]],
+) -> None:
+    """Invoke observe hooks and schedule async hooks as background tasks."""
+    for hook in hooks:
+        result = hook(event)
+        if inspect.isawaitable(result):
+            pending_tasks.append(asyncio.create_task(_await_awaitable(result)))
+
+
+async def _await_awaitable(awaitable: cabc.Awaitable[None]) -> None:
+    await awaitable
+
+
+async def _wait_for_exec_hook_tasks(pending_tasks: list[asyncio.Task[None]]) -> None:
+    """Await background observe-hook tasks and surface the first failure.
+
+    Observe hooks may return awaitables; those awaitables are scheduled as tasks
+    by ``_emit_exec_event`` and added to ``pending_tasks``. This helper awaits
+    all pending tasks and re-raises the first ``BaseException`` encountered.
+
+    Notes
+    -----
+    When multiple hooks fail, only the first exception is raised; subsequent
+    exceptions are not surfaced and may be masked by the first failure.
+
+    """
+    if not pending_tasks:
+        return
+    results = await asyncio.gather(*pending_tasks, return_exceptions=True)
+    pending_tasks.clear()
+    for result in results:
+        if isinstance(result, BaseException):
+            raise result
+
+
+__all__ = [
+    "_emit_exec_event",
+    "_freeze_str_mapping",
+    "_merge_tags",
+    "_wait_for_exec_hook_tasks",
+]

cuprum-0.1.0/cuprum/_pipeline_internals.py

@@ -0,0 +1,278 @@
+"""Internal pipeline execution coordination and fail-fast semantics."""
+
+from __future__ import annotations
+
+import dataclasses as dc
+import sys
+import time
+import typing as typ
+from pathlib import Path
+
+from cuprum._observability import (
+    _emit_exec_event,
+    _freeze_str_mapping,
+    _merge_tags,
+    _wait_for_exec_hook_tasks,
+)
+from cuprum._pipeline_spawn import _spawn_pipeline_processes
+from cuprum._pipeline_streams import (
+    _cancel_stream_tasks,
+    _create_pipe_tasks,
+    _gather_optional_text_tasks,
+    _PipelineRunConfig,
+    _prepare_pipeline_config,
+)
+from cuprum._pipeline_wait import _PipelineWaitResult, _wait_for_pipeline
+from cuprum.context import current_context
+from cuprum.events import ExecEvent
+
+if typ.TYPE_CHECKING:
+    import asyncio
+    import types
+
+    from cuprum.context import AfterHook, BeforeHook
+    from cuprum.events import ExecHook
+    from cuprum.sh import CommandResult, ExecutionContext, PipelineResult, SafeCmd
+
+_MIN_PIPELINE_STAGES = 2
+
+
+def _sh_module() -> types.ModuleType:
+    module = sys.modules.get("cuprum.sh")
+    if module is None:
+        msg = "cuprum.sh must be imported before running pipelines"
+        raise RuntimeError(msg)
+    return module
+
+
+@dc.dataclass(frozen=True, slots=True)
+class _ExecutionHooks:
+    before_hooks: tuple[BeforeHook, ...]
+    after_hooks: tuple[AfterHook, ...]
+    observe_hooks: tuple[ExecHook, ...]
+
+
+def _run_before_hooks(cmd: SafeCmd) -> _ExecutionHooks:
+    """Collect hooks for a command after enforcing the current allowlist."""
+    ctx = current_context()
+    ctx.check_allowed(cmd.program)
+    return _ExecutionHooks(
+        before_hooks=ctx.before_hooks,
+        after_hooks=ctx.after_hooks,
+        observe_hooks=ctx.observe_hooks,
+    )
+
+
+@dc.dataclass(frozen=True, slots=True)
+class _StageObservation:
+    cmd: SafeCmd
+    hooks: _ExecutionHooks
+    tags: typ.Mapping[str, object]
+    cwd: Path | None
+    env_overlay: typ.Mapping[str, str] | None
+    pending_tasks: list[asyncio.Task[None]]
+
+    def emit(
+        self,
+        phase: typ.Literal["plan", "start", "stdout", "stderr", "exit"],
+        details: _EventDetails,
+    ) -> None:
+        if not self.hooks.observe_hooks:
+            return
+        _emit_exec_event(
+            self.hooks.observe_hooks,
+            ExecEvent(
+                phase=phase,
+                program=self.cmd.program,
+                argv=self.cmd.argv_with_program,
+                cwd=self.cwd,
+                env=self.env_overlay,
+                pid=details.pid,
+                timestamp=time.time(),
+                line=details.line,
+                exit_code=details.exit_code,
+                duration_s=details.duration_s,
+                tags=self.tags,
+            ),
+            pending_tasks=self.pending_tasks,
+        )
+
+
+@dc.dataclass(frozen=True, slots=True)
+class _EventDetails:
+    pid: int | None
+    line: str | None = None
+    exit_code: int | None = None
+    duration_s: float | None = None
+
+
+@dc.dataclass(frozen=True, slots=True)
+class _PipelineStageResultInputs:
+    wait_result: _PipelineWaitResult
+    stderr_by_stage: tuple[str | None, ...]
+    final_stdout: str | None
+
+
+def _build_pipeline_observations(
+    parts: tuple[SafeCmd, ...],
+    config: _PipelineRunConfig,
+    *,
+    pending_tasks: list[asyncio.Task[None]],
+) -> tuple[_StageObservation, ...]:
+    hooks_by_stage = tuple(_run_before_hooks(cmd) for cmd in parts)
+    cwd = None if config.ctx.cwd is None else Path(config.ctx.cwd)
+    env_overlay = _freeze_str_mapping(config.ctx.env)
+    return tuple(
+        _StageObservation(
+            cmd=cmd,
+            hooks=hooks,
+            tags=_merge_tags(
+                {
+                    "project": cmd.project.name,
+                    "capture": config.capture,
+                    "echo": config.echo,
+                    "pipeline_stage_index": idx,
+                    "pipeline_stages": len(parts),
+                },
+                config.ctx.tags,
+            ),
+            cwd=cwd,
+            env_overlay=env_overlay,
+            pending_tasks=pending_tasks,
+        )
+        for idx, (cmd, hooks) in enumerate(zip(parts, hooks_by_stage, strict=True))
+    )
+
+
+def _emit_plan_events_and_run_before_hooks(
+    observations: tuple[_StageObservation, ...],
+) -> None:
+    for obs in observations:
+        obs.emit("plan", _EventDetails(pid=None))
+        for hook in obs.hooks.before_hooks:
+            hook(obs.cmd)
+
+
+def _build_pipeline_stage_results(
+    parts: tuple[SafeCmd, ...],
+    observations: tuple[_StageObservation, ...],
+    *,
+    processes: list[asyncio.subprocess.Process],
+    inputs: _PipelineStageResultInputs,
+) -> list[CommandResult]:
+    sh = _sh_module()
+    stage_results: list[CommandResult] = []
+    for idx, obs in enumerate(observations):
+        process = processes[idx]
+        ended_at = inputs.wait_result.ended_at[idx]
+        duration_s = (
+            None
+            if ended_at is None
+            else max(0.0, ended_at - inputs.wait_result.started_at[idx])
+        )
+        obs.emit(
+            "exit",
+            _EventDetails(
+                pid=process.pid,
+                exit_code=inputs.wait_result.exit_codes[idx],
+                duration_s=duration_s,
+            ),
+        )
+        stage_results.append(
+            sh.CommandResult(
+                program=obs.cmd.program,
+                argv=obs.cmd.argv,
+                exit_code=inputs.wait_result.exit_codes[idx],
+                pid=process.pid if process.pid is not None else -1,
+                stdout=inputs.final_stdout if idx == len(parts) - 1 else None,
+                stderr=inputs.stderr_by_stage[idx],
+            ),
+        )
+    return stage_results
+
+
+async def _finalize_pipeline_execution(
+    parts: tuple[SafeCmd, ...],
+    observations: tuple[_StageObservation, ...],
+    stage_results: list[CommandResult],
+    pending_tasks: list[asyncio.Task[None]],
+) -> None:
+    hooks_by_stage = tuple(obs.hooks for obs in observations)
+    _run_pipeline_after_hooks(parts, hooks_by_stage, stage_results)
+    await _wait_for_exec_hook_tasks(pending_tasks)
+
+
+async def _run_pipeline(
+    parts: tuple[SafeCmd, ...],
+    *,
+    capture: bool,
+    echo: bool,
+    context: ExecutionContext | None,
+) -> PipelineResult:
+    """Execute a pipeline and return a structured result."""
+    config = _prepare_pipeline_config(capture=capture, echo=echo, context=context)
+    pending_tasks: list[asyncio.Task[None]] = []
+    observations = _build_pipeline_observations(
+        parts,
+        config,
+        pending_tasks=pending_tasks,
+    )
+    try:
+        _emit_plan_events_and_run_before_hooks(observations)
+        (
+            processes,
+            stderr_tasks,
+            stdout_task,
+            started_at,
+        ) = await _spawn_pipeline_processes(
+            parts,
+            config,
+            observations=observations,
+        )
+    except BaseException:
+        await _wait_for_exec_hook_tasks(pending_tasks)
+        raise
+    try:
+        wait_result = await _wait_for_pipeline(
+            processes,
+            pipe_tasks=_create_pipe_tasks(processes),
+            cancel_grace=config.ctx.cancel_grace,
+            started_at=started_at,
+        )
+        inputs = _PipelineStageResultInputs(
+            wait_result=wait_result,
+            stderr_by_stage=await _gather_optional_text_tasks(stderr_tasks),
+            final_stdout=None if stdout_task is None else await stdout_task,
+        )
+    except BaseException:
+        await _cancel_stream_tasks(stderr_tasks, stdout_task)
+        await _wait_for_exec_hook_tasks(pending_tasks)
+        raise
+    stage_results = _build_pipeline_stage_results(
+        parts,
+        observations,
+        processes=processes,
+        inputs=inputs,
+    )
+    await _finalize_pipeline_execution(
+        parts,
+        observations,
+        stage_results,
+        pending_tasks,
+    )
+
+    return _sh_module().PipelineResult(
+        stages=tuple(stage_results),
+        failure_index=inputs.wait_result.failure_index,
+    )
+
+
+def _run_pipeline_after_hooks(
+    parts: tuple[SafeCmd, ...],
+    hooks_by_stage: tuple[_ExecutionHooks, ...],
+    results: list[CommandResult],
+) -> None:
+    """Run registered after hooks for each pipeline stage."""
+    for cmd, hooks, result in zip(parts, hooks_by_stage, results, strict=True):
+        for hook in hooks.after_hooks:
+            hook(cmd, result)

cuprum-0.1.0/cuprum/_pipeline_spawn.py

@@ -0,0 +1,20 @@
+"""Pipeline subprocess spawning and stream wiring.
+
+This module is a thin wrapper around the underlying spawn and cleanup helpers.
+The implementations live in ``cuprum._process_lifecycle`` to keep pipeline
+orchestration cohesive and avoid import cycles.
+"""
+
+from __future__ import annotations
+
+from cuprum._process_lifecycle import (
+    _build_spawn_observations,
+    _cleanup_spawned_processes,
+    _spawn_pipeline_processes,
+)
+
+__all__ = [
+    "_build_spawn_observations",
+    "_cleanup_spawned_processes",
+    "_spawn_pipeline_processes",
+]