Skip to content

refactor(python): simplify plugin mechanics with standard idioms - #203

Merged
BjRo merged 1 commit into
mainfrom
refactor/idiomatic-python-mechanics
Sep 19, 2026
Merged

BjRo merged 1 commit into
mainfrom
refactor/idiomatic-python-mechanics

Conversation

@BjRo

@BjRo BjRo commented Sep 19, 2026

Copy link
Copy Markdown
Owner

Why

The Python migrations left manual escaping, argument indexing, and resource cleanup that standard Python operations can express more directly.

What changed

  • Use translation tables for Markdown, catalog, and TSV escaping; direct type guards for provider records; iterator/pair traversal for arguments; dataclasses.replace() for catalog rows; and Counter for report totals.
  • Use contextlib.closing() for SQLite connections and remove a redundant catch-and-reraise without changing explicit transactions or cancellation propagation.
  • Add the behavior-preservation invariant to docs/specs/python-quality.md and increment both plugin manifests for discovery, Git, review, decisions, adaptive delivery, and Langfuse observability.

Verification

  • Python quality checks covered all 11 registered packages: 1,333 tests passed, with Ruff, strict mypy, and statement/branch coverage gates passing. Ran bun run check:python; after correcting one import-order lint issue, completed the remaining gates with bun run check:python --package plugins/capability/darrow-review/backend, bun run check:python --package plugins/orchestration/darrow-adaptive-delivery/backend, and bun run check:python --package plugins/orchestration/darrow-ticket-pipeline/backend.
  • Passed bun run lint, bun run lint:ts, bun run lint:shell, bun run typecheck, bun run check:decisions, and bun run check:docs.
  • Passed the Git, review, decisions, and adaptive-delivery backend/tests/fresh_install.py checks through their frozen runtime-only UV entrypoints. Passed discovery and Langfuse tests/fresh-install.test.sh with both bash and /bin/bash.
  • Passed the packaged inspect-skill inspect checks for the seven affected skill entrypoints.
  • Temporary differential probes matched five escaping functions across every Unicode code point and mixed escape sequences, 19,531 adaptive argument vectors, 781 frontier argument vectors, and malformed JSON/transcript cases.
  • An independent fresh-context reader found no issues.

Review notes

Exact serialized bytes, literal flag-looking arguments, error precedence, and SQLite transaction behavior are the key compatibility constraints. Local validation ran on macOS with Python 3.13; native Linux/Windows and the other supported Python versions remain for CI. Live agent evals were not run because skill instructions and workflow behavior are unchanged. The larger typed-record redesign remains a separate follow-up.

Checklist

  • I have read and followed CONTRIBUTING.md, including the contribution
    licensing terms.
  • I added or updated the applicable invariant before implementation, or
    this change does not affect a capability invariant.
  • I added or updated colocated evals, or this change does not affect skill
    behavior.
  • I confirmed that each changed plugin remains self-contained, or this
    change does not affect plugin content.
  • I ran bun run check:python, or this change does not affect registered
    Python packages or their repository quality infrastructure.

@BjRo
BjRo merged commit 8d710a8 into main Sep 19, 2026
165 checks passed
@BjRo
BjRo deleted the refactor/idiomatic-python-mechanics branch September 19, 2026 10:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant