Document .env files and pytest-cov caveat

#1483
#1489

Author: Kraig Brockschmidt

docs/python/debugging.md

@@ -4,7 +4,7 @@ Area: python
 TOCTitle: Debugging
 ContentId: 3d9e6bcf-eae8-4c94-b857-89225b5c4ab5
 PageTitle: Debugging Python with Visual Studio Code
-DateApproved: 02/12/2018
+DateApproved: 03/14/2018
 MetaDescription: Debugging Python with Visual Studio Code
 MetaSocialImage: images/tutorial/social.png
 ---
@@ -115,7 +115,7 @@ Sets optional environment variables for the debugger process beyond system envir
 
 ### `envFile`
 
-Optional path to a file that contains environment variable definitions.
+Optional path to a file that contains environment variable definitions. See [Configuring Python environments - environment variable definitions file](environments.md#environment-variable-definitions-file).
 
 ## Debugging specific app types
 

docs/python/environments.md

@@ -4,7 +4,7 @@ Area: python
 TOCTitle: Environments
 ContentId: 8fe4ca8b-fc70-4216-86c7-2c11b6c14cc6
 PageTitle: Configuring Python Environments in Visual Studio Code
-DateApproved: 02/14/2018
+DateApproved: 03/14/2018
 MetaDescription: Configuring Python Environments in Visual Studio Code
 MetaSocialImage: images/tutorial/social.png
 ---
@@ -22,6 +22,8 @@ You can also [manually specify an interpreter](#manually-specifying-an-interpret
 
 > **Tip:** If you create a new conda environment while VS Code is running, use the **Reload Window** command to refresh the environment list.
 
+The extension also loads an [environment variable definitions file](#environment-variable-definitions-file) identified by the `python.envFile` setting. The default value of this setting is `${workspaceFolder}/.env`.
+
 ## Choosing an environment
 
 By default, the Python extension relies on the first Python interpreter it finds in the path, but it's easy to switch between environments.
@@ -125,6 +127,46 @@ To use a Python interpreter that's installed in a virtual environment:
 2. Configure the same `python.pythonPath` variable in `launch.json`.
 3. Ensure that the the libraries and modules you plan on using for linting are installed within the virtual environment.
 
+## Environment variable definitions file
+
+An environment variable definitions file is a simple text file containing key-value pairs in the form of `environment_variable=value`, with `#` used to mark comments. Multi-line values are not supported.
+
+By default, the Python extension loads a file named `.env` in the current workspace folder, as identified by the default value of the `python.envFile` setting (see [General settings](settings-reference.md#general-settings). You can change the `python.envFile` setting at any time to use a different definitions file.
+
+A debug configuration also contains an `envFile` property that also defaults to the `.env` file in the current workspace. (See [Debugging - standard configuration and options](debugging.md#standard-configuration-and-options). This property allows you to easily set variables for debugging purposes that replace those used in the default `.env` file.
+
+For example, when developing a web application you might want to easily switch between development and production servers. Instead of coding the different URLs and other settings into your application directly, you could use separate definitions files for each. For example:
+
+**dev.env file**
+
+```text
+# dev.env - development configuration
+
+# API endpoint
+MYPROJECT_APIENDPOINT=https://my.domain.com/api/dev/
+
+# Variables for the database
+MYPROJECT_DBURL=https://my.domain.com/db/dev
+MYPROJECT_DBUSER=devadmin
+MYPROJECT_DBPASSWORD=!dfka**213=
+```
+
+**prod.env file**
+
+```text
+# prod.env - production configuration
+
+# API endpoint
+MYPROJECT_APIENDPOINT=https://my.domain.com/api/
+
+# Variables for the database
+MYPROJECT_DBURL=https://my.domain.com/db/
+MYPROJECT_DBUSER=coreuser
+MYPROJECT_DBPASSWORD=kKKfa98*11@
+```
+
+You can then set the `python.envFile` setting to `${workspaceFolder}/prod.env`, then set the `envFile` property in the debug configuration to `${workspaceFolder}/dev.env`.
+
 ## Python interpreter for debugging
 
 By default, the debugger uses the same `python.pythonPath` setting as for other features of VS Code. Specifically, the value for `pythonPath` in the debugger settings simply refers to the main interpreter setting as follows:

docs/python/settings-reference.md

@@ -4,7 +4,7 @@ Area: python
 TOCTitle: Settings Reference
 ContentId: d256dc5c-95e9-4c02-a82f-947bf34a3517
 PageTitle: Settings Reference for Python
-DateApproved: 12/12/2017
+DateApproved: 03/14/2018
 MetaDescription: Settings Reference for the Python extension in Visual Studio Code
 MetaSocialImage: images/tutorial/social.png
 ---
@@ -20,7 +20,7 @@ Refer to [User and workspace settings](/docs/getstarted/settings.md) to find our
 | --- | --- | --- |
 | python.pythonPath | `"python"` | Path to the python interpreter. |
 | python.venvPath | `""` | Path to folder with a list of Virtual Environments, such as `~/.pyenv`, `~/Envs`, `~/.virtualenvs`. |
-| python.envFile | `"${workspaceFolder}/.env"` | Absolute path to a file containing environment variable definitions. |
+| python.envFile | `"${workspaceFolder}/.env"` | Absolute path to a file containing environment variable definitions. See [Configuring Python environments - environment variable definitions file](environments.md#environment-variable-definitions-file). |
 | python.terminal.launchArgs | `[]` | Launch arguments given the Python interpreter when running a file. |
 | python.terminal.executeInFileDir | `false` | Indicates whether to run a file in the file's directory instead of the current folder. |
 | python.terminal.activateEnvironments | `true` | Indicates whether a selected virtual or conda environments is activated when using the **Python: Create Terminal** command or any other operation involving the terminal, such as the **Send Python File to Terminal** menu command. If `false`, skips activating virtual and conda environments before running the commands. |
@@ -162,7 +162,7 @@ Workspace symbols are symbols in C source code generated by the ctags tool (desc
 | --- | --- | --- | --- |
 | pyTestEnabled | `false` | Specifies whether pytest is enabled for unit testing. | [Unit testing](/docs/python/unit-testing.md) |
 | pyTestPath | `"py.test"` | Path to pytest. Use a full path if pytest is located outside the current environment. | [Unit testing](/docs/python/unit-testing.md) |
-| pyTestArgs | `[]` | Arguments to pass to PyTest, with each argument specified as an item in the array. | [Unit testing](/docs/python/unit-testing.md) |
+| pyTestArgs | `[]` | Arguments to pass to PyTest, with each argument specified as an item in the array. When debugging unit tests with pytest-cov installed, include `--no-cov` in these arguments. | [Unit testing](/docs/python/unit-testing.md) |
 
 ### Nose framework
 

docs/python/unit-testing.md

@@ -4,7 +4,7 @@ Area: python
 TOCTitle: Unit Testing
 ContentId: 9480bef3-4dfc-4671-a454-b9252567bc60
 PageTitle: Unit Testing Python in Visual Studio Code
-DateApproved: 11/10/2017
+DateApproved: 03/14/2018
 MetaDescription: Unit Testing Python in Visual Studio Code
 MetaSocialImage: images/tutorial/social.png
 ---
@@ -62,6 +62,9 @@ See [unittest command-line interface](https://docs.python.org/3/library/unittest
 
 You can also configure pytest using a `pytest.ini` file as described on [PyTest Configuration](https://docs.pytest.org/en/latest/customize.html).
 
+> **Note**
+> If you have the pytest-cov coverage module installed, VS Code doesn't stop at breakpoints while debugging because pytest-cov is using the same technique to access the code being run. To prevent this behavior, include `--no-cov` in `pyTestArgs` when debugging tests. (For more information, see [Debuggers and PyCharm](http://pytest-cov.readthedocs.io/en/latest/debuggers.html) in the pytest-cov documentation.)
+
 ### Nose configuration settings
 
 | Setting<br/>(python.unitTest.) | Default | Description |