Skip to content

solvi.check

solvi check: catalog lint.

solvi check: catalog lint — mistakes a catalog can carry for a long time before a decision shows them.

from solvi.check import lint
rep = lint(system)                 # a System (or a Catalog: the question checks are skipped)
print(rep); rep.ok                 # errors fail; warnings fail with strict=True (solvi check --strict)

solvi check myapp.decisions:system [--strict] [--json]     # exit 0: no errors; 1: errors; 2: usage errors
solvi check myapp.decisions:system --sensitive age,sex      # parts that read these (or what is computed from them)
solvi check myapp.decisions:system --text POLICY.md         # then every part's cite= is looked for in the text
solvi check myapp.decisions:system --spec POLICY.md [--require-cites]   # and its clause= against Spec(text)'s clauses

from solvi.check import citations
citations(system, policy_text, spec=None, require=False)   # → Report: the citations of the parts (see citations)

Errors (a decision is, or can be, wrong or impossible): then_not_in_flow a hard check sets then= for a question whose flow does not run it. Since 1.0 the deterministic strategist (and CostStrategist) puts such a check into the question's flow by itself, and System() refuses a strategist of your own that leaves it out — so this fires only for a system built around that (when the check failed, the question would be answered as if it had passed) then_unknown / then_bad_answer then= names no question / an answer that is not one of the question's options (for a then function: a literal it plainly returns; None and "abstain" are a named abstention, not an error) cycle facts that need each other: none of them can be computed unless one is given (facts derived from each other, each with a producer outside the loop, are a cycle for the deterministic strategist only; with System(strategist=...) they are the note mutual_producers) unanswerable a question no input can answer (its flow needs a fact nothing can compute; a span / rank / estimate question without a rule — a learned head cannot answer it; a missing required part) type_conflict a producer's return type that its consumer cannot read; a System(input_model=...) field that a typed reader cannot read constraint_never_holds / constraints_conflict constraints between answers that no combination of answers satisfies (brute force over the answers' finite domains) constraint_unknown_question a constraint that reads a name that is not a question: it never applies validate_reads_unknown a producer's validate requires an argument no producer of its fact takes as an input: it cannot run, so every output of that producer is rejected (a System refuses such a catalog) hard_check_untyped a hard check without -> bool with a return that is plainly not True or False (return 0, return None, a bare return, a string): on that path the check is rejected and every question it governs abstains — return a bool and declare it -> bool hard_check_never_runs a hard check with no then=, required by no question and read by no part: no question's flow reaches it, so it never stops an answer (System() warns about it) — add requires=[...] to the questions it guards, or then= rule_returns_non_option a rule with return <literal> (also in a if c else b) that is not one of its question's options (return "aprove"): on that path the question abstains reads_sensitive a part (fn, extract, check, rule, a then function, an alternative producer, a constraint) reads a sensitive field: one declared with Catalog(sensitive=...) or given to lint(sensitive=...) / solvi check --sensitive age,sex reads_sensitive_via a part reads a fact computed from a sensitive field (the message gives the chain: "reads 'risk_band', computed from 'age'"); a fact a part computes from a tainted fact is tainted too Warnings: rule_unchecked a rule of a yes/no, choice, ordinal or multi-label question whose return values cannot be read (no source: made by exec, a callable object; a lambda that cannot be told apart on its line), so rule_returns_non_option did not check it unused_part a part no question's flow uses (a question without a rule, fit or uses uses everything computable: those are the candidate features of the head it will be fitted with) then_on_soft_check then= on a check that is not hard: it is ignored question_as_fact a rule, part or check's then function reads a question's name: answers are not facts, so it must be given in the input (error for hard checks) reader_types_differ typed readers of a given fact, or alternative producers of a fact, that no value can satisfy both dead_option an option the constraints rule out whatever the other answers are constraint_raises a constraint that raises on some combination of answers (it counts as broken) unused_rule a rule registered for a question that is not among the System's questions: it never runs input_not_declared with System(input_model=Model): a part or a rule reads a name that is neither computed by a part nor a field of the model (amout for amount) — it can only arrive as an extra key of the input; when the model forbids extra keys it can never arrive uses_unknown with System(input_model=Model): a question's uses hint names something that is neither a part nor a field of the model. (Without an input model a uses name that is not a part is taken for a given fact — a learned head may read given facts directly — so a typo there cannot be told; a misspelled requires entry is an error: unanswerable) silent_default in a function that reads the input (a given fact): x or <literal> or .get(k, <literal>) on that input (amount or 0, order.get("total", 0); not a lookup in a constant table or a default on a computed value), which turns a missing, empty or null input into a value nobody gave — say so explicitly (check for None and abstain, or declare the default in System(input_model=...)); # solvi: ok on the line accepts it (parts of the solvi package itself are skipped: the user can neither edit them nor mark them) check_shares_call a check declared with Catalog.check(shares_call_with=X): it re-reads X's model call, so it agrees with X's answer whatever that answer is — not an independent check (also when X names no part or question) checks_one_family the checks in a question's flow that declare family= are all of one family (two or more): they err together, so agreeing does not make the answer surer — add a check of another family or code The wording of a question a model answers (no rule, or a rule with model=) — what the model reads: no_other_option a choice with no catch-all option ("other", "none of these", "unknown", "oos", "abstain", "misc", ..., or one described as "anything else"), no decider other= and no "not stated" (Answer.maybe): when no option fits, the model still picks one, often confidently numeric_levels a choice or ordinal whose options are bare numbers ("1".."5") without a description of each: say what each level means (a dict {level: description}). A choice is judged only when its options read as a small integer scale (consecutive from 0 or 1, the top open: "3+", "3 or more"): years and other numbers that are not levels do not fire it; an ordinal's numbers always do Of every question: compound_question a question text that asks two things (two question marks, or "and whether" / "or whether"; a "?" inside quotes or parentheses is not a question of its own): one answer cannot say yes to one half and no to the other — split it unused_given with System(input_model=Model): a field of the model that no part, rule, check, constraint, uses hint or span reads (checked only when every question has a rule or a uses hint: a learned head may read any given fact) Notes (never fail): mutual_producers facts derived from each other (net from gross and gross from net), each with a producer outside the loop: the system's strategist plans around it no_rule a question without a rule answers only after fit (it abstains until then) sensitive_unread a sensitive field no part reads (declared, nothing reads it: fine)

Citations (solvi.check.citations; solvi check --text): cite_not_found a part's quote (cite=) is not in the text — in the catalog's quote mode: "normalized" finds it across Unicode forms, dashes, spaces and curly quotes (error) clause_unknown with spec=: the part names a clause the specification does not have (error) cite_outside_clause with spec=: the quote is in the text but not in the clause the part names (error) no_cite with require=True: a part without a citation (warning)

The flows are planned with every given fact present (solvi.core.plan.strategist.given_facts), as solvi serve does, by the system's own strategist (System(strategist=)) — the deterministic one when none is set.

Finding dataclass

Finding(level: str, code: str, where: str, message: str)

One problem solvi check found: its level (error, warning or note), code (see the module docs), where (a part, a question, a constraint or file:line) and the message.

Report dataclass

Report(findings: list = list(), strict: bool = False)

ok property

ok

No errors (and, with strict, no warnings).

lint

lint(obj, strict=False, max_combos=100000, sensitive=None)

A System (or a Catalog) → Report. max_combos: the largest number of answer combinations tried per group of constraints that share questions. sensitive: names of given facts no part may read (age, sex, ...), added to the catalog's own Catalog(sensitive=...); a part that reads one, or a fact computed from one, is an error (reads_sensitive, reads_sensitive_via). Nothing changes at ask time: lint is where it is refused.

sensitive_names

sensitive_names(cat, sensitive=None)

The sensitive fields of a catalog: its own Catalog(sensitive=...) and sensitive (a name or names) → set.

silent_defaults

silent_defaults(func, names=None)

[(line, snippet, why)] in a function's source: x or <literal> and .get(k, <literal>) (the literal not None), except on lines marked # solvi: ok. [] when the source is not available. names: the function's arguments that are given inputs — then only a default on one of them counts (amount or 0, order.get("total", 0), order["x"] or 0), not one on a constant table ({...}.get(kind, 1)), a computed value (math.sqrt(v) or 1e-9) or an exception's attribute (e.lineno or 0).

split_clauses

split_clauses(text: str) -> list[tuple[str, str]]

A text → [(section, clause text)]: each paragraph, list item and table row is a clause (a table row is written as header: cell; ...); headings name the section and are not clauses themselves.

spec_clauses

spec_clauses(text)

A specification's text → {"c1": clause text, ...}: the clauses solvi.core.versions.Spec(text) numbers.

citations

citations(obj, text, *, spec=None, require=False)

The citations of a catalog's parts (cite= / clause= on the decorators: Part.cites) against the text they quote → Report. Every quote must be in text, found as solvi.core.catalog.find_quote finds it with the part's quote mode ("normalized" by default: Unicode form, dashes, spaces, curly quotes; the source's own substring is what counts) — else the error cite_not_found. With spec (a solvi.core.versions.Spec, or {clause id: text} — spec_clauses(text) numbers a text's clauses as Spec does) a clause id must be one of its clauses (clause_unknown) and the quote must lie in that clause's text (cite_outside_clause; a table row, which the Spec writes as header: cell; ..., is also compared by its cells). A clause id with a ":" — a person's correction, clause="person:k07" — is no clause of the specification: its quote is looked for in text only. require=True: a part without a citation is the warning no_cite (a policy catalog that wants every rule to cite its clause). obj: a System or a Catalog.

cmd_check

cmd_check(a)

solvi check (see solvi.cli) → 0: no errors (with --strict: no warnings either); 1: problems. The target is module:attr / file.py:attr, or — as for solvi test — a task file or a directory holding task.py (its System: task.system(), else System(task.cat, task.QUESTIONS)).