Configuration

Configuration loading and schema for jamb.

JambConfig

class jamb.config.loader.JambConfig

Configuration schema for jamb.

test_documents

Document prefixes that represent test specifications.

Type:

list[str]

fail_uncovered

Fail the pytest session when any normative item lacks test coverage.

Type:

bool

require_all_pass

Require all linked tests to pass for an item to be considered covered.

Type:

bool

test_matrix_output

File path for the generated test records matrix, or None to skip generation. Format is inferred from file extension (.html, .json, .csv, .md, .xlsx).

Type:

str | None

trace_matrix_output

File path for the generated traceability matrix, or None to skip generation. Format is inferred from file extension (.html, .json, .csv, .md, .xlsx).

Type:

str | None

exclude_patterns

Glob patterns for documents or items to exclude from processing.

Type:

list[str]

trace_to_ignore

Document prefixes to exclude from the “Traces To” column in the traceability matrix.

Type:

list[str]

software_version

Software version for the traceability matrix. If None, auto-parsed from [project].version in pyproject.toml.

Type:

str | None

trace_from

Starting document prefix for full chain trace matrix generation. When set, generates a full chain matrix instead of the simple trace matrix.

Type:

str | None

include_ancestors

Whether to include a “Traces To” column showing ancestors of the starting items in full chain matrices.

Type:

bool

tc_id_prefix

Prefix for auto-generated test case IDs. Defaults to "TC", producing IDs like TC001, TC002. Custom prefixes allow project-specific formats (e.g., "TEST-" → TEST-001). Must contain only alphanumeric characters, hyphens, or underscores.

Type:

str

matrix_columns

Extra columns to display in the full chain traceability matrix. Each entry defines a column sourced from a custom attribute or a built-in resolver.

Type:

list[MatrixColumnConfig]

publish_html_theme

Path to a Quarto SCSS theme applied to published HTML, or None to use the bundled default theme.

Type:

str | None

publish_docx_reference

Path to a Word reference document applied to published DOCX, or None for Quarto’s default styling.

Type:

str | None

publish_pdf_template

Path to a Typst preamble applied to published PDF, or None to use the bundled default.

Type:

str | None

publish_status

Document status (e.g. "Draft", "Approved") shown on the published title page, or None to omit.

Type:

str | None

Construct a config with custom settings::

    >>> config = JambConfig(
    ...     test_documents=["SRS"],
    ...     fail_uncovered=True,
    ...     test_matrix_output="test-records.html",
    ... )
    >>> config.test_documents
    ['SRS']
    >>> config.fail_uncovered
    True

validate(available_documents)

Validate configuration against available documents.

Parameters:

available_documents (list[str]) – List of document prefixes discovered in the project.

Returns:

list[str] – List of validation warning messages. Empty if no issues found.

Raises:

ValueError – If tc_id_prefix contains invalid characters.

Return type:

list[str]

__init__(test_documents=<factory>, fail_uncovered=False, require_all_pass=True, test_matrix_output=None, trace_matrix_output=None, exclude_patterns=<factory>, trace_to_ignore=<factory>, software_version=None, trace_from=None, include_ancestors=False, tc_id_prefix='TC', matrix_columns=<factory>, publish_html_theme=None, publish_docx_reference=None, publish_pdf_template=None, publish_status=None)

Parameters:

• test_documents (list[str])

• fail_uncovered (bool)

• require_all_pass (bool)

• test_matrix_output (str | None)

• trace_matrix_output (str | None)

• exclude_patterns (list[str])

• trace_to_ignore (list[str])

• software_version (str | None)

• trace_from (str | None)

• include_ancestors (bool)

• tc_id_prefix (str)

• matrix_columns (list[MatrixColumnConfig])

• publish_html_theme (str | None)

• publish_docx_reference (str | None)

• publish_pdf_template (str | None)

• publish_status (str | None)

Return type:

None

load_config

jamb.config.loader.load_config(config_path=None)

Load jamb configuration from pyproject.toml.

Looks for [tool.jamb] section. Also auto-parses software version from [project].version if not explicitly set in [tool.jamb].

Parameters:

config_path (Path | None) – Optional path to pyproject.toml. If None, uses cwd.

Returns:

JambConfig – JambConfig with loaded values or defaults.

Return type:

JambConfig

Load configuration from the default path (``pyproject.toml`` in
the current working directory)::

    >>> config = load_config()
    >>> config.matrix_format
    'html'

Load from a specific path::

    >>> from pathlib import Path
    >>> config = load_config(Path("myproject/pyproject.toml"))