Skip to content

Diagnostics

TyPy reports every problem it finds in one run, each as a diagnostic.

What TyPy does

Item Rule
Every diagnostic has a stable code, a file:line:column place with columns counted in code points, and one sentence that says what is wrong DIA-01
A certain fix is shown as the corrected line under help: DIA-02
A diagnostic that refuses valid Python names the rule the program falls outside DIA-03
One root cause gives one error DIA-04
--error-format=json writes each diagnostic as one JSON object per line DIA-05
Warnings never fail a build unless --deny-warnings is given DIA-07
A warning where CPython warns while compiling: W0101, W0301 DIA-08
A warning for a match that leaves members of its subject's type unmatched: W0401 CST-07
A code is never reused DIA-06

Troubleshooting explains every code.

Warnings

A warning reports a program TyPy accepts, with CPython's meaning, that is probably not what you meant. TyPy warns where CPython 3.12 to 3.15 give a SyntaxWarning while compiling: an invalid escape sequence, W0101, and an assertion that is always true, W0301. It also warns, as type checkers do, about a match that leaves members of its subject's type unmatched, W0401 (ADR-0033). This program builds, runs and prints \d, with a warning that shows "\\d" as the fix:

print("\d")

typy check, build and run exit with status 0 when there are only warnings. With --deny-warnings they exit with status 1 and write no executable, which suits CI.

Diagnostics as JSON

An editor or a CI job runs typy check app.py --error-format=json and reads one object per line from standard error. Every object has the same keys, with null where a diagnostic has nothing, and lines and columns count from 1, with columns in characters:

{"code":"E0402","severity":"error","message":"`ratio` was declared as float
and is assigned an int","file":"app.py","line":1,"column":16,"end_line":1,
"end_column":17,"rule":"TYP-09","help":null,"labels":[{"line":1,"column":1,
"text":"the variable"}],"fix":{"line":1,"column":16,"end_line":1,
"end_column":17,"replacement":"1.0"}}

The object is one line; it is wrapped here to fit the page.

Key Value
code, severity, message The code, "error" or "warning", and the sentence
file, line, column, end_line, end_column Where the problem is
rule The rule it enforces, such as "TYP-09"
help A hint, when there is one
labels Other places, each with line, column and text
fix A certain fix: the span to replace and its replacement

The exit status is the same as with text.

Example

A program with no problems checks cleanly:

ratio: float = 1.0
print(ratio)

An int where a float is declared is refused, and the diagnostic shows the corrected line, ratio: float = 1.0:

ratio: float = 1
print(ratio)