Public API

Package: astichi

Name	Role
__version__	Package version.
Composable	Abstract type for composed program fragments.
ComposableDescription	Immutable descriptor returned by Composable.describe().
ComposableHole	Additive-hole descriptor with builder target address data.
TargetAddress	Data-driven target address accepted by builder.target(...).
GeneratedAstCache	Trusted local cache for opt-in generated executable AST reuse.
compile	Parse marker-bearing source into a Composable.
build	Create a mutable builder for wiring Composable instances.

from astichi import (
    Composable,
    ComposableDescription,
    ComposableHole,
    GeneratedAstCache,
    TargetAddress,
)
from astichi import compile, build

Marker names in compiled source

Astichi recognizes marker names such as astichi_hole, astichi_bind_external, astichi_for, astichi_pyimport, and astichi_comment from the source text passed to astichi.compile(...).

astichi_insert(...) is reserved internal metadata. The default astichi.compile(..., source_kind="authored") rejects it; only re-ingest Astichi-emitted source with source_kind="astichi-emitted".

The current package does not ship a runtime astichi.markers helper module, so marker-bearing examples are typically embedded directly in the source string that Astichi parses.

Submodule: astichi.frontend

Lower-level access to the compiler surface:

Name	Role
compile	Same as package compile.
CompileOrigin	file_name, line_number, offset for a compiled snippet.

Concrete composable types may be exposed here for typing or introspection; all satisfy Composable.

Concrete composables today

Current frontend and builder results are concrete BasicComposable values (with FrontendComposable as a frontend alias).

compiled = astichi.compile("astichi_bind_external(fields)\nprint(fields)\n")
bound = compiled.bind(fields=("a", "b"))

.bind(mapping=None, /, **values) applies astichi_bind_external(...) substitutions and returns a new immutable composable.

.describe() returns immutable descriptor metadata for data-driven composition. See descriptor-api.md.

.emit_commented() runs final materialization and renders astichi_comment(...) markers as real Python comments. It returns plain source with no provenance tail. See marker-comment.md.

.to_executable_ast() runs final executable materialization and returns a fresh caller-owned ast.Module suitable for compile(tree, ..., "exec").

Additional descriptor value objects for advanced inspection are exported from astichi.model, including PortDescriptor, HoleDescriptor, ProductionDescriptor, ExternalBindDescriptor, IdentifierDemandDescriptor, IdentifierSupplyDescriptor, SINGLE_ADD, and MULTI_ADD. Clause-target metadata exports include ELIF_CLAUSE and REJECT_EMPTY.

Inventory value objects for lower-level resource discovery are also exported from astichi.model, including Inventory, InventoryRecord, InventoryRecordId, ResourcePath, CodePath, SourceLocation, and MutableInventory. Prefer Composable.describe() for ordinary planning. Use inventory when a tool needs map-backed access to resource records. See inventory-api.md.

Submodule: astichi.builder

Builder construction and graph types used by build() and advanced callers. The public builder handle supports both fluent chains and data-driven named calls such as builder.add("Root", piece), builder.define("Step", piece), builder.instance("Root").target("body").add("Step"), builder.target(...), and builder.assign(source_instance=..., inner_name=..., target_instance=..., outer_name=...). Descriptor identifier demand/supply pairs can be bound with builder.bind_identifier(...).

builder.to_executable_ast(cache=GeneratedAstCache(...)) is the opt-in generated-AST cache path. Cache hits return a fresh AST and skip build_merge; cache files are trusted local build artifacts, not an untrusted input format.

Submodule: astichi.assembler

Inventory-driven helpers for generated composition planners:

Name	Role
AssemblyScope	Wrapper around a builder that refreshes an inventory view after candidate application.
BindingRequest	Ordered resource-resolution request for AssemblyScope.apply_batch(...).
as_composable	Wrap a composable resource with a builder name, optional build index, and insertion order.
as_external_value	Wrap a value for astichi_bind_external(...) demands.
as_identifier	Wrap a Python identifier spelling for identifier demands.
find_candidates	Locate compatible inventory records using optional name, build-path, and code-owner selectors.
apply_batch	Resolve and apply an ordered request stream without using the single-call compatibility counters.
require_one	Accept exactly one candidate or raise a detailed ambiguity/missing diagnostic.

Build and materialize remain authoritative. The assembler helpers are a thin application layer over the current builder and inventory APIs, not the full future YIDL assembler contract. See assembler-scope.md.

Submodule: astichi.pathmatch

matches_path(selector, path) matches literal tuple selectors plus ., ?, *, and + path operators. It is used by assembler candidate lookup for build-path and code-owner filters.

Submodule: astichi.emit

Source emission and provenance helpers:

Name	Role
emit_source	Render a module AST to source with optional provenance.
encode_provenance / decode_provenance	Encode and decode the embedded provenance payload.
extract_provenance	Read provenance from emitted source text.
verify_round_trip	Verify that emitted source reparses to the embedded AST.
RoundTripError	Raised when provenance is missing or mismatched.