Project and configuration API

Modules

documentledger.project resolves canonical ledgercore projects. documentledger.config parses version-2 tool configuration. documentledger.models defines the typed records exchanged by these layers.

class documentledger.models.Config[source]

Bases: object

Config(root: ‘Path’, path: ‘Path’, project_name: ‘str’, project_uuid: ‘str’, storage_dir: ‘Path’, source_roots: ‘list[str]’, doc_roots: ‘list[str]’, source_extensions: ‘list[str]’, doc_extensions: ‘list[str]’, validation_commands: ‘list[str]’, require_doc_frontmatter: ‘bool’ = False)

Parameters:

• root (Path)

• path (Path)

• project_name (str)

• project_uuid (str)

• storage_dir (Path)

• source_roots (list[str])

• doc_roots (list[str])

• source_extensions (list[str])

• doc_extensions (list[str])

• validation_commands (list[str])

• require_doc_frontmatter (bool)

__init__(root, path, project_name, project_uuid, storage_dir, source_roots, doc_roots, source_extensions, doc_extensions, validation_commands, require_doc_frontmatter=False)

Parameters:

• root (Path)

• path (Path)

• project_name (str)

• project_uuid (str)

• storage_dir (Path)

• source_roots (list[str])

• doc_roots (list[str])

• source_extensions (list[str])

• doc_extensions (list[str])

• validation_commands (list[str])

• require_doc_frontmatter (bool)

Return type:

None

class documentledger.models.ToolConfig[source]

Bases: object

Documentledger’s tool-owned schema-2 configuration.

Project identity and storage routing deliberately do not live here. They are supplied by the shared ledgercore manifest and resolved layout.

Parameters:

• config_version (int)

• ledger_code (str)

• source_roots (tuple[str, ...])

• doc_roots (tuple[str, ...])

• source_extensions (tuple[str, ...])

• doc_extensions (tuple[str, ...])

• validation_commands (tuple[str, ...])

• require_doc_frontmatter (bool)

__init__(config_version, ledger_code, source_roots, doc_roots, source_extensions, doc_extensions, validation_commands, require_doc_frontmatter=False)

Parameters:

• config_version (int)

• ledger_code (str)

• source_roots (tuple[str, ...])

• doc_roots (tuple[str, ...])

• source_extensions (tuple[str, ...])

• doc_extensions (tuple[str, ...])

• validation_commands (tuple[str, ...])

• require_doc_frontmatter (bool)

Return type:

None

class documentledger.models.WorkspacePaths[source]

Bases: object

Resolved canonical or legacy paths, kept separate from tool config.

Parameters:

• project_root (Path)

• manifest_path (Path | None)

• local_config_path (Path | None)

• config_path (Path)

• data_dir (Path)

• artifacts_dir (Path | None)

• config_binding_path (Path | None)

• data_binding_path (Path | None)

• artifacts_binding_path (Path | None)

• layout_source (Literal['canonical', 'legacy'])

property storage_dir: Path

Compatibility alias for storage call sites during the migration.

__init__(project_root, manifest_path, local_config_path, config_path, data_dir, artifacts_dir, config_binding_path, data_binding_path, artifacts_binding_path, layout_source)

Parameters:

• project_root (Path)

• manifest_path (Path | None)

• local_config_path (Path | None)

• config_path (Path)

• data_dir (Path)

• artifacts_dir (Path | None)

• config_binding_path (Path | None)

• data_binding_path (Path | None)

• artifacts_binding_path (Path | None)

• layout_source (Literal['canonical', 'legacy'])

Return type:

None

class documentledger.models.Workspace[source]

Bases: object

Workspace(config: ‘Config’, metadata: ‘dict[str, object]’, paths: ‘WorkspacePaths | None’ = None, project_name: ‘str | None’ = None, project_uuid: ‘str | None’ = None)

Parameters:

• config (Config)

• metadata (dict[str, object])

• paths (WorkspacePaths | None)

• project_name (str | None)

• project_uuid (str | None)

__init__(config, metadata, paths=None, project_name=None, project_uuid=None)

Parameters:

• config (Config)

• metadata (dict[str, object])

• paths (WorkspacePaths | None)

• project_name (str | None)

• project_uuid (str | None)

Return type:

None

class documentledger.models.SourceUnit[source]

Bases: object

SourceUnit(source_id: ‘str’, path: ‘str’, kind: ‘str’, qualname: ‘str’, line_span: ‘tuple[int, int]’, signature: ‘str’, hashes: ‘dict[str, str]’)

Parameters:

• source_id (str)

• path (str)

• kind (str)

• qualname (str)

• line_span (tuple[int, int])

• signature (str)

• hashes (dict[str, str])

__init__(source_id, path, kind, qualname, line_span, signature, hashes)

Parameters:

• source_id (str)

• path (str)

• kind (str)

• qualname (str)

• line_span (tuple[int, int])

• signature (str)

• hashes (dict[str, str])

Return type:

None

class documentledger.models.DocSection[source]

Bases: object

DocSection(section_id: ‘str’, doc_path: ‘str’, heading_path: ‘list[str]’, heading_slug: ‘str’, line_span: ‘tuple[int, int]’, section_hash: ‘str’, summary: ‘str’, text: ‘str’)

Parameters:

• section_id (str)

• doc_path (str)

• heading_path (list[str])

• heading_slug (str)

• line_span (tuple[int, int])

• section_hash (str)

• summary (str)

• text (str)

__init__(section_id, doc_path, heading_path, heading_slug, line_span, section_hash, summary, text)

Parameters:

• section_id (str)

• doc_path (str)

• heading_path (list[str])

• heading_slug (str)

• line_span (tuple[int, int])

• section_hash (str)

• summary (str)

• text (str)

Return type:

None

class documentledger.models.ScanResult[source]

Bases: object

ScanResult(version: ‘int’, changed_sources: ‘list[str]’ = <factory>, deleted_sources: ‘list[str]’ = <factory>, stale_docs: ‘list[str]’ = <factory>, unlinked_changed_sources: ‘list[str]’ = <factory>, changed_units: ‘list[dict[str, Any]]’ = <factory>, added_units: ‘list[dict[str, Any]]’ = <factory>, deleted_units: ‘list[dict[str, Any]]’ = <factory>, affected_sections: ‘list[dict[str, Any]]’ = <factory>, unmapped_changed_units: ‘list[dict[str, Any]]’ = <factory>, source_units: ‘dict[str, dict[str, Any]]’ = <factory>, source_hashes: ‘dict[str, str]’ = <factory>, doc_hashes: ‘dict[str, str]’ = <factory>, unchanged: ‘bool’ = False)

Parameters:

• version (int)

• changed_sources (list[str])

• deleted_sources (list[str])

• stale_docs (list[str])

• unlinked_changed_sources (list[str])

• changed_units (list[dict[str, Any]])

• added_units (list[dict[str, Any]])

• deleted_units (list[dict[str, Any]])

• affected_sections (list[dict[str, Any]])

• unmapped_changed_units (list[dict[str, Any]])

• source_units (dict[str, dict[str, Any]])

• source_hashes (dict[str, str])

• doc_hashes (dict[str, str])

• unchanged (bool)

__init__(version, changed_sources=<factory>, deleted_sources=<factory>, stale_docs=<factory>, unlinked_changed_sources=<factory>, changed_units=<factory>, added_units=<factory>, deleted_units=<factory>, affected_sections=<factory>, unmapped_changed_units=<factory>, source_units=<factory>, source_hashes=<factory>, doc_hashes=<factory>, unchanged=False)

Parameters:

• version (int)

• changed_sources (list[str])

• deleted_sources (list[str])

• stale_docs (list[str])

• unlinked_changed_sources (list[str])

• changed_units (list[dict[str, Any]])

• added_units (list[dict[str, Any]])

• deleted_units (list[dict[str, Any]])

• affected_sections (list[dict[str, Any]])

• unmapped_changed_units (list[dict[str, Any]])

• source_units (dict[str, dict[str, Any]])

• source_hashes (dict[str, str])

• doc_hashes (dict[str, str])

• unchanged (bool)

Return type:

None