Add support for per-plugin options

[chadrik]

Starting discussion from #3517 in a new issue.

Some plugins may want to expose user-configurable options. For example, with my docstring parser I want users to be able to specify which style of docstrings to expect (the default behavior of automatic discovery is a bit slower).

To accomplish this we define a convention for plugins to provide options within mypy.ini, and pass the parsed options as Dict[str, str] to the plugin() registration function, along with the mypy version. User plugins will need to do their own conversion of options from str to bool, int, float, etc.

Here are three proposals for how to link plugin registration with per-plugin configuration options:

---

Option A

The correlation here is bit fragile and the per-plugin section headers may be difficult to grok for longer (i.e. absolute) paths:

[mypy]
fast_parser = true
plugins = /path/to/typeddict.py, /path/to/mypydoc.py

[mypy.plugins-/path/to/mypydoc.py]
docstring_style = 'google'

---

Option B

The following is visually clean, but can't as easily piggy-back on the current options-parsing code. (Note: I believe that mypy-plugins with a dash would conflict with mypy's per-module configuration):

[mypy]
fast_parser = true

[mypy.plugins]
typeddict = /path/to/typeddict.py
mypydoc = /path/to/mypydoc.py

[mypy.plugins-mypydoc]
docstring_style = 'google'

---

Option C

The following dotted registration style is used heavily by mercurial, and this is what I decided on in my implementation. It piggy-backs existing options parsing code, so it could easily be extended to per-module options in the future, if we found a need for that:

[mypy]
fast_parser = true
plugins.typeddict = /path/to/typeddict.py
plugins.mypydoc = /path/to/mypydoc.py

[mypy.plugins-mypydoc]
docstring_style = 'google'

---

I tried to come up with some logic for the separators:

• periods join known mypy sections: e.g. [mypy], [mypy.plugins]
• dashes join sections with dynamic topics: e.g. [mypy.plugins-custom.plugin], [mypy-custom.module]

I'm completely open to other suggestions. Underscore could work in place of periods, but I found it less visually appealing.

[JukkaL]

Another potential configuration option might be the location of Django models, for a Django plugin.

Here's another idea:

[mypy]
plugins = path/mypydjango.py, mypydoc, mypyext.plugin

[mypy.plugin-mypydjango]
model_locations = myapp.model

[mypy.plugin-mypydoc]
docstring_style = 'google'

[mypy.plugin-mypyext.plugin]
option = value

The name of the plugin would be automatically inferred from the module name of the plugin.

Rationale:

• No need to write the path multiple times.
• No need to invent a name for a plugin -- it's always derived from the plugin path / module name. This makes it easier to copy-paste plugin options from elsewhere and generally reduces the number of variables.

[chadrik]

I'm a little concerned that this could result in duplicate names for plugins identified by paths, of this sort:

[mypy]
plugins = /path/to/projectA/plugin.py, /path/to/projectB/plugin.py

Perhaps we can do a right-anchored (depth-first) match by directory. e.g.:

[mypy.plugin-projectA/plugin.py]
; matches /path/to/projectA/plugin.py
foo = bar

[mypy.plugin-plugin.py]
; warning: matches more than one entry. using first match: /path/to/projectA/plugin.py
foo = bar

Once we support importing modules on the PYTHONPATH this will become less of an issue.