Add Typing stubs for the main API.

[pcorpet]

See PEP 484 (for typing) and PEP 561 (for distributing types).

---

This change is 

[avian2]

Hi.

Thanks for your pull request! Do you have a way of testing these stubs against the code? I looked into mypy, but it can't test stub files (#5028)?

I'm planning to drop Python 2 and 3.4 support soon, so I'll probably just move the annotations in-line then.

[pcorpet]

To answer your main question:

1. there is a tool called stubtest distributed with mypy that can check that the stubs match the implementation. However it would need to add stubs for all internal modules, and not only __init__.py. I could try to use it though with a stunt. I'll try something.

2. another way to test those stubs is to add dedicated example module to check. See for instance what I did here https://github.com/josephbestjames/airtable.py/tree/master/typetests

3.yet another way is to type one of your actual test (one that only test the external API), however this doesn't check that the stubs match the code exactly

[pcorpet]

My attempt for 1 didn't work (I thought about moving __init__.pyi to unidecode.pyi at the level above but stubtest isn't much happier).

Tell me if you want me to do solution 2 or 3.

[pcorpet]

Oh and thank you for taking on my request so quickly :-)

[avian2]

I did some tests and I think the "dedicated example module" approach doesn't test the Unidecide code against the stubs either. At least I couldn't get mypy to tell me about the errors in the stubs I mentioned earlier in my review. It does tell me about those if I put the type annotations inline.

Anyway, I think it's ok. I just merged this and I'll move the type annotations inline in the next release when I drop support for Python <3.5.

Thanks again for your contribution!