Skip to content

Commit fdeedd6

Browse files
authored
Add support for pulling configuration from pyproject.toml files (#10219)
Closes #5205. This PR will add support to mypy for end users specifying configuration in a pyproject.toml file. I also updated the documentation to indicate that this support has been added, along with some guidelines on adapting the ini configurations to the toml format.
1 parent fbf6fe4 commit fdeedd6

19 files changed

+936
-30
lines changed

.gitignore

+3
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ mypyc/doc/_build
1010
*.iml
1111
/out/
1212
.venv*/
13+
venv/
1314
.mypy_cache/
1415
.incremental_checker_cache.json
1516
.cache
@@ -44,6 +45,8 @@ htmlcov
4445
bin/
4546
lib/
4647
include/
48+
.python-version
49+
pyvenv.cfg
4750

4851
.tox
4952
pip-wheel-metadata

docs/source/command_line.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -97,7 +97,7 @@ Config file
9797

9898
This flag makes mypy read configuration settings from the given file.
9999

100-
By default settings are read from ``mypy.ini``, ``.mypy.ini``, or ``setup.cfg``
100+
By default settings are read from ``mypy.ini``, ``.mypy.ini``, ``pyproject.toml``, or ``setup.cfg``
101101
in the current directory. Settings override mypy's built-in defaults and
102102
command line flags can override settings.
103103

docs/source/config_file.rst

+81-2
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,8 @@ The mypy configuration file
44
===========================
55

66
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
99
``~/.config/mypy/config``, and finally ``.mypy.ini`` in the user home directory
1010
if none of them are found; the :option:`--config-file <mypy --config-file>` command-line flag can be used
1111
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]``).
885885

886886
Controls how much debug output will be generated. Higher numbers are more verbose.
887887

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+
888965
.. _lxml: https://pypi.org/project/lxml/
889966
.. _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

Comments
 (0)