From 3dddc69865c1079edfde0a03d7e1f27dd43e1444 Mon Sep 17 00:00:00 2001 From: Kraig Brockschmidt Date: Wed, 14 Mar 2018 14:39:00 -0700 Subject: [PATCH] Document .env files and pytest-cov caveat https://github.com/Microsoft/vscode-docs/issues/1483 https://github.com/Microsoft/vscode-docs/issues/1489 --- docs/python/debugging.md | 4 +-- docs/python/environments.md | 44 ++++++++++++++++++++++++++++++- docs/python/settings-reference.md | 6 ++--- docs/python/unit-testing.md | 5 +++- 4 files changed, 52 insertions(+), 7 deletions(-) diff --git a/docs/python/debugging.md b/docs/python/debugging.md index 1baaa3602c..5042043be6 100644 --- a/docs/python/debugging.md +++ b/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 diff --git a/docs/python/environments.md b/docs/python/environments.md index 583eb64950..295990b18c 100644 --- a/docs/python/environments.md +++ b/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: diff --git a/docs/python/settings-reference.md b/docs/python/settings-reference.md index e8126e0cc0..be53e3ab15 100644 --- a/docs/python/settings-reference.md +++ b/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 diff --git a/docs/python/unit-testing.md b/docs/python/unit-testing.md index 2795a228d4..792bbbc81c 100644 --- a/docs/python/unit-testing.md +++ b/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
(python.unitTest.) | Default | Description |