app.domain.issues

Validation issue value types shared by the domain modules.

An issue is stored per record as {"severity", "code", "message"} (see Issue.to_dict() / Issue.from_dict()). Messages are short and actionable and are meant to be shown to readers as-is.

Public API: Severity, IssueCode, Issue, has_errors().

class app.domain.issues.Severity(*values)

Bases: StrEnum

Severity of a validation issue.

ERROR = 'error'
WARNING = 'warning'
class app.domain.issues.IssueCode(*values)

Bases: StrEnum

Stable machine-readable validation issue codes.

BAD_YAML = 'bad_yaml'
MISSING_FRONTMATTER = 'missing_frontmatter'
MISSING_UUID = 'missing_uuid'
BAD_UUID = 'bad_uuid'
BAD_DATE = 'bad_date'
MISSING_DATE = 'missing_date'
UNKNOWN_FIELD = 'unknown_field'
BAD_FIELD_TYPE = 'bad_field_type'
DUPLICATE_UUID = 'duplicate_uuid'
MISSING_TARGET = 'missing_target'
AMBIGUOUS_TARGET = 'ambiguous_target'
LEGACY_ALIAS = 'legacy_alias'
LEGACY_SIGNOFF = 'legacy_signoff'
CORRECTS_ON_NON_ERRATUM = 'corrects_on_non_erratum'

Retired: no longer emitted (corrects is now a legacy field). Kept so issues stored by earlier versions still decode.

ERRATUM_WITHOUT_TARGET = 'erratum_without_target'
BAD_ENCODING = 'bad_encoding'
BAD_ERRATUM_TYPE = 'bad_erratum_type'
ERRATUM_MISSING_CORRECTED_TEXT = 'erratum_missing_corrected_text'
ERRATUM_UNKNOWN_SECTION_HEADING = 'erratum_unknown_section_heading'
ERRATUM_DUPLICATE_SECTION = 'erratum_duplicate_section'
ERRATUM_TARGETS_ITSELF = 'erratum_targets_itself'
ERRATUM_RELATIONSHIP_IGNORED = 'erratum_relationship_ignored'
ERRATUM_TARGET_IS_ERRATUM = 'erratum_target_is_erratum'

Read-time only: an erratum’s erratum-for resolved to another erratum (see app.services.record_relationships).

LEGACY_ERRATUM_FORMAT = 'legacy_erratum_format'
OBSOLETE_KIND_FIELD = 'obsolete_kind_field'
class app.domain.issues.Issue(severity, code, message)

Bases: object

One validation finding for a record.

Parameters:

  • severity (Severity) – How serious the finding is.

  • code (IssueCode) – Stable issue code.

  • message (str) – Concise, actionable human-readable message.

severity: Severity
code: IssueCode
message: str
to_dict()

Convert the issue to a JSON-serialisable mapping.

Return type:

dict[str, str]

Returns:

{"severity": ..., "code": ..., "message": ...}.

classmethod from_dict(data)

Rebuild an issue from to_dict() output.

Parameters:

data (Mapping[str, str]) – Mapping with severity, code and message.

Return type:

Issue

Returns:

The issue.

Raises:
app.domain.issues.error(code, message)

Build an error-severity issue.

Parameters:

  • code (IssueCode) – Issue code.

  • message (str) – Human-readable message.

Return type:

Issue

Returns:

The issue.

app.domain.issues.warning(code, message)

Build a warning-severity issue.

Parameters:

  • code (IssueCode) – Issue code.

  • message (str) – Human-readable message.

Return type:

Issue

Returns:

The issue.

app.domain.issues.has_errors(issues)

Tell whether any issue has error severity.

Parameters:

issues (Iterable[Issue]) – Issues to inspect.

Return type:

bool

Returns:

True if at least one issue is an error.