Skip to content

🧩 hexa — Type-Declared Dependency Injection for Python

hexa is a pattern and utility library for structuring complex hierarchical pipelines. It rests on one core idea: a concrete class's annotated slot type is the dependency decision. Variation is expressed entirely as class annotations — never as imperative wiring, never as __init__ parameters, never as a composition root that assembles objects by hand.

Doc model: this wiki is written for humans — how‑to guides, examples, and testing recipes. The authoritative API contracts live in the code (docstrings) and the machine‑readable bundle under docs/mcp/.

🚀 Key Features

  • 🧬 Three fixed layers — ABC contracts declare what a stage requires, Impl* classes hold the shared default, bank-like specializations override only what differs
  • 🪢 build container — recursively wires a full pipeline from __annotations__ across the MRO; instances= and config= inject runtime values by name
  • 📐 One neutral model — every converter serializes through a PortNode tree; the model is not tied to any sample
  • 🔁 Interchangeable representations — parse_yaml / generate_abc / parse_abc / generate_yaml translate between YAML specs and ABC modules
  • ✅ Machine-checked agreement — check_matches verifies two representations describe the same tree and prints human-readable diffs
  • 🖥️ Thin CLI — hexa parse-yaml, parse-abc, generate-abc, generate-yaml, check for CLI workflows
  • 🧪 Sample-driven tests — samples/minimal and samples/extraction_pipeline double as live examples for the test suite

📦 Installation

From your internal PyPI:

Bash
pip install --extra-index-url https://$PYPI_USERNAME:$PYPI_PASSWORD@pip.aetoskia.com/simple hexa

From local source:

Bash
pip install -e .

📁 Documentation Structure

Section Description
Overview The mental model: three layers, two representations, and the container
Core Components PortNode, MethodSpec, converters, check_matches, build, CLI
Use cases Step-by-step recipes
· 01 – YAML first Author a spec, generate ABCs, verify
· 02 – ABC first Author the ABC module, emit a YAML spec
· 03 – Wiring & runtime build, instances=, config= at runtime
Design The extraction pipeline sample, port tree, and container algorithm
Philosophy Why type-declared dependencies beats wiring by hand
Best Practices Redundancy rules and the two fidelity guarantees
Error Handling What can raise and what it means
Testing Zero-mock unit testing against the samples

© Aetoskia Internal — hexa 0.1.0