`arch.idx`: Document Index and Header API#

The public package separates styled, arbitrary-depth document indexes from the fixed architectonic address exported as arch.Quad (with arch.Idx retained for compatibility).

`1` Domain model#

class arch.idx.model.IdxStyle(*values)#

Bases: StrEnum

Rendering alphabet for one index place.

classmethod parse(value)#: Parse a style name, including concise configuration aliases.

class arch.idx.model.Severity(*values)#

Bases: StrEnum

Diagnostic severity.

class arch.idx.model.IdxPart(ordinal, style=IdxStyle.NUMBER)#

Bases: object

One zero-based index place and its display style.

class arch.idx.model.IdxSpec(styles=(IdxStyle.NUMBER,), separator='.', marker='', wrapper='', max_depth=None, numeric_origin=1, symbols=('.', '-', '+', '*', '^'))#

Bases: object

Policy for parsing and rendering a family of document indexes.

classmethod from_mapping(value)#: Build a spec from validated YAML-compatible values.

style_at(depth)#: Return the style at a zero-based depth.

class arch.idx.model.Idx(parts)#

Bases: object

A styled, hierarchical document index.

classmethod from_ordinals(ordinals, spec=DEFAULT_SPEC)#: Build an index from zero-based ordinals.

classmethod from_parts(spec, *ordinals)#: Build from Sublime-era zero-based parts with an explicit specification.

classmethod from_values(values, spec=DEFAULT_SPEC)#: Build from display values, preserving upstream numeric ergonomics.

classmethod parse(source, spec=DEFAULT_SPEC)#

Parse one complete index according to spec.

Raises:: ValueError – If the input is malformed, ambiguous, or exceeds the spec.

classmethod attempt_to_read(source, spec=DEFAULT_SPEC)#: Read an index from the beginning of text and return its span.

classmethod build_relative(parent=None, previous=None, *, absolute_depth=None, relative_depth=None, absolute_place=None, relative_place=None, spec=DEFAULT_SPEC)#: Build a relative index using the useful sublime-headers semantics.

render(spec=DEFAULT_SPEC)#: Render the index canonically according to spec.

matches(other)#: Return whether two indexes identify the same places.

is_ancestor_of(other)#: Return whether this index is a strict prefix of other.

property depth#: Number of index places.

property ordinals#: Zero-based place values.

class arch.idx.model.Diagnostic(code, message, severity, line, column, path='', replacement=None)#

Bases: object

Stable, machine-readable lint finding.

as_dict()#: Return a JSON-compatible representation.

class arch.idx.model.Edit(start, end, replacement, line, column, code)#

Bases: object

One byte-stable text replacement within decoded source.

class arch.idx.model.Occurrence(start, end, insertion, line, column, level, text, idx, structural, prefix='', metadata=<factory>)#

Bases: object

One discovered structural or free-standing document index site.

`2` Configuration#

exception arch.idx.config.ConfigError#

Bases: ValueError

Raised for an invalid arch configuration.

class arch.idx.config.RuleKind(*values)#

Bases: StrEnum

Path matcher mechanism.

class arch.idx.config.PathRule(pattern, spec, kind=RuleKind.GLOB, insertion=None, include_title=None, source=None)#

Bases: object

Ordered mapping from one path matcher to one named policy.

matches(path, root)#: Return whether the rule matches an absolute or root-relative path.

class arch.idx.config.IndexSelection(name, spec, insertion, include_title)#

Bases: object

Complete index policy selected for one explicitly enrolled path.

class arch.idx.config.AppConfig(specs, headers, rules, header_rules=<factory>, header_defaults=<factory>, default_spec='default', index_default=None, insertion='observed', ignores=('.git/**', '.venv/**', 'node_modules/**', 'build/**', 'dist/**', '__pycache__/**'), sources=<factory>, warnings=<factory>, spec_sources=<factory>, header_sources=<factory>, header_default_sources=<factory>, index_default_source=None, insertion_source=None, ignore_sources=<factory>, header_mode=HeaderMode.FLEX, header_mode_source=None)#

Bases: object

Resolved policy with independent index and header selectors.

name_for(path, root)#: Resolve the legacy grammar name without implying enrollment.

spec_for(path, root)#: Resolve a grammar for direct API callers without enrolling a path.

index_selection_for(path, root)#: Return explicit index policy, or None for an unenrolled/unsupported path.

header_name_for(path, root)#: Return the independently selected header profile name.

header_profile_for(path, root)#: Resolve a header profile independently from index selection.

resolution_for(path, root)#: Explain both authoritative policy paths for one file.

matching_ignore(path, root)#: Return the first matching ignore pattern and its authority.

is_ignored(path, root)#: Return whether a path matches a configured ignore glob.

arch.idx.config.load_config(explicit=None, *, cwd=None, user_path=None)#: Load built-ins, user config, project config, then explicit config.

`3` Planning and application#

class arch.idx.engine.Operation(*values)#

Bases: StrEnum

Systematic modification represented by a plan.

exception arch.idx.engine.StalePlanError#

Bases: RuntimeError

Raised when a file changed after its plan was created.

exception arch.idx.engine.UnsafeFileError#

Bases: OSError

Raised when a path cannot be read within the regular-file safety boundary.

class arch.idx.engine.FilePlan(path, digest, decoded, eligible, occurrences, diagnostics, edits, skipped=None)#

Bases: object

Immutable analysis and proposed edits for one file.

property changed#: Whether applying this plan would change bytes.

rendered()#: Return source after all edits.

diff()#: Render a unified diff without timestamps.

as_dict()#: Return stable JSON-compatible plan data.

class arch.idx.engine.ApplyResult(path, changed, bytes_written=0)#

Bases: object

Observable result of an application attempt.

arch.idx.engine.plan_file(path, spec=DEFAULT_SPEC, *, operation=Operation.FIX, insertion='observed', enrolled=True, include_title=True)#: Analyze one explicitly selected file and propose conservative edits.

arch.idx.engine.plan_bytes(path, data, spec=DEFAULT_SPEC, *, operation=Operation.FIX, insertion='observed', enrolled=True, include_title=True)#: Analyze explicitly selected bytes, including stdin with a synthetic path.

arch.idx.engine.apply_plan(plan, *, dry_run=False)#: Atomically apply one plan after checking its content digest.

arch.idx.engine.discover_paths(inputs, config, *, root=None)#: Expand files and directories deterministically while honoring ignores.

`4` Header model#

Immutable header-format models shared by the CLI and terminal editor.

class arch.idx.headers.Formatter(*values)#

Bases: StrEnum

A deterministic title transformation.

apply(text)#

Transform stripped title text, preserving inline code and URLs.

Backtick code spans (`` code ), markdown links (``[text](url)), and bare URLs are extracted before transformation and restored verbatim, so a case transform or word-joiner never corrupts semantic inline content.

class arch.idx.headers.HeaderMode(*values)#

Bases: StrEnum

How header presentation is selected during normalization.

class arch.idx.headers.IndexPolicy(*values)#

Bases: StrEnum

Whether a header level may, must, or must not display an index.

class arch.idx.headers.HeaderSpec(mark='#', left_margin=0, top_margin=0, right_margin=0, bottom_margin=0, width='content', continuous=False, idx_spec=IdxSpec(styles=(<IdxStyle.NUMBER: 'number'>, ), separator='.', marker='', wrapper='', max_depth=None, numeric_origin=1, symbols=('.', '-', '+', '*', '^')), index_policy=IndexPolicy.OPTIONAL, tagged=False, formatters=(), color='')#

Bases: object

Presentation and index policy for one structural header level.

classmethod from_mapping(value, *, defaults=None, legacy=False)#: Build a spec from modern or explicitly selected Sublime-era values.

property margins#: Return left, top, right, and bottom margins.

property height#: Return the rendered line count.

format_title(title)#: Apply configured title transformations in order.

render(title, *, idx=None, tag='', comment='#', column=0)#: Render one complete header block without a trailing newline.

parse(source, *, level, comment='#', column=0)#: Parse a compatible complete header block.

as_dict()#: Return stable YAML/JSON-compatible data.

class arch.idx.headers.Header(title, level, spec, idx=None, tag='')#

Bases: object

Semantic content parsed from or rendered into one header block.

render(*, comment='#', column=0)#: Render through this header’s immutable specification.

class arch.idx.headers.HeaderOccurrence(header, span, line, column, comment)#

Bases: object

One recognized header and its half-open source span.

class arch.idx.headers.HeaderProfile(levels=<factory>)#

Bases: object

Ordered header levels, clamping deeper documents to the final level.

classmethod from_mapping(value, *, legacy=False)#: Load list or sparse-level mapping syntax without mutating input.

for_level(level)#: Return a level specification, repeating the final one when needed.

as_dict()#: Return a stable level-keyed representation.

arch.idx.headers.comment_token(path_suffix)#: Return the standalone line-comment token for a file suffix.

`5` Header formatting planner#

Discover and format configured header blocks through immutable file plans.

arch.idx.header_engine.discover_headers(path, text, profile, *, mode=HeaderMode.FLEX)#: Recognize configured header blocks without treating rulers as headings.

arch.idx.header_engine.plan_header_bytes(path, data, profile, *, mode=HeaderMode.FLEX)#: Plan deterministic formatting for an in-memory file.

arch.idx.header_engine.plan_header_file(path, profile, *, mode=HeaderMode.FLEX)#: Read a bounded regular file and plan header formatting.

`6` Keyboard profile editor#

Keyboard-first HeaderSpec editor built on PyRatatui.

class arch.idx.spec_tui.SpecEditorState(profile, level=0, field=0, title='Header title', message='', help_visible=False, last_change=None)#

Bases: object

Pure editor state used by both rendering and terminal event handling.

property spec#: Return the selected level’s specification.

evolve(**changes)#: Return a changed immutable state.

arch.idx.spec_tui.reduce_key(state, key)#: Apply one normalized key and optionally return a command.

arch.idx.spec_tui.snapshot(state, *, width=100, height=30)#: Render a deterministic plain-text representation for tests and agents.

arch.idx.spec_tui.load_profile(path)#: Load a modern or legacy profile, defaulting to one conventional level.

arch.idx.spec_tui.save_profile(path, profile)#: Atomically save a stable modern YAML representation beside the target.

arch.idx.spec_tui.run_spec_tui(*, input_path=None, output_path=None)#: Run the terminal editor and restore terminal state on every exit.

arch.idx: Document Index and Header API#

1 Domain model#

2 Configuration#

3 Planning and application#

4 Header model#

5 Header formatting planner#

6 Keyboard profile editor#

`arch.idx`: Document Index and Header API#

`1` Domain model#

`2` Configuration#

`3` Planning and application#

`4` Header model#

`5` Header formatting planner#

`6` Keyboard profile editor#