Add type hint annotations for user-facing code

[namurphy]

For the developers of packages that make use of wrapt, it would be helpful for user-facing objects to have type hint annotations.

As an example use case, I'm adding static type checking with mypy to the continuous integration suite of a package. This particular package uses wrapt in a decorator that we use frequently throughout the package. Because mypy follows dependencies, it was unable to fully type check our usage of @wrapt.decorator. We added a rudimentary type stub file in https://github.com/PlasmaPy/PlasmaPy/pull/2442 to get around this limitation. It would be helpful to have the type hints in @wrapt.decorator itself, as well as other widely used code.

The mypy documentation has a section on annotating decorators.

Thank you for creating a wonderful package!

[namurphy]

I just saw that there is a PR in progress (#225) which would add a .pyi file for @wrapt.decorator. Since wrapt now appears to be Python 3.6+, an alternative would be to add the type hint annotations directly to the .py file itself in the signature line of @wrapt.decorator.

[dimaqq]

Yes, please :)