automatic error suppression for mypy
Project description
mypy-upgrade
Table of Contents
- What is
mypy-upgrade
? - Features
- Basic Usage
- Recommended Mypy Flags
- Using the API
- Command-Line Options
- Quick Start
- Known Limitations
- Similar Projects
What is mypy-upgrade
?
mypy-upgrade
is primarily a command-line utility that provides automatic
error suppression for mypy
(analogous to
pyre-upgrade
and
pylint-silent
). In addition,
mypy-upgrade
exposes an API with the same functionality.
Given a type checking report from mypy
, mypy-upgrade
will silence
the listed errors using error suppression comments. For example, with
the following output from mypy:
package/subpackage/module.py:13: error: Incompatible default for argument "filename" (default has type "None", argument has type "str") [assignment]
mypy-upgrade
will place a # type: ignore[assignment] # FIX ME
comment at the
end of line 13 in package/subpackage/module.py
. If error codes are not
present in the mypy
report (e.g., the --hide-error-codes
flag is set when
mypy
was invoked), then a non-specific # type: ignore # FIX ME
comment will be
added instead.
Features
-
Removal of unused
type: ignore
comments -
Replacement of blanket
type: ignore
comments with error code-specific comments -
Support for suppressing multiple mypy errors per-line
-
Preservation of existing in-line comments
-
Optional inclusion of
mypy
error description messages
Basic Usage
There are two idioms for invocation. To silence all errors in a package, one can:
-
pipe
mypy
's output directly tomypy-upgrade
mypy --strict -p my_package | mypy-upgrade
-
create a
mypy
type checking report text filemypy --strict -p my_package > mypy_report.txt
and then pass the file to
mypy-upgrade
mypy-upgrade --report mypy_report.txt
Command-Line Options
You may want to include the error messages provided by mypy
in the
suppression comments so that you can fix them later. You can do so using
the -d
(or --description-style
) option
mypy-upgrade --report mypy_report.txt -d full -p package
You can also customize the "fix me" message placed after the error suppression
comment using the --fix-me
option
mypy-upgrade --report mypy_report.txt --fix-me "FIX THIS" -p package
To selectively silence errors in packages and modules, use the -p
(--package
) and -m
(--module
) options along with the fully qualified
module/package name, respectively:
mypy-upgrade --report mypy_report.txt -p package1 -p package2 -m package1.module1 -m package2.module2
Similarly, to selectively silence errors in files and directories, pass them in as positional arguments:
mypy-upgrade --report mypy_report.txt path/to/a/package/ path/to/a/module.py
For a full list of all options and their descriptions, run mypy-upgrade --help
usage: mypy-upgrade [-h] [-m MODULE] [-p PACKAGE] [-r REPORT] [-d {full,none}] [--fix-me FIX_ME] [-v] [-V] [--suppress-warnings] [files ...]
Place in-line comments into files to silence mypy errors.
positional arguments:
files Silence errors from the provided files/directories.
options:
-h, --help show this help message and exit
-m MODULE, --module MODULE
Silence errors from the provided (importable) module. This flag may be repeated multiple times.
-p PACKAGE, --package PACKAGE
Silence errors from the provided (importable) package. This flag may be repeated multiple times.
-r REPORT, --report REPORT
The path to a text file containing a mypy type checking report. If not specified, input is read from standard input.
-d {full,none}, --description-style {full,none}
Specify the style in which mypy error descriptions are expressed in the error suppression comment. Defaults to "none".
--fix-me FIX_ME Specify a custom 'Fix Me' message to be placed after the error suppression comment. Pass " " to omit a 'Fix Me' message altogether. Defaults to
"FIX ME".
-v, --verbose Control the verbosity. 0: Only warnings are printed. 1: Print detailed warnings, a short summary of silenced errors, and a detailed list of errors
that were not silenced. 2: Print detailed warnings, a detailed list of silenced errors, and a detailed list of errors that were not silenced.
Defaults to 0. This flag may be repeated multiple times.
-V, --version Print the version.
--suppress-warnings Suppress all warnings. Disabled by default.
Using the API
Identical functionality to the command-line utility can be obtained using the
API. In addition, one obtains detailed information on the results of running
mypy-upgrade
. Assuming the mypy
type checking report is saved as
mypy_report.txt
, we have
import pathlib
from mypy_upgrade.silence import silence_errors_in_report
mypy_report = pathlib.Path("mypy_report.txt")
with mypy_report.open(mode="r", encoding="utf-8") as report:
result = silence_errors_in_report(
report=report
packages=["package1", "package2"],
modules=["package1.module1", "package2.module2"],
files=["path/to/a/package/", "path/to/a/module.py"],
description_style="full",
fix_me="FIX THIS",
)
silenced_errors, not_silenced_errors, messages = result
Recommended Mypy Flags
To enable all checks utilized by mypy-upgrade
to silence as many errors as possible, the
following flags should be set when creating the type checking report to pass to mypy-upgrade
:
-
--show-absolute-path
- Required if running
mypy-upgrade
in a separate directory thanmypy
- Required if running
-
--strict
- Enables
mypy-upgrade
to silence all possible mypy errors (see Known Limitations for exceptions)
- Enables
-
--show-error-codes
- Ensures that error-code specific comments are added instead of blanket
type: ignore
comments
- Ensures that error-code specific comments are added instead of blanket
-
--warn-unused-ignores
- Ensures that unused
type: ignore
comments are removed
- Ensures that unused
-
ignore-without-code
- When used with
--show-error-codes
, permitsmypy-upgrade
to replace existingtype: ignore
comments with code-specifictype: ignore
comments (enable from the command line with themypy
option--enable-error-code
)
- When used with
Quick Start
mypy-upgrade
can be installed via pip
.
python3 -m pip install mypy-upgrade
If you want to run the latest version of the code, you can install from the repo directly:
python3 -m pip install -U git+https://github.com/ugognw/mypy-upgrade.git@development
# or if you don't have 'git' installed
python3 -m pip install -U https://github.com/ugognw/mypy-upgrade/tree/development
Known Limitations
The following limitations derive mainly from Python syntax issues and are unable to be handled
by mypy-upgrade
. If you can't resolve the error directly, please consider refactoring to permit
error suppression.
-
Type errors on lines ending in line continuation characters or within multiline f-strings
-
Improperly specified type hints within comments
-
mypy
will report a type error if a type hint is improperly specified; for example, given the following code:x = {} # type: set
mypy
will produce atype-arg
error in column 1 andmypy-upgrade
will place a# type: ignore[type-arg]
comment at the end, which will, in turn, negate the effectiveness of the# type: set
commment and eliminate the need for the# type: ignore[type-arg]
comment -
-
mypy
"syntax"
errors are not silenced- It is recommended that you fix your code such that it is syntactically valid prior to using
mypy-upgrade
- It is recommended that you fix your code such that it is syntactically valid prior to using
Similar Projects
If this doesn't fit your use-case, maybe one of these other projects will!
-
geo7/mypy_clean_slate
:mypy
reports are generated internally in--strict
mode; includes support for suppressing multiple errors on a single line; an inspiration for much ofmypy-upgrade
's implementation -
whtsky/mypy-silent
: relies solely ontyper
+ the standard library; includes support for removing unusedtype: ignore
comments but no support for suppressing multiple errors on a single line; another inspiration for much ofmypy-upgrade
's implementation -
patrick91/mypy-silent
: a fork ofwhtsky/mypy-silent
with support for suppressing multiple errors on a single line (on thefeature/multiple-errors
branch) -
uptickmetachu/mypy-silent
: a fork ofwhtsky/mypy-silent
with support for suppressing multiple errors on a single line
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for mypy_upgrade-0.0.1b5-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 24793f8b01c729d85647860f70ec2f43b6af01322eebb163583ba050f6835872 |
|
MD5 | 8175c4fe35964267c424003c83941c04 |
|
BLAKE2b-256 | a21e7d3f6ae17b5a418626cd9e5f41f2359c11f1d8af18f2f62af7fda12e0313 |