API reference

class archledger.repository.InitResult(workspace_root: 'Path', config_path: 'Path', archledger_dir: 'Path', created_paths: 'tuple[Path, ...]')

workspace_root: Path

config_path: Path

archledger_dir: Path

created_paths: tuple[Path, ...]

__init__(workspace_root: Path, config_path: Path, archledger_dir: Path, created_paths: tuple[Path, ...]) → None

class archledger.repository.StatusResult(workspace_root: 'Path', config_path: 'Path', archledger_dir: 'Path', archive_dir: 'Path', sections_count: 'int', record_directories_count: 'int', storage_meta_path: 'Path', build_dir: 'Path')

workspace_root: Path

config_path: Path

archledger_dir: Path

archive_dir: Path

sections_count: int

record_directories_count: int

storage_meta_path: Path

build_dir: Path

__init__(workspace_root: Path, config_path: Path, archledger_dir: Path, archive_dir: Path, sections_count: int, record_directories_count: int, storage_meta_path: Path, build_dir: Path) → None

class archledger.repository.CheckFinding(level: 'str', message: 'str', path: 'Path | None' = None)

level: str

message: str

path: Path | None

__init__(level: str, message: str, path: Path | None = None) → None

class archledger.repository.CheckResult(errors: 'tuple[CheckFinding, ...]', warnings: 'tuple[CheckFinding, ...]')

errors: tuple[CheckFinding, ...]

warnings: tuple[CheckFinding, ...]

has_failures(*, strict: bool) → bool

__init__(errors: tuple[CheckFinding, ...], warnings: tuple[CheckFinding, ...]) → None

class archledger.repository.ArchiveResult(record_id: 'str', source_path: 'Path', archive_path: 'Path', reason: 'str', already_archived: 'bool' = False)

record_id: str

source_path: Path

archive_path: Path

reason: str

already_archived: bool

__init__(record_id: str, source_path: Path, archive_path: Path, reason: str, already_archived: bool = False) → None

class archledger.repository.DoctorRepair(kind: 'str', message: 'str', path: 'Path | None' = None, before: 'int | None' = None, after: 'int | None' = None)

kind: str

message: str

path: Path | None

before: int | None

after: int | None

__init__(kind: str, message: str, path: Path | None = None, before: int | None = None, after: int | None = None) → None

class archledger.repository.DoctorResult(errors: 'tuple[CheckFinding, ...]', warnings: 'tuple[CheckFinding, ...]', repairs: 'tuple[DoctorRepair, ...]', storage_next_number_before: 'int', storage_next_number_after: 'int', highest_seen: 'int', missing_numbers: 'tuple[int, ...]', duplicate_numbers: 'tuple[int, ...]')

errors: tuple[CheckFinding, ...]

warnings: tuple[CheckFinding, ...]

repairs: tuple[DoctorRepair, ...]

storage_next_number_before: int

storage_next_number_after: int

highest_seen: int

missing_numbers: tuple[int, ...]

duplicate_numbers: tuple[int, ...]

__init__(errors: tuple[CheckFinding, ...], warnings: tuple[CheckFinding, ...], repairs: tuple[DoctorRepair, ...], storage_next_number_before: int, storage_next_number_after: int, highest_seen: int, missing_numbers: tuple[int, ...], duplicate_numbers: tuple[int, ...]) → None

class archledger.repository.ArchitectureRepository(paths: ProjectPaths, config: ProjectConfig)

__init__(paths: ProjectPaths, config: ProjectConfig) → None

init(*, overwrite: bool = False) → InitResult

status() → StatusResult

create_record(kind: str, title: str, **kwargs: object) → ArchitectureRecord

list_records(*, include_draft: bool = False, include_superseded: bool = False, kind: str | None = None) → list[ArchitectureRecord]

load_all_records(*, include_sections: bool = True) → list[ArchitectureRecord]

get_record(record_id: str) → ArchitectureRecord

check(*, strict: bool = False) → CheckResult

archive_record(record_id: str, *, reason: str = '') → ArchiveResult

doctor(*, repair: bool = False) → DoctorResult

archledger.repository.path_in_archive(path: Path, archive_dir: Path) → bool

archledger.model.known_source_extensions(config: object) → tuple[str, ...]

Return sorted tuple of all recognised source file extensions.

class archledger.model.SectionSpec(key: 'str', title: 'str', order: 'int', number: 'int')

key: str

title: str

order: int

number: int

__init__(key: str, title: str, order: int, number: int) → None

class archledger.model.SourceRef(path: 'str', symbols: 'tuple[str, ...]', reason: 'str' = '')

path: str

symbols: tuple[str, ...]

reason: str

__init__(path: str, symbols: tuple[str, ...], reason: str = '') → None

class archledger.model.ArchitectureRecord(id: 'str', type: 'str', title: 'str', status: 'str', section: 'str', order: 'int', path: 'Path', metadata: 'dict[str, object]', body: 'str', source_refs: 'tuple[SourceRef, ...]' = ())

id: str

type: str

title: str

status: str

section: str

order: int

path: Path

metadata: dict[str, object]

body: str

source_refs: tuple[SourceRef, ...]

__init__(id: str, type: str, title: str, status: str, section: str, order: int, path: Path, metadata: dict[str, object], body: str, source_refs: tuple[SourceRef, ...] = ()) → None

archledger.model.normalize_kind(kind: str) → str

archledger.model.validate_record(record: ArchitectureRecord, *, id_format: LedgerIdFormat | None = None, expected_segment: str | None = None, id_prefix: str = 'al', id_width: int = 4) → list[str]

class archledger.model.SourceFormatSpec(extension: str, native_output: str, section_body_placeholder: str, empty_section_placeholder: str)

All per-format attributes for a source format.

extension: str

native_output: str

section_body_placeholder: str

empty_section_placeholder: str

__init__(extension: str, native_output: str, section_body_placeholder: str, empty_section_placeholder: str) → None

archledger.model.source_format_spec(source_format: str) → SourceFormatSpec

Return the full spec for a source format.

archledger.model.default_extension_for_source_format(source_format: str) → str

archledger.model.native_output_format_for_source_format(source_format: str) → str

archledger.model.infer_output_format_from_path(path: str | Path) → str | None

archledger.model.default_document_filename_for_output_format(output_format: str) → str

archledger.model.document_template_name_for_source_format(source_format: str) → str

archledger.model.record_template_name_for_source_format(kind: str, source_format: str = 'markdown') → str

archledger.model.section_body_placeholder_for_source_format(source_format: str) → str

archledger.model.empty_section_placeholder_for_source_format(source_format: str) → str

archledger.model.section_filename_for(section_spec: SectionSpec, extension: str = '.md', *, id_prefix: str = 'al', id_width: int = 4, segment_mode: str = 'none', segment: str | None = None) → str

archledger.model.filename_for(number: int, extension: str = '.md', *, id_prefix: str = 'al', id_width: int = 4, segment_mode: str = 'none', segment: str | None = None) → str

archledger.model.id_from_filename(path: Path) → str

archledger.model.is_visible_status(status: str, *, include_draft: bool, include_superseded: bool, include_archived: bool = False) → bool

archledger.model.record_sort_key(record: ArchitectureRecord) → tuple[int, int, str, int, str]

class archledger.source_tracking.TrackedFile(path: 'str', sha256: 'str')

path: str

sha256: str

__init__(path: str, sha256: str) → None

class archledger.source_tracking.DirectoryState(path: 'str', sha256: 'str', file_count: 'int')

path: str

sha256: str

file_count: int

__init__(path: str, sha256: str, file_count: int) → None

class archledger.source_tracking.SourceState(schema: 'str', project_uuid: 'str', project_name: 'str', created_at: 'str', updated_at: 'str', reason: 'str', scanner: 'dict[str, object]', files: 'dict[str, TrackedFile]', directories: 'dict[str, DirectoryState]')

schema: str

project_uuid: str

project_name: str

created_at: str

updated_at: str

reason: str

scanner: dict[str, object]

files: dict[str, TrackedFile]

directories: dict[str, DirectoryState]

__init__(schema: str, project_uuid: str, project_name: str, created_at: str, updated_at: str, reason: str, scanner: dict[str, object], files: dict[str, TrackedFile], directories: dict[str, DirectoryState]) → None

class archledger.source_tracking.ChangedFile(path: 'str', change: 'str', old_sha256: 'str | None' = None, new_sha256: 'str | None' = None)

path: str

change: str

old_sha256: str | None

new_sha256: str | None

__init__(path: str, change: str, old_sha256: str | None = None, new_sha256: str | None = None) → None

class archledger.source_tracking.PossibleRename(old_path: 'str', new_path: 'str', sha256: 'str')

old_path: str

new_path: str

sha256: str

__init__(old_path: str, new_path: str, sha256: str) → None

class archledger.source_tracking.ImpactedRecord(id: 'str', type: 'str', title: 'str', status: 'str', section: 'str', path: 'str', matched_refs: 'tuple[str, ...]')

id: str

type: str

title: str

status: str

section: str

path: str

matched_refs: tuple[str, ...]

__init__(id: str, type: str, title: str, status: str, section: str, path: str, matched_refs: tuple[str, ...]) → None

class archledger.source_tracking.ChangeSet(baseline_exists: 'bool', baseline_updated_at: 'str | None', baseline_reason: 'str | None', current_scanned_at: 'str', scanner_used: 'str', file_count: 'int', changed_files: 'tuple[ChangedFile, ...]', possible_renames: 'tuple[PossibleRename, ...]', impacted_records: 'tuple[ImpactedRecord, ...]', impacted_sections: 'tuple[str, ...]', unlinked_changed_files: 'tuple[str, ...]', unbaselined_files: 'tuple[str, ...]' = ())

baseline_exists: bool

baseline_updated_at: str | None

baseline_reason: str | None

current_scanned_at: str

scanner_used: str

file_count: int

changed_files: tuple[ChangedFile, ...]

possible_renames: tuple[PossibleRename, ...]

impacted_records: tuple[ImpactedRecord, ...]

impacted_sections: tuple[str, ...]

unlinked_changed_files: tuple[str, ...]

unbaselined_files: tuple[str, ...]

__init__(baseline_exists: bool, baseline_updated_at: str | None, baseline_reason: str | None, current_scanned_at: str, scanner_used: str, file_count: int, changed_files: tuple[ChangedFile, ...], possible_renames: tuple[PossibleRename, ...], impacted_records: tuple[ImpactedRecord, ...], impacted_sections: tuple[str, ...], unlinked_changed_files: tuple[str, ...], unbaselined_files: tuple[str, ...] = ()) → None

archledger.source_tracking.scan_workspace(paths: ProjectPaths, config: ProjectConfig, *, reason: str = 'manual', scanned_at: str | None = None) → SourceState

archledger.source_tracking.diff_source_states(baseline: SourceState | None, current: SourceState) → ChangeSet

archledger.source_tracking.resolve_impacts(records: list[ArchitectureRecord], changes: ChangeSet, *, include_draft: bool, include_superseded: bool) → ChangeSet

class archledger.storage.project_config.Arc42Config(template_version: 'str', language: 'str', title: 'str', include_help: 'bool')

template_version: str

language: str

title: str

include_help: bool

__init__(template_version: str, language: str, title: str, include_help: bool) → None

class archledger.storage.project_config.BuildConfig(default_output: 'str', default_format: 'str', default_output_dir: 'str', include_draft: 'bool', include_superseded: 'bool', strict: 'bool', keep_intermediate: 'bool', converter: 'str', pdf_engine: 'str', reference_docx: 'str', outputs: 'dict[str, BuildOutputConfig]')

default_output: str

default_format: str

default_output_dir: str

include_draft: bool

include_superseded: bool

strict: bool

keep_intermediate: bool

converter: str

pdf_engine: str

reference_docx: str

outputs: dict[str, BuildOutputConfig]

__init__(default_output: str, default_format: str, default_output_dir: str, include_draft: bool, include_superseded: bool, strict: bool, keep_intermediate: bool, converter: str, pdf_engine: str, reference_docx: str, outputs: dict[str, BuildOutputConfig]) → None

class archledger.storage.project_config.BuildOutputConfig(enabled: 'bool | None' = None, tool: 'str | None' = None, pdf_engine: 'str' = '', reference_docx: 'str' = '')

enabled: bool | None

tool: str | None

pdf_engine: str

reference_docx: str

__init__(enabled: bool | None = None, tool: str | None = None, pdf_engine: str = '', reference_docx: str = '') → None

class archledger.storage.project_config.DiagramConfig(enabled: 'bool', renderer: 'str', default_type: 'str', output_dir: 'str', image_format: 'str', kroki_url: 'str')

enabled: bool

renderer: str

default_type: str

output_dir: str

image_format: str

kroki_url: str

__init__(enabled: bool, renderer: str, default_type: str, output_dir: str, image_format: str, kroki_url: str) → None

class archledger.storage.project_config.ProjectConfig(config_version: 'int', archledger_dir: 'str', project_uuid: 'str', project_name: 'str', id_prefix: 'str' = 'al', id_width: 'int' = 4, id_segment_mode: 'str' = 'none', id_default_segment: 'str' = 'content', id_segment_map: 'dict[str, str]'=<factory>, source_format: 'str' = 'markdown', source_schema_version: 'int' = 2, front_matter: 'str' = 'yaml', section_extension: 'str' = '.md', record_extension: 'str' = '.md', build_default_output: 'str' = 'architecture.md', build_default_format: 'str' = 'markdown', build_output_dir: 'str' = 'build', build_include_draft: 'bool' = False, build_include_superseded: 'bool' = False, build_strict: 'bool' = False, build_keep_intermediate: 'bool' = False, build_converter: 'str' = 'auto', build_pdf_engine: 'str' = '', build_reference_docx: 'str' = '', build_outputs: 'dict[str, dict[str, object]]'=<factory>, arc42_template_version: 'str' = '9.0-EN', arc42_language: 'str' = 'en', arc42_title: 'str' = 'Architecture Documentation', arc42_include_help: 'bool' = False, skill_installed: 'bool' = False, skill_path: 'str' = 'skills/archledger/SKILL.md', tracking_enabled: 'bool' = True, tracking_state_file: 'str' = 'source-state.json', tracking_scanner: 'str' = 'auto', tracking_include: 'tuple[str, ...]'=('**/*.py', '**/*.toml', '**/*.md', '**/*.adoc', '**/*.rst', '**/*.j2', '**/*.yaml', '**/*.yml', '**/*.json'), tracking_exclude: 'tuple[str, ...]'=('.git/**', '.venv/**', '**/__pycache__/**', '.mypy_cache/**', '.pytest_cache/**', '.ruff_cache/**', 'dist/**', 'build/**'), tracking_max_file_bytes: 'int' = 1000000, tracking_hash_algorithm: 'str' = 'sha256', diagram_enabled: 'bool' = False, diagram_renderer: 'str' = 'pass-through', diagram_default_type: 'str' = 'text', diagram_output_dir: 'str' = 'diagrams', diagram_image_format: 'str' = 'svg', diagram_kroki_url: 'str' = '')

config_version: int

archledger_dir: str

project_uuid: str

project_name: str

id_prefix: str

id_width: int

id_segment_mode: str

id_default_segment: str

id_segment_map: dict[str, str]

source_format: str

source_schema_version: int

front_matter: str

section_extension: str

record_extension: str

build_default_output: str

build_default_format: str

build_output_dir: str

build_include_draft: bool

build_include_superseded: bool

build_strict: bool

build_keep_intermediate: bool

build_converter: str

build_pdf_engine: str

build_reference_docx: str

build_outputs: dict[str, dict[str, object]]

arc42_template_version: str

arc42_language: str

arc42_title: str

arc42_include_help: bool

skill_installed: bool

skill_path: str

tracking_enabled: bool

tracking_state_file: str

tracking_scanner: str

tracking_include: tuple[str, ...]

tracking_exclude: tuple[str, ...]

tracking_max_file_bytes: int

tracking_hash_algorithm: str

diagram_enabled: bool

diagram_renderer: str

diagram_default_type: str

diagram_output_dir: str

diagram_image_format: str

diagram_kroki_url: str

property source: SourceConfig

property build: BuildConfig

property arc42: Arc42Config

property skill: SkillConfig

property ids: IdConfig

property id_format: LedgerIdFormat

property tracking: TrackingConfig

property diagrams: DiagramConfig

__init__(config_version: int, archledger_dir: str, project_uuid: str, project_name: str, id_prefix: str = 'al', id_width: int = 4, id_segment_mode: str = 'none', id_default_segment: str = 'content', id_segment_map: dict[str, str]=<factory>, source_format: str = 'markdown', source_schema_version: int = 2, front_matter: str = 'yaml', section_extension: str = '.md', record_extension: str = '.md', build_default_output: str = 'architecture.md', build_default_format: str = 'markdown', build_output_dir: str = 'build', build_include_draft: bool = False, build_include_superseded: bool = False, build_strict: bool = False, build_keep_intermediate: bool = False, build_converter: str = 'auto', build_pdf_engine: str = '', build_reference_docx: str = '', build_outputs: dict[str, dict[str, object]]=<factory>, arc42_template_version: str = '9.0-EN', arc42_language: str = 'en', arc42_title: str = 'Architecture Documentation', arc42_include_help: bool = False, skill_installed: bool = False, skill_path: str = 'skills/archledger/SKILL.md', tracking_enabled: bool = True, tracking_state_file: str = 'source-state.json', tracking_scanner: str = 'auto', tracking_include: tuple[str, ...]=('**/*.py', '**/*.toml', '**/*.md', '**/*.adoc', '**/*.rst', '**/*.j2', '**/*.yaml', '**/*.yml', '**/*.json'), tracking_exclude: tuple[str, ...]=('.git/**', '.venv/**', '**/__pycache__/**', '.mypy_cache/**', '.pytest_cache/**', '.ruff_cache/**', 'dist/**', 'build/**'), tracking_max_file_bytes: int = 1000000, tracking_hash_algorithm: str = 'sha256', diagram_enabled: bool = False, diagram_renderer: str = 'pass-through', diagram_default_type: str = 'text', diagram_output_dir: str = 'diagrams', diagram_image_format: str = 'svg', diagram_kroki_url: str = '') → None

class archledger.storage.project_config.IdConfig(prefix: 'str', width: 'int', segment_mode: 'str', default_segment: 'str', segment_map: 'dict[str, str]')

prefix: str

width: int

segment_mode: str

default_segment: str

segment_map: dict[str, str]

__init__(prefix: str, width: int, segment_mode: str, default_segment: str, segment_map: dict[str, str]) → None

class archledger.storage.project_config.SkillConfig(installed: 'bool', path: 'str')

installed: bool

path: str

__init__(installed: bool, path: str) → None

class archledger.storage.project_config.SourceConfig(format: 'str', schema_version: 'int', front_matter: 'str', section_extension: 'str', record_extension: 'str')

format: str

schema_version: int

front_matter: str

section_extension: str

record_extension: str

__init__(format: str, schema_version: int, front_matter: str, section_extension: str, record_extension: str) → None

class archledger.storage.project_config.TrackingConfig(enabled: 'bool', state_file: 'str', scanner: 'str', include: 'tuple[str, ...]', exclude: 'tuple[str, ...]', max_file_bytes: 'int', hash_algorithm: 'str')

enabled: bool

state_file: str

scanner: str

include: tuple[str, ...]

exclude: tuple[str, ...]

max_file_bytes: int

hash_algorithm: str

__init__(enabled: bool, state_file: str, scanner: str, include: tuple[str, ...], exclude: tuple[str, ...], max_file_bytes: int, hash_algorithm: str) → None

class archledger.storage.project_config.LedgerIdFormat(prefix: 'str' = 'al', width: 'int' = 4, segment_mode: 'str' = 'none')

prefix: str

width: int

segment_mode: str

property pattern_text: str

property reference_pattern_text: str

pattern() → Pattern[str]

reference_pattern() → Pattern[str]

format(number: int, *, segment: str | None = None) → str

parse_parts(record_id: str) → ParsedLedgerId

parse(record_id: str) → int

is_id(value: object) → bool

__init__(prefix: str = 'al', width: int = 4, segment_mode: str = 'none') → None

archledger.storage.project_config.build_default_project_config(workspace_root: Path, *, archledger_dir: str, source_format: str = 'markdown', id_prefix: str = 'al', id_width: int = 4, id_segment_mode: str = 'none', id_default_segment: str = 'content', id_segment_map: dict[str, str] | None = None, project_name: str | None = None, project_uuid: str | None = None, build_default_format: str | None = None, build_default_output: str | None = None, build_default_output_dir: str | None = None, build_include_draft: bool = False, build_include_superseded: bool = False, build_strict: bool = False, build_keep_intermediate: bool = False, build_converter: str = 'auto', build_pdf_engine: str = '', build_reference_docx: str = '', diagram_enabled: bool = False, diagram_renderer: str = 'pass-through', diagram_default_type: str = 'text', diagram_output_dir: str = 'diagrams', diagram_image_format: str = 'svg', diagram_kroki_url: str = '', arc42_template_version: str = '9.0-EN', arc42_language: str = 'en', arc42_title: str = 'Architecture Documentation', arc42_include_help: bool = False, tracking_enabled: bool = True, tracking_scanner: str = 'auto', tracking_state_file: str = 'source-state.json', tracking_max_file_bytes: int = 1000000, tracking_include: tuple[str, ...] | None = None, tracking_exclude: tuple[str, ...] | None = None) → ProjectConfig

archledger.storage.project_config.load_project_config(path: Path) → ProjectConfig

archledger.storage.project_config.normalize_project_name(name: str) → str

archledger.storage.project_config.render_default_config(workspace_root: Path, *, archledger_dir: str, source_format: str = 'markdown', project_name: str | None = None, project_uuid: str | None = None) → str

archledger.storage.project_config.render_project_config(config: ProjectConfig) → str