proteobench.validation.report module#

Structured validation report objects for ProteoBench submission validation.

This module defines the data model returned by the validation layer (proteobench.validation.validator.validate_submission()). The report is a plain, framework-agnostic container so that it can be produced in the core library and rendered by any front end (Streamlit, notebooks, CLI).

It exposes three objects: Severity (the issue severity enumeration), ValidationIssue (a single machine- and human-readable finding), and ValidationReport (a collection of issues with overall pass/fail helpers).

class proteobench.validation.report.Severity(value)[source]#

Bases: str, Enum

Severity level of a validation issue.

Severity controls only display prominence and inclusion in the pull-request summary; it does not gate the Streamlit submission flow (no severity blocks submission). It also drives the optional programmatic ValidationReport.raise_if_errors() path.

ERROR = 'error'#
INFO = 'info'#
WARNING = 'warning'#
class proteobench.validation.report.ValidationIssue(code: str, severity: Severity, message: str, check: str, field: str | None = None, observed: Any = None, expected: Any = None, examples: List[Any] = <factory>)[source]#

Bases: object

A single validation finding.

code#

Machine-readable issue code (stable identifier, e.g. "protein_not_in_fasta").

Type:

str

severity#

Severity of the issue.

Type:

Severity

message#

Human-readable description of the issue.

Type:

str

check#

Name of the check that produced the issue (e.g. "protein_ids").

Type:

str

field#

Relevant field, file, or column name the issue refers to.

Type:

str, optional

observed#

Observed value (or a short summary of it).

Type:

Any, optional

expected#

Expected value or allowed range, where applicable.

Type:

Any, optional

examples#

A small number of example offending rows or identifiers.

Type:

list, optional

check: str#
code: str#
examples: List[Any]#
expected: Any = None#
field: str | None = None#
message: str#
observed: Any = None#
severity: Severity#
to_dict() → Dict[str, Any][source]#

Convert the issue to a JSON-serialisable dictionary.

Returns:

Dictionary representation of the issue.

Return type:

dict

class proteobench.validation.report.ValidationReport(issues: List[ValidationIssue] = <factory>)[source]#

Bases: object

Collection of validation issues with overall status helpers.

issues#

Issues collected during validation.

Type:

list of ValidationIssue

add(code: str, severity: Severity, message: str, check: str, field: str | None = None, observed: Any = None, expected: Any = None, examples: List[Any] | None = None) → ValidationReport[source]#

Append a new issue to the report.

Parameters:

  • code (str) – Machine-readable issue code.

  • severity (Severity) – Severity of the issue.

  • message (str) – Human-readable description.

  • check (str) – Name of the originating check.

  • field (str, optional) – Relevant field, file, or column name.

  • observed (Any, optional) – Observed value.

  • expected (Any, optional) – Expected value or allowed range.

  • examples (list, optional) – Example offending rows or identifiers.

Returns:

The report itself, to allow chaining.

Return type:

ValidationReport

add_error(code: str, message: str, check: str, **kwargs: Any) → ValidationReport[source]#

Append an ERROR issue.

Parameters:

  • code (str) – Machine-readable issue code.

  • message (str) – Human-readable description.

  • check (str) – Name of the originating check.

  • **kwargs (dict) – Optional field, observed, expected, and examples values.

Returns:

The report itself, to allow chaining.

Return type:

ValidationReport

add_info(code: str, message: str, check: str, **kwargs: Any) → ValidationReport[source]#

Append an INFO issue.

Parameters:

  • code (str) – Machine-readable issue code.

  • message (str) – Human-readable description.

  • check (str) – Name of the originating check.

  • **kwargs (dict) – Optional field, observed, expected, and examples values.

Returns:

The report itself, to allow chaining.

Return type:

ValidationReport

add_warning(code: str, message: str, check: str, **kwargs: Any) → ValidationReport[source]#

Append a WARNING issue.

Parameters:

  • code (str) – Machine-readable issue code.

  • message (str) – Human-readable description.

  • check (str) – Name of the originating check.

  • **kwargs (dict) – Optional field, observed, expected, and examples values.

Returns:

The report itself, to allow chaining.

Return type:

ValidationReport

property errors: List[ValidationIssue]#

Return all ERROR issues.

Returns:

The error-level issues.

Return type:

list of ValidationIssue

extend(issues: List[ValidationIssue]) → ValidationReport[source]#

Append several issues at once.

Parameters:

issues (list of ValidationIssue) – Issues to add.

Returns:

The report itself, to allow chaining.

Return type:

ValidationReport

property has_errors: bool#

Whether the report contains any ERROR issue.

Returns:

True if at least one error is present.

Return type:

bool

property infos: List[ValidationIssue]#

Return all INFO issues.

Returns:

The info-level issues.

Return type:

list of ValidationIssue

issues: List[ValidationIssue]#
property passed: bool#

Overall pass status (no ERROR issues).

This is informational only: the Streamlit submission flow does not gate on it (submission is never blocked). It is used for display and by the optional raise_if_errors() path.

Returns:

True when there are no ERROR issues (warnings allowed).

Return type:

bool

raise_if_errors() → None[source]#

Raise SubmissionValidationError if any error issue is present.

Raises:

SubmissionValidationError – If the report contains at least one ERROR issue.

summary(include_info: bool = False) → str[source]#

Build a compact Markdown summary of the report.

Useful for embedding the findings into pull-request text or logs. The wording is neutral: submission validation does not block submission, it only surfaces points for the submitter and reviewers to consider.

Parameters:

include_info (bool, optional) – Whether to include INFO issues in the summary. Default False.

Returns:

Markdown-formatted summary.

Return type:

str

to_dict() → Dict[str, Any][source]#

Convert the report to a JSON-serialisable dictionary.

Returns:

Dictionary with overall status and the list of issues.

Return type:

dict

property warnings: List[ValidationIssue]#

Return all WARNING issues.

Returns:

The warning-level issues.

Return type:

list of ValidationIssue