In short: I'm asking for permission to write type annotations for python-dotenv and include in the centralized repository called typeshed. In this case, this PR is just for a reference and can be closed. There's another option that I refine the quality of this PR and we start typechecking python-dotenv itself.

I wrote type annotations for python-dotenv which will be useful for python-dotenv users who also use mypy to typecheck their apps.

I'd like to contribute this either:

• as an internal annotation in the library (as included in this PR) or
• as an external annotation in typeshed.

I do not intend to have this PR merged as-is, rather I've included the changes for reference. In the contribution guide of typeshed, it states:

If you want to submit type stubs for a new library, you need to contact the maintainers of the original library first to let them know and get their permission. Do it by opening an issue on their project's bug tracker. This gives them the opportunity to consider adopting type hints directly in their codebase (which you should prefer to external type stubs). When the project owners agree for you to submit stubs here or you do not receive a reply within one month, open a pull request referencing the issue where you asked for permission.

I was mainly interested in annotating public interfaces, so including this in typeshed is sufficient for me. I also annotated private interfaces but it may be unsatisfactory. However, there's still an option to include the type annotation in python-dotenv and use it for typechecking python-dotenv itself.

Quality of the current type annotation

• It passes mypy typecheck in 2.7, 3.5, 3.6, and 3.7 modes.
• There are some (non-behavioral) changes in the original code to workaround typechecking problems.
• I'm relatively more confident with completeness of public interfaces annotation, than private ones.
• Less annotation for IPython support and CLI.