Better documentation about .env file

[anthonykim1]

#23280 (comment)
and
#23856

We should have better documentation regarding .env file.

[benglewis]

Honestly, I hate to be a hater and complain, but the Python: Env File option should be off-by-default, at the very least until it is "fixed". What do I mean?

1. The implementation appeared out of nowhere one day (both myself and another developer on my team had our setup broken one day because of it, and it took me getting mad and searching all of my system packages, shell plugins and configuration and then VSCode extensions one-by-one until I realized that it was vscode-python)
2. The implementation is not consistent with the python-dotenv package that users are used to using out there in multiple ways:

• It doesn't handle comments properly
• It doesn't handle multi-line values

3. When the implementation is inconsistent, it can break developers' workflows since it sets a value on the environment variable which will then not be overridden.
4. Users that use .env files have enough other alternative options that they do not need this from this extension.

[anthonykim1]

Thanks for the feedback there @benglewis
Would you find https://code.visualstudio.com/docs/python/environments#_environment-variables to be helpful at all? Curious to hear what you think. -Thanks

[benglewis]

Maybe, for situations where it is not viable to change/edit code to introduce python-dotenv

[shughes-uk]

This feature cost me hours. We have an app that uses python-dotenv to load settings from a .env file. I wanted to change a setting, so just updated my env file. Normally executing the app should immediately reflect these changes, but now it was using the old value as python-dotenv gives priority to environment variables over the file.

So spend forever trying to track down where the hell the old value was coming from. Eventually fastapi/fastapi#4251 led me to #23280 (comment) .

Especially annoying as when I tried to use the vscode debugger to figure it out, of course the issue did not exist (as it was reloading the .env file each launch).

The other issues are closed, but I would beg you to reconsider having this on by default without any indication it happens unless you read the entire extension documentation. At least add a little "loaded .env variables" or something at the start of a terminal boot as a hint!

[benglewis]

Just to clarify @anthonykim1 , my feedback suggesting that it might be useful was regarding allowing a user to actively choose to turn it on and "opt-in". It should 100% definitely not be the default. Additionally, a notification when opening a shell that the .env was loaded into environment variables with a link to the setting, would probably help people that are stuck after having enabled it by mistake

[legau]

To add to this, in non-Python projects, activating one time a Python interpreter causes all subsequent terminal sessions to load these old state values with no way (to my knowledge) to remove them except uninstalling the extension. In a non-python project the interpreter will almost never come up automatically to refresh the values except by hand.
This is absolutely unexpected behavior even with comprehensive documentation available.
There are a lot of issues about this and everyone states the long time it has taken them to debug such weird behavior.

[mkp-bangemann]

My current workaround is disabling the Python extension for non-Python projects in that workspace. Prior to finding the cause, I just used an external terminal as a workaround. But it definitely caused a few headaches every now and then trying to find the issue.