settings

Resolves wiki_toolkit configuration.

build_context() resolves the full Context (docs_dir, repo_root, branch_prefix, batch_byte_cap, batch_file_cap) through a five-tier precedence chain: CLI flag > WIKI_TOOLKIT_<UPPER_SNAKE> env var > nearest .wiki-toolkit.toml (dedicated file, flat top-level keys) > nearest pyproject.toml’s [tool.wiki_toolkit] table > built-in default. Each file tier is found by walking upward from cwd, same convention as ruff/mypy; once found, it’s authoritative for that tier (a broken file or an invalid field value there falls through to the next tier rather than continuing to search further up). CLI-flag overrides are currently only wired up for docs_dir and repo_root; the other three fields start at the env tier.

CLASS	DESCRIPTION
Context	The full resolved wiki_toolkit configuration.
SettingsDiagnostics	Non-fatal settings-resolution problems, surfaced by doctor as warnings (never as failures).

FUNCTION	DESCRIPTION
build_context	Resolve the full Context per field, tracking which tier produced each value.
diagnose_settings	Diagnose non-fatal problems in settings resolution.

Classes

Context pydantic-model

Bases: BaseModel

The full resolved wiki_toolkit configuration.

Show JSON schema:

{
  "description": "The full resolved wiki_toolkit configuration.",
  "properties": {
    "docs_dir": {
      "format": "path",
      "title": "Docs Dir",
      "type": "string"
    },
    "repo_root": {
      "format": "path",
      "title": "Repo Root",
      "type": "string"
    },
    "branch_prefix": {
      "title": "Branch Prefix",
      "type": "string"
    },
    "batch_byte_cap": {
      "title": "Batch Byte Cap",
      "type": "integer"
    },
    "batch_file_cap": {
      "title": "Batch File Cap",
      "type": "integer"
    }
  },
  "required": [
    "docs_dir",
    "repo_root",
    "branch_prefix",
    "batch_byte_cap",
    "batch_file_cap"
  ],
  "title": "Context",
  "type": "object"
}

Fields:

• docs_dir (Path)
• repo_root (Path)
• branch_prefix (str)
• batch_byte_cap (int)
• batch_file_cap (int)

Attributes

sources property

sources: dict[str, ContextConfigSource]

Per-field source (flag/env/dedicated_file/pyproject/default), set by build_context().

SettingsDiagnostics dataclass

SettingsDiagnostics(
    dual_config_files: bool = False,
    repo_root_fallback: bool = False,
    invalid_sources: dict[str, ContextConfigSource] = dict(),
)

Non-fatal settings-resolution problems, surfaced by doctor as warnings (never as failures).

Functions:

build_context

build_context(
    docs_dir_flag: Path | None = None,
    repo_root_flag: Path | None = None,
    cwd: Path | None = None,
) -> tuple[Context, dict[str, ContextConfigSource]]

Resolve the full Context per field, tracking which tier produced each value.

Precedence per field: CLI flag > env var > dedicated file > pyproject.toml > default.

diagnose_settings

diagnose_settings(
    sources: dict[str, ContextConfigSource], cwd: Path | None = None
) -> SettingsDiagnostics

Diagnose non-fatal problems in settings resolution.

sources is the per-field source mapping from build_context(), used to tell which fields ultimately fell back to default – the only case where a dropped invalid value upstream is worth naming.