Skip to content

Checks

A check runs the passes over a model, reports each rule at its level and returns a report.

check_model 

check_model(
    model: Model,
    *,
    rules: Mapping[str, Level] | None = None,
    max_diagnostics: int | None = None,
    provenance: Provenance | None = None,
    catalog: Catalog | None = None,
    settings: Settings | None = None,
) -> Report

Check a model and return a report.

Parameters:

Name Type Description Default
model Model

The model to check.

 required
rules Mapping[str, Level] | None

Levels by rule name, or all for every rule, over those the settings give: error, warn or ignore.

 None
max_diagnostics int | None

Maximum number of diagnostics in the report; the error and warning counts cover every diagnostic found.

 None
provenance Provenance | None

Where the build script placed each element, so the report names script lines; see :meth:bricky.ModelBuilder.provenance.

 None
catalog Catalog | None

Catalog to resolve parts and colors against; :func:bricky.default_catalog by default.

 None
settings Settings | None

Settings to read rule levels and passes' options from; read from the environment and the configuration file by default.

 None

Raises:

Type Description
BrickyError

If the settings or rules name a rule no installed pass checks.

Level

How a check reports a rule's diagnostics, by the names ty gives its levels.

diagnostics

Diagnostics: the facts that passes report, and the reports that collect them.

A rule is one kind of fact a pass checks, such as floating-group. It has a default level and an exact condition, which bricky explain prints. A diagnostic states one such fact about the model: what is wrong, the elements involved and their region. A diagnostic never prescribes a fix: the agent decides what to change.

A check reports each rule at a level: error, warn or ignore. A report gives the level of every rule. It also says what each element a diagnostic names is, and which line of the build script placed it.

Report

The result of a check: a model's diagnostics and what each named element is.

ok property 

ok: bool

Whether the model is free of errors.

is_error 

is_error(diagnostic: Diagnostic) -> bool

Whether the check reported a diagnostic as an error, not as a warning.

Diagnostic

One fact about the model, found by a pass under one rule.

Rule

A fact a pass checks: its name, its default level and the exact condition.

Region

An axis-aligned region: x and y in studs, z in plates.

of classmethod 

of(box: Box) -> Region

Convert a box in base units to a region in studs and plates.

ElementInfo

What an element named by a diagnostic is, and which script line placed it.

format_report 

format_report(report: Report) -> str

Format a report as compiler-style text.

registry

The pass plugin protocol, discovery, and the levels that checks report rules at.

A pass is any class with a name, a one-line summary, the rules it checks and a run method. Packages register passes under the bricky.passes entry-point group, so a pass pack installs and uninstalls without changes to the core. People configure rules, never passes: a check runs each pass that checks a rule not ignored.

ENTRY_POINT_GROUP module-attribute 

ENTRY_POINT_GROUP: Final = 'bricky.passes'

The entry-point group that packages register passes under.

BUILT_IN module-attribute 

BUILT_IN: Final = (
    "schema",
    "collision",
    "connectivity",
    "stability",
)

The passes of bricky itself, in the order checks run them; others follow, by name.

Pass

A check that reads a model's shared analyses and reports facts as diagnostics.

name class-attribute 

name: str

The pass's name, which bricky explain gives beside each of its rules.

summary class-attribute 

summary: str

One line on what the pass checks.

rules class-attribute 

rules: tuple[Rule, ...]

Every rule the pass checks, with its default level and exact condition.

run 

run(context: Context) -> Iterable[Diagnostic]

Return the diagnostics found in the model.

installed_passes cached 

installed_passes() -> Mapping[str, type[Pass]]

Return every installed pass by name, discovered once per process.

The passes of :data:BUILT_IN come first, in that order.

installed_rules cached 

installed_rules() -> Mapping[str, tuple[str, Rule]]

Return every rule an installed pass checks, with the name of that pass.

The rules come in the order of their passes, then as each pass lists them.

Raises:

Type Description
BrickyError

If two installed passes claim the same rule, or a pass names a rule all, the key that sets every rule.

resolve_levels 

resolve_levels(
    *layers: tuple[str, Mapping[str, Level]],
) -> dict[str, Level]

Return the level of every installed rule, ordered as :func:installed_rules.

Each rule starts at its default level. Each layer then applies in turn, such as the settings and then a command's options: all sets every rule, and a rule's own entry overrides it. A layer comes with the name that errors give it.

Raises:

Type Description
BrickyError

If a layer names a rule that no installed pass checks.

run_passes 

run_passes(
    context: Context, levels: Mapping[str, Level]
) -> list[Diagnostic]

Run every pass that checks a rule not ignored, and keep those rules' diagnostics.

Parameters:

Name Type Description Default
context Context

The model and its shared analyses.

 required
levels Mapping[str, Level]

The level of every installed rule, as :func:resolve_levels returns.

 required

Raises:

Type Description
BrickyError

If a pass reports a rule it does not list.