@@ -4,8 +4,8 @@ The mypy configuration file
4
4
===========================
5
5
6
6
Mypy supports reading configuration settings from a file. By default
7
- it uses the file ``mypy.ini `` with a fallback to ``.mypy.ini ``, then ``setup.cfg `` in
8
- the current directory, then ``$XDG_CONFIG_HOME/mypy/config ``, then
7
+ it uses the file ``mypy.ini `` with a fallback to ``.mypy.ini ``, then ``pyproject.toml ``,
8
+ then `` setup.cfg `` in the current directory, then ``$XDG_CONFIG_HOME/mypy/config ``, then
9
9
``~/.config/mypy/config ``, and finally ``.mypy.ini `` in the user home directory
10
10
if none of them are found; the :option: `--config-file <mypy --config-file> ` command-line flag can be used
11
11
to read a different file instead (see :ref: `config-file-flag `).
@@ -885,5 +885,84 @@ These options may only be set in the global section (``[mypy]``).
885
885
886
886
Controls how much debug output will be generated. Higher numbers are more verbose.
887
887
888
+
889
+ Using a pyproject.toml file
890
+ ***************************
891
+
892
+ Instead of using a ``mypy.ini `` file, a ``pyproject.toml `` file (as specified by
893
+ `PEP 518 `_) may be used instead. A few notes on doing so:
894
+
895
+ * The ``[mypy] `` section should have ``tool. `` prepended to its name:
896
+
897
+ * I.e., ``[mypy] `` would become ``[tool.mypy] ``
898
+
899
+ * The module specific sections should be moved into ``[[tool.mypy.overrides]] `` sections:
900
+
901
+ * For example, ``[mypy-packagename] `` would become:
902
+
903
+ .. code-block :: toml
904
+
905
+ [[tool.mypy.overrides]]
906
+ module = 'packagename'
907
+ ...
908
+
909
+ * Multi-module specific sections can be moved into a single ``[[tools.mypy.overrides]] `` section with a
910
+ module property set to an array of modules:
911
+
912
+ * For example, ``[mypy-packagename,packagename2] `` would become:
913
+
914
+ .. code-block :: toml
915
+
916
+ [[tool.mypy.overrides]]
917
+ module = [
918
+ 'packagename',
919
+ 'packagename2'
920
+ ]
921
+ ...
922
+
923
+ * The following care should be given to values in the ``pyproject.toml `` files as compared to ``ini `` files:
924
+
925
+ * Strings must be wrapped in double quotes, or single quotes if the string contains special characters
926
+
927
+ * Boolean values should be all lower case
928
+
929
+ Please see the `TOML Documentation `_ for more details and information on
930
+ what is allowed in a ``toml `` file. See `PEP 518 `_ for more information on the layout
931
+ and structure of the ``pyproject.toml `` file.
932
+
933
+ Example ``pyproject.toml ``
934
+ **************************
935
+
936
+ Here is an example of a ``pyproject.toml `` file. To use this config file, place it at the root
937
+ of your repo (or append it to the end of an existing ``pyproject.toml `` file) and run mypy.
938
+
939
+ .. code-block :: toml
940
+
941
+ # mypy global options:
942
+
943
+ [tool.mypy]
944
+ python_version = "2.7"
945
+ warn_return_any = true
946
+ warn_unused_configs = true
947
+
948
+ # mypy per-module options:
949
+
950
+ [[tool.mypy.overrides]]
951
+ module = "mycode.foo.*"
952
+ disallow_untyped_defs = true
953
+
954
+ [[tool.mypy.overrides]]
955
+ module = "mycode.bar"
956
+ warn_return_any = false
957
+
958
+ [[tool.mypy.overrides]]
959
+ module = [
960
+ "somelibrary",
961
+ "some_other_library"
962
+ ]
963
+ ignore_missing_imports = true
964
+
888
965
.. _lxml : https://pypi.org/project/lxml/
889
966
.. _SQLite : https://www.sqlite.org/
967
+ .. _PEP 518 : https://www.python.org/dev/peps/pep-0518/
968
+ .. _TOML Documentation : https://toml.io/
0 commit comments