Add basic support for user-defined mypy plugins #3517

JukkaL · 2017-06-09T15:10:21Z

Configure them through plugins=path/plugin.py, ... in the ini file.
The paths are relative to the configuration file.

This is an almost minimal implementation and some features
are missing:

Plugins installed through pip aren't properly supported.
Plugins within packages aren't properly supported.
Incremental mode doesn't invalidate cache files when
plugins change.

@chadrik We've been working on the same issue. This seems fairly
similar to your #3512. Not sure what's the best way forward.

Here are some thoughts about the design of this PR:

To configure a plugin, a user only needs to remember the name
(or currently path) of the plugin. Every plugin has a single,
fixed entry point plugin(mypy_version). The idea is to make
configuring plugins as easy as possible, as this is the main
explicit user interface to the plugin system.
Since the entry point takes mypy version as an argument, it
should be possible to write plugins that are compatible across
multiple mypy versions even if the internal API changes. This
won't be particularly convenient, though.
If there is an exception raised during plugin initialization, we just
display a normal Python stack trace (along with a note about what
was going on). Plugin errors aren't really mypy internal errors but
programmer errors (in this case of the plugin developer) so
I want to make them very visible.

Configure them through "plugins=path/plugin.py, ..." in the ini file. The paths are relative to the configuration file. This is an almost minimal implementation and some features are missing: * Plugins installed through pip aren't properly supported. * Plugins within packages aren't properly supported. * Incremental mode doesn't invalidate cache files when plugins change.

Previously we sometimes normalized to Windows paths and sometimes to Linux paths. Now switching to always use Linux paths.

chadrik · 2017-06-09T16:11:26Z

mypy/plugin.py

+    def get_method_hook(self, fullname: str) -> Optional[MethodHook]:
+        return self._find_hook(lambda plugin: plugin.get_method_hook(fullname))
+
+    def _find_hook(self, lookup: Callable[[Plugin], T]) -> Optional[T]:


The result of this should probably be cached based on hook-type and fullname.

Created an issue about caching (#3533). This may need some analysis or experimentation to decide a caching strategy (e.g. unlimited cache size vs bounded cache size; maximum size of the cache) so I feel that it's better to do it separately.

chadrik · 2017-06-09T16:12:16Z

mypy/test/testgraph.py

@@ -42,6 +43,7 @@ def _make_manager(self) -> BuildManager:
            reports=Reports('', {}),
            options=Options(),
            version_id=__version__,
+            plugin=Plugin((3, 6)),


should this use defaults.PYTHON3_VERSION?

chadrik · 2017-06-09T16:45:10Z

Looks really similar to what I have except it includes tests, so you win!

There are two other functional differences that I want to discuss:

Support for plugin options

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).

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'

Support for module plugins

You already mentioned this omission, but it should be fairly trivial to detect a plugin specifier that is path-like (re.search(r'[/\\]|([.]py$)', x)) and use that as a switch to support both behaviors. What do you think?

gvanrossum · 2017-06-10T01:33:50Z

Regarding plugin options, I recall the options to pytest plugins driving me mad, because they appear to be pytest options but aren't in the pytest docs (and the usage message goes on and on and on...).

A more minimal alternative would be to just have different names for the plugin, one for each variation.

miedzinski · 2017-06-10T20:53:03Z

@chadrik
Since mypy can configure itself from setup.cfg and we definitely don't want any naming conflicts, I think all plugin option sections should be somehow marked as mypy-specific (i.e. prefixed with mypy: or mypy-plugin:).

chadrik · 2017-06-10T22:16:23Z

@miedzinski good point. I updated my examples above to include proper namespaces.

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 · 2017-06-13T15:42:45Z

@chadrik I agree that specifying options for plugins would be useful. They can be implemented in a separate PR -- it would also be good to first discuss the best way to provide them (outside this PR). Support for referring to plugins through a module name can also be added with another PR. I usually prefer keeping PRs small to make them easy to review and to keep discussions focused. Feel free to create issues for the new features.

chadrik · 2017-06-13T16:11:57Z

@JukkaL that's fine as long as you don't do a release between this PR and the next, since the signature to the plugin registration function will change (it will grow a new options argument) and the layout of mypy.ini file might change. I'll get a PR for that made soon.

This PR looks good to me.

chadrik · 2017-06-13T16:12:58Z

Actually, I forgot I had two review notes above. What do you think about caching the lookup on the ChainedPlugin?

JukkaL · 2017-06-13T16:43:20Z

I created #3533 about caching.

gvanrossum · 2017-06-13T17:39:35Z