Document how to write aliases that are recognized by mypy

[hynek]

This fIxEs #630 as far as we can fix it. I would love to add a more concrete example (a minimal example that people can just drop in and that explains how to drop in) but I guess I'll leave that as a contribution opportunity to someone else since I don't have the bandwidth for that ATM.

[euresti]

Just some nits and a question.

Thanks for doing this.

[Tinche]

I actually had issues getting mypy to recognize my wrappers. I think the package implementing the wrappers needs to contain a py.typed marker file.

[euresti]

Also, what would make us not hold our nose? I have a couple of ideas:

1. Add a new decorator that does nothing but it lets mypy know that this method overrides an attrs method. Something like:

@class_maker(auto_attribs_default=True)
def my_class_maker(...):
   ...

This looks great but is probably pretty hard in mypy. Also how many defaults do we allow to set. We'd want to iterate on the API.

2. Add a method that lets us not feel like it's not modifying a global. e.g.

from mypy.plugins.attrs import register_extra_makers

class MyPlugin(Plugin):
    def __init__(self, options: Options) -> None:
        register_extra_makers(dataclass=..., attrs=..., attrib=...)
        super().__init__(options)        

def plugin(version):
    return MyPlugin

3. Maybe there's a way to do this in mypy.ini? But this is not something I've investigated. The mypy team might have special rules for what's allowed in the mypy.ini file.

[hynek]

Also, what would make us not hold our nose? I have a couple of ideas:

This seems worth a news ticket I think!

I like both but someone intimate with mypy has to investigate what you wrote. :|

[hynek]

I have just used the information involved: https://gist.github.com/hynek/1e3844d0c99e479e716169034b5fa963#file-attrs_ng_plugin-py

Thanks again!