Skip to content

Commit 7b710ad

Browse files
gvanrossumddfisher
gvanrossum
authored and
ddfisher
committed
Document @flagfile and the format for mypy.ini. (#2161)
See #2148.
1 parent 2fbb724 commit 7b710ad

File tree

2 files changed

+178
-11
lines changed

2 files changed

+178
-11
lines changed

‎docs/source/command_line.rst

Lines changed: 46 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -9,17 +9,21 @@ flag (or its long form ``--help``)::
99

1010
$ mypy -h
1111
usage: mypy [-h] [-v] [-V] [--python-version x.y] [--platform PLATFORM]
12-
[--py2] [-s] [--silent] [--almost-silent]
13-
[--disallow-untyped-calls] [--disallow-untyped-defs]
14-
[--check-untyped-defs] [--disallow-subclassing-any]
15-
[--warn-incomplete-stub] [--warn-redundant-casts]
16-
[--warn-unused-ignores] [--fast-parser] [-i] [--cache-dir DIR]
17-
[--strict-optional] [-f] [--pdb] [--use-python-path] [--stats]
18-
[--inferstats] [--custom-typing MODULE] [--html-report DIR]
19-
[--old-html-report DIR] [--xslt-html-report DIR]
20-
[--xml-report DIR] [--txt-report DIR] [--xslt-txt-report DIR]
21-
[--linecount-report DIR] [-m MODULE] [-c PROGRAM_TEXT]
22-
[-p PACKAGE]
12+
[-2] [-s] [--almost-silent] [--disallow-untyped-calls]
13+
[--disallow-untyped-defs] [--check-untyped-defs]
14+
[--disallow-subclassing-any] [--warn-incomplete-stub]
15+
[--warn-redundant-casts] [--warn-unused-ignores]
16+
[--suppress-error-context] [--fast-parser] [-i]
17+
[--cache-dir DIR] [--strict-optional]
18+
[--strict-optional-whitelist [GLOB [GLOB ...]]] [--pdb]
19+
[--show-traceback] [--stats] [--inferstats]
20+
[--custom-typing MODULE] [--scripts-are-modules]
21+
[--config-file CONFIG_FILE] [--linecount-report DIR]
22+
[--linecoverage-report DIR] [--old-html-report DIR]
23+
[--memory-xml-report DIR] [--xml-report DIR]
24+
[--xslt-html-report DIR] [--xslt-txt-report DIR]
25+
[--html-report DIR] [--txt-report DIR] [-m MODULE]
26+
[-c PROGRAM_TEXT] [-p PACKAGE]
2327
[files [files ...]]
2428
(etc., too long to show everything here)
2529

@@ -99,6 +103,25 @@ example::
99103
will type check that little program (and complain that ``List[int]``
100104
is not callable).
101105

106+
Reading a list of files from a file
107+
***********************************
108+
109+
Finally, any command-line argument starting with ``@`` reads additional
110+
command-line arguments from the file following the ``@`` character.
111+
This is primarily useful if you have a file containing a list of files
112+
that you want to be type-checked: instead of using shell syntax like::
113+
114+
mypy $(cat file_of_files)
115+
116+
you can use this instead::
117+
118+
mypy @file_of_files
119+
120+
Such a file can also contain other flags, but a preferred way of
121+
reading flags (not files) from a file is to use a
122+
:ref:`configuration file <config-file>`.
123+
124+
102125
How imports are found
103126
*********************
104127

@@ -146,6 +169,8 @@ NOTE: These rules are relevant to the following section too:
146169
the ``-s`` flag described below is applied _after_ the above algorithm
147170
has determined which package, stub or module to use.
148171

172+
.. _silent-imports:
173+
149174
Following imports or not?
150175
*************************
151176

@@ -209,6 +234,8 @@ probably contains a subtle misspelling of the super method; however if
209234
``Any``, and mypy will assume there may in fact be a ``finnagle()``
210235
method, so it won't flag the error.
211236

237+
.. _almost-silent:
238+
212239
For an effect similar to ``-s`` that's a little less silent you can
213240
use ``--almost-silent``. This uses the same rules for deciding
214241
whether to check an imported module as ``-s``, but it will issue
@@ -278,6 +305,14 @@ Here are some more useful flags:
278305
run under the the given operating system. Without this option, mypy will
279306
default to using whatever operating system you are currently using. See
280307
:ref:`version_and_platform_checks` for more about this feature.
308+
309+
.. _config-file-flag:
310+
311+
- ``--config-file CONFIG_FILE`` causes configuration settings to be
312+
read from the given file. By default settings are read from ``mypy.ini``
313+
in the current directory. Settings override mypy's built-in defaults
314+
and command line flags can override settings. See :ref:`config-file`
315+
for the syntax of configuration files.
281316

282317
For the remaining flags you can read the full ``mypy -h`` output.
283318

‎docs/source/config_file.rst

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
.. _config-file:
2+
3+
The mypy configuration file
4+
===========================
5+
6+
Mypy supports reading configuration settings from a file. By default
7+
it uses the file ``mypy.ini`` in the current directory; the
8+
``--config-file`` command-line flag can be used to read a different
9+
file instead (see :ref:`--config-file <config-file-flag>`).
10+
11+
Most flags correspond closely to :ref:`command-line flags
12+
<command-line>` but there are some differences in flag names and some
13+
flags may take a different value based on the file being processed.
14+
15+
The configuration file format is the usual
16+
`ini file <https://docs.python.org/3.6/library/configparser.html>`_
17+
format. It should contain section names in square brackets and flag
18+
settings of the form `NAME = VALUE`. Comments start with ``#``
19+
characters.
20+
21+
- A section named ``[mypy]`` must be present. This specifies
22+
the global flags.
23+
24+
- Additional sections named ``[mypy-PATTERN1,PATTERN2,...]`` may be
25+
present, where ``PATTERN1``, ``PATTERN2`` etc. are `filename
26+
patterns <https://docs.python.org/3.6/library/fnmatch.html>`_
27+
separated by commas. These sections specify additional flags that
28+
only apply to files whose name matches at least one of the patterns.
29+
30+
Global flags
31+
************
32+
33+
The following global flags may only be set in the global section
34+
(``[mypy]``).
35+
36+
- ``python_version`` (string) specifies the Python version used to
37+
parse and check the target program. The format is ``DIGIT.DIGIT``
38+
for example ``2.7``. The default is the version of the Python
39+
interpreter used to run mypy.
40+
41+
- ``platform`` (string) specifies the OS platform for the target
42+
program, for example ``darwin`` or ``win32`` (meaning OS X or
43+
Windows, respectively). The default is the current platform as
44+
revealed by Python's ``sys.platform`` variable.
45+
46+
- ``custom_typing_module`` (string) specifies the name of an
47+
alternative module which is to be considered equivalent to the
48+
``typing`` module.
49+
50+
- ``warn_incomplete_stub`` (Boolean, default False) warns for missing
51+
type annotation in typeshed. This is only relevant in combination
52+
with ``check_untyped_defs``.
53+
54+
- ``warn_redundant_casts`` (Boolean, default False) warns about
55+
casting an expression to its inferred type.
56+
57+
- ``warn_unused_ignores`` (Boolean, default False) warns about
58+
unneeded ``# type: ignore`` comments.
59+
60+
- ``strict_optional`` (Boolean, default False) enables experimental
61+
strict Optional checks.
62+
63+
- ``scripts_are_modules`` (Boolean, default False) makes script ``x``
64+
become module ``x`` instead of ``__main__``. This is useful when
65+
checking multiple scripts in a single run.
66+
67+
- ``verbosity`` (integer, default 0) controls how much debug output
68+
will be generated. Higher numbers are more verbose.
69+
70+
- ``pdb`` (Boolean, default False) invokes pdb on fatal error.
71+
72+
- ``show_traceback`` (Boolean, default False) shows traceback on fatal
73+
error.
74+
75+
- ``dump_type_stats`` (Boolean, default False) dumps stats about type
76+
definitions.
77+
78+
- ``dump_inference_stats`` (Boolean, default False) dumps stats about
79+
type inference.
80+
81+
- ``fast_parser`` (Boolean, default False) enables the experimental
82+
fast parser.
83+
84+
- ``incremental`` (Boolean, default False) enables the experimental
85+
module cache.
86+
87+
- ``cache_dir`` (string, default ``.mypy_cache``) stores module cache
88+
info in the given folder in incremental mode.
89+
90+
- ``suppress_error_context`` (Boolean, default False) suppresses
91+
context notes before errors.
92+
93+
94+
Per-file flags
95+
**************
96+
97+
The following flags may vary per file. They may also be specified in
98+
the global section; the global section provides defaults which are
99+
overridden by the pattern sections matching the file.
100+
101+
.. note::
102+
103+
If multiple pattern sections match a file they are processed in
104+
unspecified order.
105+
106+
- ``silent_imports`` (Boolean, default False) silences complaints
107+
about :ref:`imports not found <silent-imports>`.
108+
109+
- ``almost_silent`` (Boolean, default False) is similar but
110+
:ref:`slightly less silent <almost-silent>`.
111+
112+
- ``disallow_untyped_calls`` (Boolean, default False) disallows
113+
calling functions without type annotations from functions with type
114+
annotations.
115+
116+
- ``disallow_untyped_defs`` (Boolean, default False) disallows
117+
defining functions without type annotations or with incomplete type
118+
annotations.
119+
120+
- ``check_untyped_defs`` (Boolean, default False) type-checks the
121+
interior of functions without type annotations.
122+
123+
- ``debug_cache`` (Boolean, default False) writes the incremental
124+
cache JSON files using a more readable, but slower format.
125+
126+
- ``show_none_errors`` (Boolean, default True) shows errors related
127+
to strict ``None`` checking, if the global ``strict_optional`` flag
128+
is enabled.
129+
130+
.. note::
131+
132+
Configuration flags are liable to change between releases.

0 commit comments

Comments
 (0)