Make Env methods self-documenting

[tomgrin10]

I would like to preface this issue by saying that I really love this library, and use it a lot in my projects 😀

I personally see great importance in self-documenting code, and a large part of self-documenting code is being able to view a function's arguments and their types in an IDE when using an API, without looking at its docs. As this library has no official API reference (which is totally fine!), I think its crucial that the function signatures are clear to the user.

I see 2 choices for achieving this:

1. Adding a .pyi file. (this means that every change to Env's API means a change in the .pyi file too)
2. Rewrite Env's methods so that they have a clear signature that IDEs can parse.

I personally think the 1st option is easier, but wanted to know your opinion before submitting a PR.

[sloria]

I would like to preface this issue by saying that I really love this library, and use it a lot in my projects 😀

Thanks for the kind words

a large part of self-documenting code is being able to view a function's arguments and their types in an IDE when using an API, without looking at its docs. As this library has no official API reference (which is totally fine!), I think its crucial that the function signatures are clear to the user.

I suppose I opted to prioritize conciseness and ease of maintenance over static analyzability and self-documentation (related issue: https://github.com/sloria/environs/issues/120). That said, I'd be willing to budge if your proposal can be done without too much maintenance overhead. So feel free to send a PR. A rough proof of concept should suffice.

[hukkin]

Hey, chipping in since I did quite a lot of research on this in https://github.com/sloria/environs/issues/120 :smiley:

I personally think the 1st option is easier...

Getting the typings right might not be as easy as you initially think (without making any functional changes to the codebase). https://github.com/sloria/environs/issues/120 describes the problem points quite extensively. Neglecting the eager=False feature the annotations will be fairly complex (I made a package with reduced API, e.g. no eager=False, you can see the monstrous type annotations there :smile: ). Respecting the eager=False feature, it seems the equation is pretty much impossible for a type checker to solve.

Note that distributing inaccurate typings that neglect a certain use case is probably more annoying to users than typing everything as typing.Any.

[mfwarren]

starting with 9.0.0 mypy complains about this example:

from environs import Env
env = Env(eager=True)

ENV_VALUE = env('ENV_VALUE')
ENV_VALUE.startswith('string')

is there a suggestion for an elegant way to handle types in this case?

[hukkin]

@mfwarren I would say the type annotations need to be loosened here. I made a PR for you https://github.com/sloria/environs/pull/188

Meanwhile you can fix mypy complaining by adding assert isinstance(ENV_VALUE, str) immediately after reading the value. Or alternatively revert to a previous environs release.

[sloria]

Closing this for now as i don't think there's any immediate action to take. We can always reopen if people want to discuss further