From 2f2eed79bc74ce5ed9048c023a9c10209eae7443 Mon Sep 17 00:00:00 2001 From: Kraig Brockschmidt Date: Tue, 29 Jan 2019 11:17:01 -0800 Subject: [PATCH] Acrolinx tweaks --- docs/languages/python.md | 2 +- docs/python/debugging.md | 16 +++++------ docs/python/editing.md | 4 +-- docs/python/environments.md | 12 ++++---- docs/python/jupyter-support.md | 2 +- docs/python/linting.md | 8 +++--- docs/python/python-tutorial.md | 16 +++++------ docs/python/settings-reference.md | 14 +++++----- .../tutorial-deploy-app-service-on-linux.md | 16 +++++------ docs/python/tutorial-deploy-containers.md | 16 +++++------ docs/python/tutorial-django.md | 28 +++++++++---------- docs/python/tutorial-flask.md | 22 +++++++-------- docs/python/unit-testing.md | 4 +-- 13 files changed, 80 insertions(+), 80 deletions(-) diff --git a/docs/languages/python.md b/docs/languages/python.md index 06ee0c0c00..06da852c8a 100644 --- a/docs/languages/python.md +++ b/docs/languages/python.md @@ -60,7 +60,7 @@ The Python extension can apply a number of different linters including Pylint, P ## Debugging -No more `print` statement debugging! Set breakpoints, inspect data, and use the debug console as you run your program step by step. Debug a number of different type of Python applications, including multi-threaded, web, and remote applications. +No more `print` statement debugging! Set breakpoints, inspect data, and use the debug console as you run your program step by step. Debug a number of different types of Python applications, including multi-threaded, web, and remote applications. For Python-specific details, including setting up your `launch.json` configuration and remote debugging, see [Debugging](/docs/python/debugging.md). General VS Code debugging information is found in the [debugging document](/docs/editor/debugging.md). diff --git a/docs/python/debugging.md b/docs/python/debugging.md index 7a803ce2bb..6fa4b5da65 100644 --- a/docs/python/debugging.md +++ b/docs/python/debugging.md @@ -48,7 +48,7 @@ To select a debugging configuration, select the Debug View in the sidebar, then By default, VS Code shows only the most common configurations provided by the Python extension. You can select other configurations to include in `launch.json` by using the **Add Configuration** command shown in the list and in the `launch.json` editor. When you use the command, VS Code prompts you with a list of all available configurations (be sure to scroll down to see all the Python options): -![Adding a new Python debugging configurations](images/debugging/add-configuration.png) +![Adding a new Python debugging configuration](images/debugging/add-configuration.png) See [Debugging specific app types](#debugging-specific-app-types) for details on all of these configurations. @@ -180,7 +180,7 @@ As an example, say `${workspaceFolder}` contains a `py_code` folder containing ` ### `debugOptions` -An array of additional options that may contain the following: +An array of additional options: | Option | Description | | --- | --- | @@ -214,7 +214,7 @@ In your Python code, you can call `breakpoint()` at any point where you want to ## Attach to a local script -In some scenarios you need to debug a Python script that's invoked locally by another process. For example, you may be debugging a web server that runs different Python scripts for specific processing jobs. In such cases, you need to attach the VS Code debugger to the script once it's been launched: +In some scenarios, you need to debug a Python script that's invoked locally by another process. For example, you may be debugging a web server that runs different Python scripts for specific processing jobs. In such cases, you need to attach the VS Code debugger to the script once it's been launched: 1. Run VS Code, open the folder or workspace containing the script, and create a `launch.json` for that workspace if one doesn't exist already. @@ -248,11 +248,11 @@ Remote debugging allows you to step through a program locally within VS Code whi 1. Both computers: make sure that identical source code is available. -1. Both computers: install [ptvsd](https://pypi.org/project/ptvsd/) using `python -m pip install --upgrade ptvsd` into your environment (while using a form of virtual environment is not required, it is strongly recommended). +1. Both computers: install [ptvsd](https://pypi.org/project/ptvsd/) using `python -m pip install --upgrade ptvsd` into your environment (while using a form of virtual environment is not required, it is a recommended best practice). 1. Remote computer: open the port you wish to use for debugging in the appropriate firewall or other networking configuration. -1. Remote computer: there are two ways to specify how to attach to the remote process. Note that you may need to specify the remote computer's private IP address, if applicable (Linux VMs on Azure, for example, have both a public and private address). If you use the public IP address, you might see the error "Cannot assign requested address." +1. Remote computer: there are two ways to specify how to attach to the remote process. You may need to specify the remote computer's private IP address, if applicable (Linux VMs on Azure, for example, have both a public and private address). If you use the public IP address, you might see the error "Cannot assign requested address." 1. In the source code, add the following lines, replacing `address` with the remote computer's IP address and port number (IP address 1.2.3.4 is shown here for illustration only). @@ -312,7 +312,7 @@ Remote debugging allows you to step through a program locally within VS Code whi > **Tip**: setting a single breakpoint on the statement immediately following the `ptvsd.wait_for_attach()` line may not work. Set at least one other breakpoint on another statement. -1. Local computer: start the VS Code debugger using the modified **Python Attach** configuration. VS Code should stop on your locally-set breakpoints, allowing you to step through the code, examine variables, and perform all other debugging actions. Expressions that you enter in the **Debug Console** are run on the remote computer as well. +1. Local computer: start the VS Code debugger using the modified **Python Attach** configuration. VS Code should stop on your locally set breakpoints, allowing you to step through the code, examine variables, and perform all other debugging actions. Expressions that you enter in the **Debug Console** are run on the remote computer as well. Text output to stdout, as from `print` statements, appears on both computers. Other outputs, such as graphical plots from a package like matplotlib, however, appear only on the remote computer. @@ -324,7 +324,7 @@ Remote debugging allows you to step through a program locally within VS Code whi ### Debugging over SSH -In some cases you may want or need to use a secure connection to the remote computer when debugging. On Windows computers, you may need to install [OpenSSH](http://sshwindows.sourceforge.net/) to have the `ssh` command. +In some cases, you may want or need to use a secure connection to the remote computer when debugging. On Windows computers, you may need to install [OpenSSH](http://sshwindows.sourceforge.net/) to have the `ssh` command. On the remote computer: @@ -460,7 +460,7 @@ Google App Engine launches an app by itself, so launching it in the VS Code debu ``` 1. Create a `launch.json` configuration using the **Attach (Remote Debug)** configuration as a template. Make sure the port value matches what's in the source code above. 1. Add `"preLaunchTask": "python"` to `launch.json`. -1. From the Command Palette, run the **Run Build Task** command. This opens the Tasks output window where you see various messages. +1. From the Command Palette, run the **Run Build Task** command. This command opens the Tasks output window where you see various messages. 1. Once you see the message "Google App Engine has started; ready to attach the debugger," start the VS Code debugger using the remote debugging configuration. 1. Set breakpoints where you want, then start the browser to start the app. diff --git a/docs/python/editing.md b/docs/python/editing.md index 40fab7c385..7c0f3b42f8 100644 --- a/docs/python/editing.md +++ b/docs/python/editing.md @@ -4,7 +4,7 @@ Area: python TOCTitle: Editing Code ContentId: 0ccb0e35-c4b2-4001-91bf-79ff1618f601 PageTitle: Editing Python Code in Visual Studio Code -DateApproved: 01/03/2019 +DateApproved: 01/29/2019 MetaDescription: Editing Python in Visual Studio Code MetaSocialImage: images/tutorial/social.png --- @@ -77,7 +77,7 @@ The **Python: Run Selection/Line in Python Terminal** command (`kbstyle(Shift+En Source code that runs in the terminal/REPL is cumulative until the current instance of the terminal is closed. -The command opens the Python Terminal if necessary; you can also open the interactive REPL environment directly using the **Python: Start REPL** command. Note that initial startup might take a few moments especially if the first statement you run is an `import`. +The command opens the Python Terminal if necessary; you can also open the interactive REPL environment directly using the **Python: Start REPL** command. (Initial startup might take a few moments especially if the first statement you run is an `import`.) On first use of the **Python: Run Selection/Line in Python Terminal** command, VS Code may send the text to the REPL before that environment is ready, in which case the selection or line is not run. If you encounter this behavior, try the command again when the REPL has finished loading. diff --git a/docs/python/environments.md b/docs/python/environments.md index 9687c0b06e..8cf8613f3d 100644 --- a/docs/python/environments.md +++ b/docs/python/environments.md @@ -10,7 +10,7 @@ MetaSocialImage: images/tutorial/social.png --- # Using Python environments in VS Code -An "environment" in Python is the context in which a Python program runs. An environment consists of an interpreter and any number of installed packages. The Python extension for VS Code provide helpful integration features for working with different environments. +An "environment" in Python is the context in which a Python program runs. An environment consists of an interpreter and any number of installed packages. The Python extension for VS Code provides helpful integration features for working with different environments. > **Note**: If you're looking to get started with Python in Visual Studio Code, refer to the tutorial [Getting Started with Python in VS Code](/docs/python/python-tutorial.md). @@ -18,7 +18,7 @@ An "environment" in Python is the context in which a Python program runs. An env By default, the Python extension looks for and uses the first Python interpreter it finds in the system path. If it doesn't find an interpreter, it issues a warning. On macOS, the extension also issues a warning if you're using the OS-installed Python interpreter, because you typically want to use an interpreter you install directly. In either case, you can disable these warnings by setting `python.disableInstallationCheck` to `true` in your user [settings](/docs/getstarted/settings.md). -To select an specific environment, use the **Python: Select Interpreter** command from the **Command Palette** (`kb(workbench.action.showCommands)`). +To select a specific environment, use the **Python: Select Interpreter** command from the **Command Palette** (`kb(workbench.action.showCommands)`). ![Python: Select Interpreter command](images/environments/select-interpreters-command.png) @@ -80,7 +80,7 @@ The extension automatically looks for interpreters in the following locations: - Virtual environments located directly under the workspace (project) folder. - Virtual environments located in the folder identified by the `python.venvPath` setting (see [General settings](/docs/python/settings-reference.md#general-settings)), which can contain multiple virtual environments. The extension looks for virtual environments in the first-level subfolders of `venvPath`. - Interpreters installed by [pyenv](https://github.com/pyenv/pyenv). -- A [pipenv](https://docs.pipenv.org/) environment for the workplace folder. If one is found then no other interpreters are searched for or listed as pipenv expects to manage all aspects of the environment. +- A [pipenv](https://docs.pipenv.org/) environment for the workplace folder. If one is found, then no other interpreters are searched for or listed as pipenv expects to manage all aspects of the environment. - Conda environments that contain a Python interpreter. VS Code does not show conda environments that don't contain an interpreter. - Interpreters installed in a `.direnv` folder for [direnv](https://direnv.net/) under the workspace (project) folder. @@ -120,7 +120,7 @@ For examples of using virtual environment in projects, see the [Django tutorial] ### Conda environments -A conda environment is a Python environment that's managed using the `conda` package manager (see [Getting started with conda](https://conda.io/docs/user-guide/getting-started.html) (conda.io)). Conda works very well to create environments with interrelated dependencies as well as binary packages. Unlike virtual environments, which are scoped to a project, conda environments are available globally on any given computer. This availability makes it easy to configure several distinct conda environments and then choose the appropriate one for any given project. +A conda environment is a Python environment that's managed using the `conda` package manager (see [Getting started with conda](https://conda.io/docs/user-guide/getting-started.html) (conda.io)). Conda works well to create environments with interrelated dependencies as well as binary packages. Unlike virtual environments, which are scoped to a project, conda environments are available globally on any given computer. This availability makes it easy to configure several distinct conda environments and then choose the appropriate one for any given project. As noted earlier, the Python extension automatically detects existing conda environments provided that the environment contains a Python interpreter. For example, the following command creates a conda environment with the Python 3.4 interpreter and several libraries, which VS Code then shows in the list of available interpreters: @@ -189,7 +189,7 @@ An environment variable definitions file is a simple text file containing key-va By default, the Python extension loads a file named `.env` in the current workspace folder, as identified by the default entry `"python.envFile": "${workspaceFolder}/.env"` in your user settings (see [General settings](/docs/python/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 - Set configuration options](/docs/python/debugging.md#set-configuration-options)). This property allows you to easily set variables for debugging purposes that replace those used in the default `.env` file. +A debug configuration also contains an `envFile` property that also defaults to the `.env` file in the current workspace (see [Debugging - Set configuration options](/docs/python/debugging.md#set-configuration-options)). This property allows you to easily set variables for debugging purposes that replace variables specified 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: @@ -229,7 +229,7 @@ The [PYTHONPATH](https://docs.python.org/3/using/cmdline.html#envvar-PYTHONPATH) > **Note**: you must set the PYTHONPATH variable through your operating system as VS Code doesn't provide a means to set environment variables directly. -In VS Code, PYTHONPATH affects debugging, linting, IntelliSense, unit testing, and any other operation that depends on Python resolving modules. For example, suppose you have source code in a `src` folder and tests in a `tests` folder. When running tests, however, they can't normally access modules in `src` unless you hard-code relative paths. To solve this, add the path to `src` to PYTHONPATH. +In VS Code, PYTHONPATH affects debugging, linting, IntelliSense, unit testing, and any other operation that depends on Python resolving modules. For example, suppose you have source code in a `src` folder and tests in a `tests` folder. When running tests, however, they can't normally access modules in `src` unless you hard-code relative paths. To solve this problem, add the path to `src` to PYTHONPATH. It's recommended that you set the PYTHONPATH variable in an [Environment variable definitions file](#environment-variable-definitions-file), described earlier. diff --git a/docs/python/jupyter-support.md b/docs/python/jupyter-support.md index 149932d71b..3a954464f8 100644 --- a/docs/python/jupyter-support.md +++ b/docs/python/jupyter-support.md @@ -11,7 +11,7 @@ MetaSocialImage: images/tutorial/social.png # Working with Jupyter Notebooks in Visual Studio Code -[Jupyter](http://jupyter-notebook.readthedocs.io/en/latest/) (formerly IPython) is an open source project that lets you easily combine Markdown text and executable Python source code on one canvas called a *notebook*. +[Jupyter](http://jupyter-notebook.readthedocs.io/en/latest/) (formerly IPython) is an open-source project that lets you easily combine Markdown text and executable Python source code on one canvas called a *notebook*. To work with Jupyter notebooks, you must activate an Anaconda environment in VS Code, or another Python environment in which you've installed the [Jupyter package](https://pypi.org/project/jupyter/). To select an environment, use the **Python: Select Interpreter** command from the Command Palette (`kb(workbench.action.showCommands)`). diff --git a/docs/python/linting.md b/docs/python/linting.md index f9afa803be..35407505bb 100644 --- a/docs/python/linting.md +++ b/docs/python/linting.md @@ -10,7 +10,7 @@ MetaSocialImage: images/tutorial/social.png --- # Linting Python in Visual Studio Code -Linting highlights syntactical and stylistic problems in your Python source code, which oftentimes helps you identify and correct subtle programming errors or just unconventional coding practices. For example, linting detects use of an uninitialized or undefined variable, calls to undefined functions, missing parentheses, and even more subtle issues such as attempting to redefine a built-in types or functions. Linting is thus distinct from [Formatting](editing.md#formatting) because linting analyzes how the code runs and detects errors whereas formatting simply restructures how code *appears*. +Linting highlights syntactical and stylistic problems in your Python source code, which oftentimes helps you identify and correct subtle programming errors or unconventional coding practices that can lead to errors. For example, linting detects use of an uninitialized or undefined variable, calls to undefined functions, missing parentheses, and even more subtle issues such as attempting to redefine built-in types or functions. Linting is thus distinct from [Formatting](editing.md#formatting) because linting analyzes how the code runs and detects errors whereas formatting simply restructures how code *appears*. By default, linting for Python is enabled in Visual Studio Code using [Pylint](https://www.pylint.org), and you can enable other linters of your choice. You can easily enable and disable all linting by using the **Python: Enable Linting** command. @@ -77,7 +77,7 @@ Custom arguments are specified in the appropriate arguments setting for each lin "python.linting.pydocstyleArgs": ["--ignore=D400", "--ignore=D4"] ``` -Note that if a top-level element is a single value, as delineated by quotation marks or braces, is still a single item in the list even if the value itself contains spaces. +Note that if a top-level element is a single value, as delineated by quotation marks or braces, is still appears as a single item in the list even if the value itself contains spaces. A custom path is generally unnecessary as the Python extension resolves the path to the linter based on the Python interpreter being used (see [Environments](/docs/python/environments.md)). To use a different version of a linter, specify its path in the appropriate custom path setting. For example, if your selected interpreter is a virtual environment but you want to use a linter that's installed in a global environment, then set the appropriate path setting to point to the global environment's linter. @@ -124,7 +124,7 @@ For the complete list of Pylint messages, see [readable-pylint-messages](https:/ ### Command-line arguments and configuration files -See [Pylint command line arguments](https://pylint.readthedocs.io/en/latest/user_guide/run.html#command-line-options) for general switches. Command line arguments can be used to load Pylint plugins, such as that for Django: +See [Pylint command line arguments](https://pylint.readthedocs.io/en/latest/user_guide/run.html#command-line-options) for general switches. Command-line arguments can be used to load Pylint plugins, such as the plugin for Django: ```json "python.linting.pylintArgs": ["--load-plugins", "pylint_django"] @@ -251,7 +251,7 @@ By default, Flake8 ignores E121, E123, E126, E226, E24, and E704. Flake8 user options are read from the `C:\Users\\.flake8` (Windows) or `~/.config/flake8` (macOS/Linux) file. -At the project level, options are read from the `[flake8]` section of a `tox.ini`, `setup.cfg` or `.flake8` file. +At the project level, options are read from the `[flake8]` section of a `tox.ini`, `setup.cfg`, or `.flake8` file. For details, see [Flake8 configuration](http://flake8.pycqa.org/en/latest/user/configuration.html). diff --git a/docs/python/python-tutorial.md b/docs/python/python-tutorial.md index a2cd00728d..c2e4e6a97d 100644 --- a/docs/python/python-tutorial.md +++ b/docs/python/python-tutorial.md @@ -4,7 +4,7 @@ Area: python TOCTitle: Tutorial ContentId: 77828f36-ae45-4887-b25c-34545edd52d3 PageTitle: Get Started Tutorial for Python in Visual Studio Code -DateApproved: 01/14/2019 +DateApproved: 01/29/2019 MetaDescription: A Python hello world tutorial using the Python extension in Visual Studio Code (a great Python IDE like PyCharm, if not the best Python IDE) MetaSocialImage: images/tutorial/social.png --- @@ -20,7 +20,7 @@ If you have any problems, feel free to file an issue for this tutorial in the [V ## Prerequisites -To successfully complete this tutorial, you must do the following: +To successfully complete this tutorial, complete the following requirements: 1. Install the [Python extension for VS Code](https://marketplace.visualstudio.com/items?itemName=ms-python.python). @@ -30,7 +30,7 @@ To successfully complete this tutorial, you must do the following: - (macOS) An installation through [Homebrew](https://brew.sh/) on macOS using `brew install python3` (the system install of Python on macOS is not supported). - (All operating systems) A download from [Anaconda](https://www.anaconda.com/download/) (for data science purposes). -1. On Windows, make sure the location of your Python interpreter (that is, the folder where it's installed, like `c:\python32`) is included in your PATH environment variable. You can check this by running `path` at the command prompt. If the Python interpreter's folder isn't included, open Windows Settings, search for "environment", select **Edit environment variables for your account**, then edit the **Path** variable to include that folder. +1. On Windows, make sure the location of your Python interpreter (that is, the folder where it's installed, like `c:\python32`) is included in your PATH environment variable. You can check the location by running `path` at the command prompt. If the Python interpreter's folder isn't included, open Windows Settings, search for "environment", select **Edit environment variables for your account**, then edit the **Path** variable to include that folder. 1. On MacOS, make sure the location of your VS Code installation is included in your PATH environment variable. See [the setup instructions](/docs/setup/mac.md#launching-from-the-command-line) for more information. @@ -105,14 +105,14 @@ The command opens a terminal panel in which your Python interpreter is automatic There are two other ways you can run Python within VS Code: -- Select one or more lines, then press `kbstyle(Shift+Enter)` or right-click and select **Run Selection/Line in Python Terminal**. This command is very convenient for testing just a part of a file. -- Use the **Python: Start REPL** command to open a REPL terminal for the currently selected Python interpreter. In the REPL you can then enter and run lines of code one at a time. +- Select one or more lines, then press `kbstyle(Shift+Enter)` or right-click and select **Run Selection/Line in Python Terminal**. This command is convenient for testing just a part of a file. +- Use the **Python: Start REPL** command to open a REPL terminal for the currently selected Python interpreter. In the REPL, you can then enter and run lines of code one at a time. ## Configure and run the debugger Let's now try debugging our simple Hello World program. -First, set a breakpoint on line 2 of `hello.py` by placing the cursor on the `print` call and pressing `kb(editor.debug.action.toggleBreakpoint)`. Alternately, just click in the editor's left gutter, next to the line numbers. When you do this, a red circle appears in the gutter. +First, set a breakpoint on line 2 of `hello.py` by placing the cursor on the `print` call and pressing `kb(editor.debug.action.toggleBreakpoint)`. Alternately, just click in the editor's left gutter, next to the line numbers. When you set a breakpoint, a red circle appears in the gutter. ![Setting a breakpoint in hello.py](images/tutorial/breakpoint-set.png) @@ -224,7 +224,7 @@ If you see the message, "Python interpreter is not found because python.exe is n ## Install and use packages -Let's now run an example that's a little more interesting. In Python, packages are how you obtain any number of useful code libraries, typically from [PyPI](https://pypi.org/). For this example you use the `matplotlib` and `numpy` packages to create a graphical plot as is commonly done with data science. (Note that `matplotlib` cannot show graphs when running in the [Windows Subsystem for Linux](https://docs.microsoft.com/windows/wsl/about) as it lacks the necessary UI support.) +Let's now run an example that's a little more interesting. In Python, packages are how you obtain any number of useful code libraries, typically from [PyPI](https://pypi.org/). For this example, you use the `matplotlib` and `numpy` packages to create a graphical plot as is commonly done with data science. (Note that `matplotlib` cannot show graphs when running in the [Windows Subsystem for Linux](https://docs.microsoft.com/windows/wsl/about) as it lacks the necessary UI support.) Return to the **Explorer** view (the top-most icon on the left side, which shows files), create a new file called `standardplot.py`, and paste in the following source code: @@ -267,7 +267,7 @@ Rerun the program now (with or without the debugger) and after a few moments a p ### Use a virtual environment -A best practice among Python developers is to avoid installing packages into a global interpreter environment, as we did in the previous section. You instead use a project-specific *virtual environment* that contains a copy of a global interpreter. Once you activate that environment, any packages you then install are isolated from other environments, which reduces many complications that can arise from conflicting package versions. +A best practice among Python developers is to avoid installing packages into a global interpreter environment, as we did in the previous section. You instead use a project-specific *virtual environment* that contains a copy of a global interpreter. Once you activate that environment, any packages you then install are isolated from other environments. Such isolation reduces many complications that can arise from conflicting package versions. For examples of creating and activating a virtual environment and installing packages, see the [Django tutorial](/docs/python/tutorial-django.md) and the [Flask tutorial](/docs/python/tutorial-flask.md). diff --git a/docs/python/settings-reference.md b/docs/python/settings-reference.md index 181e7a53d4..c01b4e50be 100644 --- a/docs/python/settings-reference.md +++ b/docs/python/settings-reference.md @@ -20,13 +20,13 @@ Refer to [User and workspace settings](/docs/getstarted/settings.md) to find our | --- | --- | --- | | python.condaPath | `"conda"` | Path to the `conda` executable. | | python.pythonPath | `"python"` | Path to the python interpreter, or the path to a folder containing the Python interpreter. Can use variables like `${workspaceFolder}` and `${workspaceFolder}/.venv`. Using a path to a folder allows anyone working with a project to create an environment in the `.venv` folder as appropriate to their operating system, rather than having to specify an exact platform-dependent path. The `settings.json` file can then be included in a source code repository. | -| python.disableInstallationCheck | `false` | If set to `true`, disables a warning from the extension if no Python interpreter is installed. On macOS, also disables a warning that appears if you're using the OS-installed Python interpreter. It's generally recommended to install an separate interpreter on macOS. | -| python.venvPath | `""` | Path to a folder, where virtual environments are created. Depending on the virtualization tool used, it can be the project itself: `${workspaceFolder}`, or separate folder for all virtual enviroments located side-by-side: `.\envs`, `~/.virtualenvs`, and so on. | +| python.disableInstallationCheck | `false` | If set to `true`, disables a warning from the extension if no Python interpreter is installed. On macOS, also disables a warning that appears if you're using the OS-installed Python interpreter. It's generally recommended to install a separate interpreter on macOS. | +| python.venvPath | `""` | Path to a folder, where virtual environments are created. Depending on the virtualization tool used, it can be the project itself: `${workspaceFolder}`, or separate folder for all virtual environments located side by side: `.\envs`, `~/.virtualenvs`, and so on. | | python.envFile | `"${workspaceFolder}/.env"` | Absolute path to a file containing environment variable definitions. See [Configuring Python environments - environment variable definitions file](/docs/python/environments.md#environment-variable-definitions-file). | | python.globalModuleInstallation | `false` | Specifies whether to install packages for the current user only using the `--user` command-line argument (the default), or to install for all users in the global environment (when set to `true`). Ignored when using a virtual environment. For more information on the `--user`argument, see [pip - User Installs](https://pip.pypa.io/en/stable/user_guide/#user-installs). | | python.terminal.launchArgs | `[]` | Launch arguments that are given to the Python interpreter when you run a file using commands such as **Python: Run Python File in Terminal**. In the `launchArgs` list, each item is a top-level command-line element that's separated by a space (quoted values that contain spaces are a single top-level element and are thus one item in the list). For example, for the arguments `--a --b --c {"value1" : 1, "value2" : 2}`, the list items should be `["--a", "--b", "--c", "{\"value1\" : 1, \"value2\" : 2}\""]`. Note that Visual Studio code ignores this setting when debugging because it instead uses arguments from your selected debugging configuration in `launch.json`. | | python.terminal.executeInFileDir | `false` | Indicates whether to run a file in the file's directory instead of the current folder. | -| python.terminal.activateEnvironment | `true` | Indicates whether to automatically activate the environment you select using the **Python: Select Interpreter** command. For example, when this setting is `true` and you select a virtual envrionment, the extension automatically runs the environment's activate command (`source env/bin/activate` on macOS/Linux; `env\scripts\activate` on Windows). | +| python.terminal.activateEnvironment | `true` | Indicates whether to automatically activate the environment you select using the **Python: Select Interpreter** command. For example, when this setting is `true` and you select a virtual environment, the extension automatically runs the environment's *activate* command (`source env/bin/activate` on macOS/Linux; `env\scripts\activate` on Windows). | ## Workspace symbol (tags) settings @@ -36,8 +36,8 @@ Workspace symbols are symbols in C source code generated by the ctags tool (desc | --- | --- | --- | | tagFilePath | `"${workspaceFolder}/.vscode/tags"` | Fully qualified path to tag file (an exuberant ctag file), used to provide workspace symbols. | | enabled | `true` | Specifies whether to enable the Workspace Symbol provider. | -| rebuildOnStart | `true` | Specifies whether to re-build the tags file on start. | -| rebuildOnFileSave | `true` | Specifies whether to re-build the tags file on when saving a Python file. | +| rebuildOnStart | `true` | Specifies whether to rebuild the tags file on start. | +| rebuildOnFileSave | `true` | Specifies whether to rebuild the tags file on when saving a Python file. | | ctagsPath | `"ctags"` | Fully qualified path to the ctags executable; default value assumes it's in the current environment. | | exclusionPatterns | `["**/site-packages/**"]` | Pattern used to exclude files and folders from ctags. | @@ -49,7 +49,7 @@ Workspace symbols are symbols in C source code generated by the ctags tool (desc | --- | --- | --- | | python.jediEnabled | `true` | Indicates whether to use Jedi as the IntelliSense engine (true) or the [Microsoft Python Language Server](http://blogs.msdn.microsoft.com/pythonengineering/2018/07/18/introducing-the-python-language-server/) (false). Note that the language server requires a platform that [supports .NET Core 2.1 or newer](https://docs.microsoft.com/dotnet/core/rid-catalog). | | python.jediPath | `""` | Path to folder containing the Jedi library (folder should contain a `jedi` subfolder). | -| python.jediMemoryLimit | 0 | Memory limit for the Jedi completion engine in megabytes. Zero (the default) means 1024MB. -1 disables the memory limit check. | +| python.jediMemoryLimit | 0 | Memory limit for the Jedi completion engine in megabytes. Zero (the default) means 1024 MB. -1 disables the memory limit check. | ### Python Language Server settings @@ -88,7 +88,7 @@ To suppress the "used-before-assignment" messages, for example, use the setting | --- | --- | --- | --- | | provider | `"autopep8"` | Specifies the formatter to use, either "autopep8", "black", or "yapf". |[Editing - Formatting](/docs/python/editing.md#formatting) | | autopep8Path | `"autopep8"` | Path to autopep8 | [Editing - Formatting](/docs/python/editing.md#formatting) | -| autopep8Args| `[]` | Arguments for autopep8 where each top-level element that's separated by a space is a separate item in the list. | [Editing - Formatting](/docs/python/editing.md#formatting) | +| autopep8Args| `[]` | Arguments for autopep8, where each top-level element that's separated by a space is a separate item in the list. | [Editing - Formatting](/docs/python/editing.md#formatting) | | blackPath | `"black"` | Path to black | [Editing - Formatting](/docs/python/editing.md#formatting) | | blackArgs| `[]` | Arguments for black, where each top-level element that's separated by a space is a separate item in the list. | [Editing - Formatting](/docs/python/editing.md#formatting) | | yapfPath | `"yapf"` | Path to yapf | [Editing - Formatting](/docs/python/editing.md#formatting) | diff --git a/docs/python/tutorial-deploy-app-service-on-linux.md b/docs/python/tutorial-deploy-app-service-on-linux.md index 8d1c2341b8..cf66afc18b 100644 --- a/docs/python/tutorial-deploy-app-service-on-linux.md +++ b/docs/python/tutorial-deploy-app-service-on-linux.md @@ -24,7 +24,7 @@ If you encounter any problems in the course of this tutorial, feel free to file ## Prerequisites -To complete this tutorial you need an Azure account, Visual Studio Code with the Azure App Service extension, a Python environment, and an app that you'd like to deploy. +To complete this tutorial, you need an Azure account, Visual Studio Code with the Azure App Service extension, a Python environment, and an app that you'd like to deploy. ### Azure account @@ -32,7 +32,7 @@ If you don't have an Azure account, [sign up now](https://azure.microsoft.com/fr ### Visual Studio Code, Python, and the Azure App Service extension -Install the following: +Install the following software: - [Visual Studio Code](https://code.visualstudio.com/). - Python and the [Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python) extension as described on [Python Tutorial - Prerequisites](/docs/python/python-tutorial.md). @@ -128,9 +128,9 @@ If you need a custom startup file, first create the file and commit it to your r ![Open Settings in Portal command in the App Service explorer](images/deploy-azure/open-settings-in-portal-command.png) -1. In the Azure portal, sign in if necessary; then on the **Application settings** page, enter your startup file name (like `startup.txt`) under **Runtime** > **Startup File**, then select **Save**. (This is the one case in which you need to visit the Azure portal.) +1. In the Azure portal, sign in if necessary; then on the **Application settings** page, enter your startup file name (like `startup.txt`) under **Runtime** > **Startup File**, then select **Save**. (This step is the one case in which you need to visit the Azure portal.) - ![Setting the startup file name in the Azure Portal](images/deploy-azure/azure-portal-startup-file.png) + ![Setting the startup file name in the Azure portal](images/deploy-azure/azure-portal-startup-file.png) 1. The App Service restarts when you save changes. Because you still haven't deployed your app code, however, visiting the site at this point shows "Application Error." This message indicates that the Gunicorn server started but failed to find the app, and therefore nothing is responding to HTTP requests. @@ -152,7 +152,7 @@ By default, the App Service on Linux container assumes that a Flask app's startu gunicorn --bind=0.0.0.0 --timeout 600 --chdir myapp website:app ``` -1. **Startup file is within a module**: in the [python-sample-vscode-flask-tutorial](https://github.com/Microsoft/python-sample-vscode-flask-tutorial) code, the `webapp.py` startup file is contained within the folder `hello_app`, which is itself a module with an `__init__.py` file. The app object is named `app` and is defined in `__init__.py` and `webapp.py` uses a relative import. Because of this arrangement, pointing Gunicorn to `webapp:app` produces a "Attempted relative import in non-package" error and the app fails to start. +1. **Startup file is within a module**: in the [python-sample-vscode-flask-tutorial](https://github.com/Microsoft/python-sample-vscode-flask-tutorial) code, the `webapp.py` startup file is contained within the folder `hello_app`, which is itself a module with an `__init__.py` file. The app object is named `app` and is defined in `__init__.py` and `webapp.py` uses a relative import. Because of this arrangement, pointing Gunicorn to `webapp:app` produces the error, "Attempted relative import in non-package," and the app fails to start. In this situation, create a simple shim file that imports the app object from the module, and then have Gunicorn launch the app using the shim. The [python-sample-vscode-flask-tutorial](https://github.com/Microsoft/python-sample-vscode-flask-tutorial) code, for example, contains `startup.py` with the following contents: @@ -199,7 +199,7 @@ As noted earlier, you must deploy to App Service on Linux using Git in order for ![Opening the repository after initialization](images/deploy-azure/source-control-open-repository.png) -1. In the **Source Control** explorer you see your project files ready to commit to the repository. Enter a commit message like "Initial commit", then select the checkmark button: +1. In the Source Control explorer, you see your project files ready to commit to the repository. Enter a commit message like "Initial commit", then select the checkmark button: ![Commit the app code to source control](images/deploy-azure/source-control-commit.png) @@ -223,7 +223,7 @@ As mentioned earlier, you must use Git to deploy Python apps to App Service on L 1. To deploy the app: - - **LocalGit**: Commit your changes to your local repository, then right-click the App Service again, select **Deploy to Web App**, and select the project folder when prompted. (You can also select use the deploy button at the top of the explorer.) + - **LocalGit**: Commit your changes to your local repository, then right-click the App Service again, select **Deploy to Web App**, and select the project folder when prompted. (You can also select the deploy button at the top of the explorer.) ![Deploy to Web App command on an App Service in the App Service explorer](images/deploy-azure/deploy-to-web-app-command.png) @@ -283,7 +283,7 @@ When you use the App Service extension in VS Code to set GitHub as the deploymen Congratulations on completing this walkthrough of deploying Python code to App Service on Linux! -As noted earlier, you can learn more about the App Service extension by visiting its GitHub repository, [vscode-azureappservice](https://github.com/Microsoft/vscode-azureappservice). Issues and contributions are also very welcome. +As noted earlier, you can learn more about the App Service extension by visiting its GitHub repository, [vscode-azureappservice](https://github.com/Microsoft/vscode-azureappservice). Issues and contributions are also welcome. To learn more about Azure services that you can use from Python, including data storage along with AI and Machine Learning services, visit [Azure Python Developer Center](https://docs.microsoft.com/python/azure/?view=azure-python). diff --git a/docs/python/tutorial-deploy-containers.md b/docs/python/tutorial-deploy-containers.md index 98a8d3dec7..2ad1d6c1b9 100644 --- a/docs/python/tutorial-deploy-containers.md +++ b/docs/python/tutorial-deploy-containers.md @@ -18,9 +18,9 @@ If you have any problems, feel free to file an issue for this tutorial in the [V Docker is a system that allows you to deploy and run apps using **containers** rather than setting up dedicated environments like virtual machines. A container is a lightweight runtime environment that shares the resources of the host operating system with other containers. Docker is the layer that sits above the operating system to manage resources on behalf of containers. -A container is specifically an instance of a Docker **image**, an executable package that contains everything needed to run your app: app code, configuration files, runtimes, and all of app's dependencies. A image can be used to instantiate any number of identical containers, which is especially useful when scaling out a cloud-based web app. Because container images are much smaller than virtual machine images, instances can be started and stopped much more quickly than virtual machines, enabling your app to be highly responsive to varying loads at a minimal cost. (When used to scale web apps, containers are often managed in **clusters**, which are then managed by an orchestration agent such as [Kubernetes](https://wikipedia.org/wiki/Kubernetes).) +A container is specifically an instance of a Docker **image**, an executable package that contains everything needed to run your app: app code, configuration files, runtimes, and all of app's dependencies. An image can be used to instantiate any number of identical containers, which is especially useful when scaling out a cloud-based web app. Because container images are much smaller than virtual machine images, instances can be started and stopped much more quickly than virtual machines, enabling your app to be highly responsive to varying loads at a minimal cost. (When used to scale web apps, containers are often managed in **clusters**, which are then managed by an orchestration agent such as [Kubernetes](https://wikipedia.org/wiki/Kubernetes).) -Images, for their part, are built in multiple **layers**. The lowest or **base** layers of an image are typically common elements like the Python runtime; the higher layers the contain more specialized elements like your app code. Because of layering, it takes very little time to rebuild an image when changing only the top layer with your app code. Similarly, when you push an image to a **container registry**, an online repository for images from which you can deploy to cloud services like Azure, only the modified layers need be uploaded and redeployed. As a result, using containers has only a very small impact on your develop-test-deploy loop. +Images, for their part, are built in multiple **layers**. The lowest or **base** layers of an image are typically common elements like the Python runtime; the higher layers the contain more specialized elements like your app code. Because of layering, it takes very little time to rebuild an image when changing only the top layer with your app code. Similarly, when you push an image to a **container registry**, an online repository for images from which you can deploy to cloud services like Azure, only the modified layers need be uploaded and redeployed. As a result, using containers has only a small impact on your develop-test-deploy loop. You will experience the basics of containers and images in the course of this tutorial. For additional background, including helpful diagrams, refer to the [Docker documentation](https://docs.docker.com/get-started/). @@ -34,7 +34,7 @@ If you don't have an Azure account, [sign up now](https://azure.microsoft.com/fr ### Visual Studio Code, Docker, and Python runtime -Install the following: +Install the following software: - [Visual Studio Code](https://code.visualstudio.com/) - [Docker Community Edition](https://www.docker.com/community-edition). To verify your installation, run the command `docker --version`, which should show output like `Docker version 18.06.1-ce, build e68fc7a`. @@ -170,7 +170,7 @@ The following steps summarize the configuration used in the [python-sample-vscod #RUN pip install --no-cache-dir -r /requirements.txt ``` -1. The `uwsgi.ini` file, which is in the `hello_app` folder of the sample, provides configuration arguments for the uwsgi server. For the sample, the configuration below says that the Flask app object is found in the `hello_app/webapp.py` module, and that it's named (that is, "callable" as) `app`. The other value are additional common uwsgi settings: +1. The `uwsgi.ini` file, which is in the `hello_app` folder of the sample, provides configuration arguments for the uwsgi server. For the sample, the configuration below says that the Flask app object is found in the `hello_app/webapp.py` module, and that it's named (that is, "callable" as) `app`. The other values are additional common uwsgi settings: ```ini [uwsgi] @@ -293,7 +293,7 @@ With the necessary `Dockerfile` in place, you're ready to build the Docker image ### Two useful features of the Docker extension -The Docker extension provides a simple UI to manage and even run your images rather than using the Docker CLI. Just expand the **Image** node in the Docker explorer, right click any image, and select any of the menu items: +The Docker extension provides a simple UI to manage and even run your images rather than using the Docker CLI. Just expand the **Image** node in the Docker explorer, right-click any image, and select any of the menu items: ![Managing images with the Docker extension](images/deploy-containers/manage-images.png) @@ -335,7 +335,7 @@ With an image built and pushed to a registry, you can use the Docker extension i An **App Service Plan** defines the physical resources (an underlying virtual machine) that hosts the running container. For this tutorial, B1 is the least expensive plan that supports Docker containers. (For more information, see [App Service plan overview](https://docs.microsoft.com/azure/app-service/azure-web-sites-web-hosting-plans-in-depth-overview) in the Azure documentation.) - The name of the App Service must be unique across all of Azure, so you typically use a company or personal name. For production sites, you typically configure the App Service with a separately-registered domain name. + The name of the App Service must be unique across all of Azure, so you typically use a company or personal name. For production sites, you typically configure the App Service with a separately registered domain name. 1. Creating the app service takes a few minutes, and you see progress in VS Code's Output panel. @@ -349,7 +349,7 @@ With an image built and pushed to a registry, you can use the Docker extension i ## Make changes and redeploy -Because you inevitably make changes to your app, you end up rebuilding and redeploying your container many times. Fortunately, the process is very simple: +Because you inevitably make changes to your app, you end up rebuilding and redeploying your container many times. Fortunately, the process is simple: 1. Make changes to your app and test locally. @@ -388,7 +388,7 @@ From within VS Code, you can view (or "tail") logs from the running site on Azur Congratulations on completing this walkthrough of deploying a containerized Python app to Azure App Service! -As noted earlier, you can learn more about the Docker and App Service extensions by visiting their respective repositories on GitHub: [vscode-docker](https://github.com/Microsoft/vscode-docker) and [vscode-azureappservice](https://github.com/Microsoft/vscode-azureappservice). Issues and contributions are also very welcome. +As noted earlier, you can learn more about the Docker and App Service extensions by visiting their respective repositories on GitHub: [vscode-docker](https://github.com/Microsoft/vscode-docker) and [vscode-azureappservice](https://github.com/Microsoft/vscode-azureappservice). Issues and contributions are also welcome. To learn more about Azure services that you can use from Python, including data storage along with AI and Machine Learning services, visit [Azure Python Developer Center](https://docs.microsoft.com/python/azure/?view=azure-python). diff --git a/docs/python/tutorial-django.md b/docs/python/tutorial-django.md index 94d59496b7..f776735bab 100644 --- a/docs/python/tutorial-django.md +++ b/docs/python/tutorial-django.md @@ -11,7 +11,7 @@ MetaDescription: Python Django tutorial using the best Python IDE, demonstrating [Django](https://www.djangoproject.com/) is a high-level Python framework designed for rapid, secure, and scalable web development. Django includes rich support for URL routing, page templates, and working with data. -In this tutorial you create a simple Django app with three pages that use a common base template. You create this app in the context of Visual Studio Code in order to understand how to work with Django in the VS Code terminal, editor, and debugger. This tutorial does not explore various details about Django itself, such as working with data models and creating an administrative interface. For guidance on those aspects, refer to the [Django documentation](https://docs.djangoproject.com/en/2.1/intro/tutorial01/). +In this tutorial, you create a simple Django app with three pages that use a common base template. You create this app in the context of Visual Studio Code in order to understand how to work with Django in the VS Code terminal, editor, and debugger. This tutorial does not explore various details about Django itself, such as working with data models and creating an administrative interface. For guidance on those aspects, refer to the [Django documentation](https://docs.djangoproject.com/en/2.1/intro/tutorial01/). The completed code project from this tutorial can be found on GitHub: [python-sample-vscode-django-tutorial](https://github.com/Microsoft/python-sample-vscode-django-tutorial). @@ -29,11 +29,11 @@ To successfully complete this tutorial, you must do the following (which are the - (macOS) An installation through [Homebrew](https://brew.sh/) on macOS using `brew install python3` (the system install of Python on macOS is not supported). - (All operating systems) A download from [Anaconda](https://www.anaconda.com/download/) (for data science purposes). -1. On Windows, make sure the location of your Python interpreter is included in your PATH environment variable. You can check this by running `path` at the command prompt. If the Python interpreter's folder isn't included, open Windows Settings, search for "environment", select **Edit environment variables for your account**, then edit the **Path** variable to include that folder. +1. On Windows, make sure the location of your Python interpreter is included in your PATH environment variable. You can check the location by running `path` at the command prompt. If the Python interpreter's folder isn't included, open Windows Settings, search for "environment", select **Edit environment variables for your account**, then edit the **Path** variable to include that folder. ## Create a project environment for Django -In this section you create a virtual environment in which Django is installed. Using a virtual environment avoids installing Django into a global Python environment and gives you exact control over the libraries used in an application. A virtual environment also makes it easy to [Create a requirements.txt file for the environment](#create-a-requirementstxt-file-for-the-environment). +In this section, you create a virtual environment in which Django is installed. Using a virtual environment avoids installing Django into a global Python environment and gives you exact control over the libraries used in an application. A virtual environment also makes it easy to [Create a requirements.txt file for the environment](#create-a-requirementstxt-file-for-the-environment). 1. On your file system, create a project folder for this tutorial, such as `hello_django`. @@ -80,7 +80,7 @@ You now have a self-contained environment ready for writing Django code. VS Code In Django terminology, a "Django project" is composed of several site-level configuration files along with one or more "apps" that you deploy to a web host to create a full web application. A Django project can contain multiple apps, each of which typically has an independent function in the project, and the same app can be in multiple Django projects. An app, for its part, is just a Python package that follows certain conventions that Django expects. -To create a minimal Django app, then, it's necessary to first create the Django project to serve as the container for the app, then create the app itself. For both purposes you use the Django administrative utility, `django-admin`, which is installed when you install the Django package. +To create a minimal Django app, then, it's necessary to first create the Django project to serve as the container for the app, then create the app itself. For both purposes, you use the Django administrative utility, `django-admin`, which is installed when you install the Django package. ### Create the Django project @@ -113,9 +113,9 @@ To create a minimal Django app, then, it's necessary to first create the Django Quit the server with CTRL-BREAK. ``` - When you run the server the first time, it creates a default SQLite database in the file `db.sqlite3`, which is generally intended for development purposes but can be used in production for low-volume web apps. Also, Django's built-in web server is intended *only* for local development purposes. When you deploy to a web host, however, Django uses the host's web server instead. The `wsgi.py` module in the Django project takes care of hooking into the production servers. + When you run the server the first time, it creates a default SQLite database in the file `db.sqlite3`, which is intended for development purposes but can be used in production for low-volume web apps. Also, Django's built-in web server is intended *only* for local development purposes. When you deploy to a web host, however, Django uses the host's web server instead. The `wsgi.py` module in the Django project takes care of hooking into the production servers. - If you want to use a different port than the default 8000, simply specify the port number on the command line, such as `python manage.py runserver 5000`. + If you want to use a different port than the default 8000, specify the port number on the command line, such as `python manage.py runserver 5000`. 1. `kbstyle(Ctrl+click)` the `http://127.0.0.1:8000/` URL in the terminal output window to open your default browser to that address. If Django is installed correctly and the project is valid, you see the default page shown below. The VS Code terminal output window also shows the server log. @@ -153,7 +153,7 @@ To create a minimal Django app, then, it's necessary to first create the Django ] ``` -1. The `web_project` folder also contains a `urls.py` file, which is where URL routing is actually handled. Open `web_project/urls.py` and modify it to match the following code (you can retain the instructive comments if you like). This code pulls in the app's `hello/urls.py` using `django.urls.include`, which keeps the app's routes contained within the app. This separation is very helpful when a project contains multiple apps. +1. The `web_project` folder also contains a `urls.py` file, which is where URL routing is actually handled. Open `web_project/urls.py` and modify it to match the following code (you can retain the instructive comments if you like). This code pulls in the app's `hello/urls.py` using `django.urls.include`, which keeps the app's routes contained within the app. This separation is helpful when a project contains multiple apps. ```python from django.contrib import admin @@ -288,7 +288,7 @@ Debugging gives you the opportunity to pause a running program on a particular l 1. Use Step Over to run the `now = datetime.now()` statement. -1. On the left side of the VS Code window you see a **Variables** pane that shows local variables, such as `now`, as well as arguments, such as `name`. Below that are panes for **Watch**, **Call Stack**, and **Breakpoints** (see [VS Code debugging](/docs/editor/debugging.md) for details). In the **Locals** section, try expanding different values. You can also double-click values (or use `kb(debug.setVariable)`) to modify them. Changing variables such as `now`, however, can break the program. Developers typically make changes only to correct values when the code didn't produce the right value to begin with. +1. On the left side of the VS Code window, you see a **Variables** pane that shows local variables, such as `now`, as well as arguments, such as `name`. Below that are panes for **Watch**, **Call Stack**, and **Breakpoints** (see [VS Code debugging](/docs/editor/debugging.md) for details). In the **Locals** section, try expanding different values. You can also double-click values (or use `kb(debug.setVariable)`) to modify them. Changing variables such as `now`, however, can break the program. Developers typically make changes only to correct values when the code didn't produce the right value to begin with. ![Local variables and arguments in VS Code during debugging](images/django/debug-local-variables.png) @@ -338,7 +338,7 @@ The app you've created so far in this tutorial generates only plain text web pag A template is an HTML file that contains placeholders for values that the code provides at run time. The Django templating engine takes care of making the substitutions when rendering the page. The code, therefore, concerns itself only with data values and the template concerns itself only with markup. Django templates provide flexible options such as template inheritance, which allows you to define a base page with common markup and then build upon that base with page-specific additions. -In this section you start by creating a single page using a template. In subsequent sections you configure the app to serve static files, and then create multiple pages to the app that each contain a nav bar from a base template. Django templates also supports control flow and iteration, as you see later in this tutorial in the context of template debugging. +In this section, you start by creating a single page using a template. In subsequent sections, you configure the app to serve static files and then create multiple pages to the app that each contains a nav bar from a base template. Django templates also support control flow and iteration, as you see later in this tutorial in the context of template debugging. 1. In the `web_project/settings.py` file, locate the `INSTALLED_APPS` list and add the following entry, which makes sure the project knows about the app so it can handle templating: @@ -456,7 +456,7 @@ In production, you also need to set `DEBUG=False` in `settings.py`, which necess The reason for this extra subfolder is that when you deploy the Django project to a production server, you collect all the static files into a single folder that's then served by a dedicated static file server. The `static/hello` subfolder ensures that when the app's static files are collected, they're in an app-specific subfolder and won't collide with file from other apps in the same project. -1. In the `static/hello` folder, create a file named `site.css` with the following contents. After entering this code, also observe the syntax highlighting that VS Code provide for CSS files, including a color preview. +1. In the `static/hello` folder, create a file named `site.css` with the following contents. After entering this code, also observe the syntax highlighting that VS Code provides for CSS files, including a color preview. ```css .message { @@ -490,7 +490,7 @@ For production deployments, you typically collect all the static files from your STATIC_ROOT = os.path.join(BASE_DIR, 'static_collected') ``` -1. In the Terminal, run the command `python manage.py collectstatic` and observe that `hello/site.css` is copied into the top-level `static_collected` folder alongside `manage.py`. +1. In the Terminal, run the command `python manage.py collectstatic` and observe that `hello/site.css` is copied into the top level `static_collected` folder alongside `manage.py`. 1. In practice, run `collectstatic` any time you change static files and before deploying into production. @@ -646,7 +646,7 @@ With the code snippet in place, you can quickly create templates for the Home, A ### Run the app -With all the page templates in place, save `views.py`, run the app, and open a browser to the home page to see the results. Navigate between the pages to verify that the page template are properly extending the base template. +With all the page templates in place, save `views.py`, run the app, and open a browser to the home page to see the results. Navigate between the pages to verify that the page templates are properly extending the base template. ![Django app rendering a common nav bar from the base template](images/django/full-app.png) @@ -668,7 +668,7 @@ When using the `db.sqlite3` file, you can also work directly with the database u ### Types of databases -By default, Django includes a `db.sqlite3` file for an app's database that's suitable for development work. As described on [When to use SQLite](https://www.sqlite.org/whentouse.html) (sqlite.org), SQLite works fine for low to medium traffic sites with fewer than 100K hits/day, but is not recommended for higher volumes. It's also limited to a single computer, so it cannot be used in any multi-server scenario such as load-balancing and geo-replication. +By default, Django includes a `db.sqlite3` file for an app's database that's suitable for development work. As described on [When to use SQLite](https://www.sqlite.org/whentouse.html) (sqlite.org), SQLite works fine for low to medium traffic sites with fewer than 100 K hits/day, but is not recommended for higher volumes. It's also limited to a single computer, so it cannot be used in any multi-server scenario such as load-balancing and geo-replication. For these reasons, consider using a production-level data store such as [PostgreSQL](https://www.postgresql.org/), [MySQL](https://www.mysql.com/), and [SQL Server](https://www.microsoft.com/en-ca/sql-server/). For information on Django's support for other databases, see [Database setup](https://docs.djangoproject.com/en/2.1/intro/tutorial02/#database-setup). You can also use the [Azure SDK for Python](https://docs.microsoft.com/visualstudio/python/azure-sdk-for-python) to work with Azure storage services like tables and blobs. @@ -921,7 +921,7 @@ Accordingly, developers typically omit the virtual environment folder from sourc Although you can create the file by hand, you can also use the `pip freeze` command to generate the file based on the exact libraries installed in the activated environment: -1. With your chosen environment selected using the **Python: Select Interpreter** command, tun the **Terminal: Create New Integrated Terminal** command (`kb(workbench.action.terminal.new)`)) to open a terminal with that environment activated. +1. With your chosen environment selected using the **Python: Select Interpreter** command, run the **Terminal: Create New Integrated Terminal** command (`kb(workbench.action.terminal.new)`)) to open a terminal with that environment activated. 1. In the terminal, run `pip freeze > requirements.txt` to create the `requirements.txt` file in your project folder. diff --git a/docs/python/tutorial-flask.md b/docs/python/tutorial-flask.md index 72080c7722..8d766a521d 100644 --- a/docs/python/tutorial-flask.md +++ b/docs/python/tutorial-flask.md @@ -4,7 +4,7 @@ Area: python TOCTitle: Flask Tutorial ContentId: 593d2dd6-20f0-4ad3-8ecd-067cc47ee217 PageTitle: Python and Flask Tutorial in Visual Studio Code -DateApproved: 09/18/2018 +DateApproved: 01/29/2018 MetaDescription: Python Flask tutorial showing IntelliSense, debugging, and code navigation support in the Visual Studio Code editor. MetaSocialImage: images/tutorial/social.png --- @@ -14,7 +14,7 @@ MetaSocialImage: images/tutorial/social.png Flask is called a "micro" framework because it doesn't directly provide features like form validation, database abstraction, authentication, and so on. Such features are instead provided by special Python packages called Flask [extensions](http://flask.pocoo.org/extensions/). The extensions integrate seamlessly with Flask so that they appear as if they were part of Flask itself. For example, Flask doesn't provide a page template engine, but installing Flask includes the [Jinja](http://jinja.pocoo.org/) templating engine by default. For convenience, we typically speak of these defaults as part of Flask. -In this tutorial you create a simple Flask app with three pages that use a common base template. Along the way you experience a number of features of Visual Studio Code including using the terminal, the editor, the debugger, code snippets, and more. +In this tutorial, you create a simple Flask app with three pages that use a common base template. Along the way, you experience a number of features of Visual Studio Code including using the terminal, the editor, the debugger, code snippets, and more. The completed code project from this tutorial can be found on GitHub: [python-sample-vscode-flask-tutorial](https://github.com/Microsoft/python-sample-vscode-flask-tutorial). @@ -32,11 +32,11 @@ To successfully complete this tutorial, you must do the following (which are the - (macOS) An installation through [Homebrew](https://brew.sh/) on macOS using `brew install python3` (the system install of Python on macOS is not supported). - (All operating systems) A download from [Anaconda](https://www.anaconda.com/download/) (for data science purposes). -1. On Windows, make sure the location of your Python interpreter is included in your PATH environment variable. You can check this by running `path` at the command prompt. If the Python interpreter's folder isn't included, open Windows Settings, search for "environment", select **Edit environment variables for your account**, then edit the **Path** variable to include that folder. +1. On Windows, make sure the location of your Python interpreter is included in your PATH environment variable. You can check the location by running `path` at the command prompt. If the Python interpreter's folder isn't included, open Windows Settings, search for "environment", select **Edit environment variables for your account**, then edit the **Path** variable to include that folder. ## Create a project environment for Flask -In this section you create a virtual environment in which Flask is installed. Using a virtual environment avoids installing Flask into a global Python environment and gives you exact control over the libraries used in an application. A virtual environment also makes it easy to [Create a requirements.txt file for the environment](#create-a-requirementstxt-file-for-the-environment). +In this section, you create a virtual environment in which Flask is installed. Using a virtual environment avoids installing Flask into a global Python environment and gives you exact control over the libraries used in an application. A virtual environment also makes it easy to [Create a requirements.txt file for the environment](#create-a-requirementstxt-file-for-the-environment). 1. On your file system, create a project folder for this tutorial, such as `hello_flask`. @@ -121,7 +121,7 @@ You now have a self-contained environment ready for writing Flask code. VS Code If you see an error that the Flask module cannot be found, make sure you've run `pip3 install flask` (macOS/Linux) or `pip install flask` (Windows) in your virtual environment as described at the end of the previous section. - Also, if you want to run the development server on a different IP address or port, use the host and port command line arguments, as with `--host=0.0.0.0 --port=80`. + Also, if you want to run the development server on a different IP address or port, use the host and port command-line arguments, as with `--host=0.0.0.0 --port=80`. 1. To open your default browser to the rendered page, `kbstyle(Ctrl+click)` the `http://127.0.0.1:5000/` URL in the terminal. @@ -216,7 +216,7 @@ Debugging gives you the opportunity to pause a running program on a particular l > **Note**: If the `env` entry in your configuration contains `"FLASK_APP": "${workspaceFolder}/app.py"`, change it to `"FLASK_APP": "app.py"` as shown above. Otherwise you may encounter error messages like "Cannot import module C" where C is the drive letter where your project folder resides. -1. Save `launch.json` (`kb(workbench.action.files.save)`). In the debug configuration drop-down list (which reads **Python: Current File**) select the **Python: Flask (0.11.x or later)** configuration . +1. Save `launch.json` (`kb(workbench.action.files.save)`). In the debug configuration drop-down list (which reads **Python: Current File**) select the **Python: Flask (0.11.x or later)** configuration. ![Selecting the Flask debugging configuration](images/flask/debug-select-configuration.png) @@ -238,7 +238,7 @@ Debugging gives you the opportunity to pause a running program on a particular l 1. Use Step Over to run the `now = datetime.now()` statement. -1. On the left side of the VS Code window you see a **Variables** pane that shows local variables, such as `now`, as well as arguments, such as `name`. Below that are panes for **Watch**, **Call Stack**, and **Breakpoints** (see [VS Code debugging](/docs/editor/debugging.md) for details). In the **Locals** section, try expanding different values. You can also double-click values (or use `kb(debug.setVariable)`) to modify them. Changing variables such as `now`, however, can break the program. Developers typically make changes only to correct values when the code didn't produce the right value to begin with. +1. On the left side of the VS Code window, you see a **Variables** pane that shows local variables, such as `now`, as well as arguments, such as `name`. Below that are panes for **Watch**, **Call Stack**, and **Breakpoints** (see [VS Code debugging](/docs/editor/debugging.md) for details). In the **Locals** section, try expanding different values. You can also double-click values (or use `kb(debug.setVariable)`) to modify them. Changing variables such as `now`, however, can break the program. Developers typically make changes only to correct values when the code didn't produce the right value to begin with. ![Local variables and arguments in VS Code during debugging](images/flask/debug-local-variables.png) @@ -289,7 +289,7 @@ The app you've created so far in this tutorial generates only plain text web pag - A template is an HTML file that contains placeholders for values that the code provides at run time. The templating engine takes care of making the substitutions when rendering the page. The code, therefore, concerns itself only with data values and the template concerns itself only with markup. - The default templating engine for Flask is [Jinja](http://jinja.pocoo.org/), which is installed automatically when you install Flask. This engine provides flexible options including template inheritance. With inheritance, you can define a base page with common markup and then build upon that base with page-specific additions. -In this section you create a single page using a template. In the sections that follow, you configure the app to serve static files, and then create multiple pages to the app that each contain a nav bar from a base template. +In this section, you create a single page using a template. In the sections that follow, you configure the app to serve static files, and then create multiple pages to the app that each contains a nav bar from a base template. 1. Inside the `hello_flask` folder, create a folder named `templates`, which is where Flask looks for templates by default. @@ -383,7 +383,7 @@ The following sections demonstrate both types of static files. 1. In the `hello_flask` folder, create a folder named `static`. -1. Within the `static` folder, create a file named `site.css` with the following contents. After entering this code, also observe the syntax highlighting that VS Code provide for CSS files, including a color preview: +1. Within the `static` folder, create a file named `site.css` with the following contents. After entering this code, also observe the syntax highlighting that VS Code provides for CSS files, including a color preview: ```css .message { @@ -414,7 +414,7 @@ The following sections demonstrate both types of static files. ### Serve a static file from code -1. In the `static` folder, create a JSON data file named `data.json` with the following contents (which are just meaningless sample data): +1. In the `static` folder, create a JSON data file named `data.json` with the following contents (which are meaningless sample data): ```json { @@ -582,7 +582,7 @@ With the code snippet in place, you can quickly create templates for the Home, A ### Run the app -With all the page templates in place, save `app.py`, run the app, and open a browser to see the results. Navigate between the pages to verify that the page template are properly extending the base template. +With all the page templates in place, save `app.py`, run the app, and open a browser to see the results. Navigate between the pages to verify that the page templates are properly extending the base template. ![Flask app rendering a common nav bar from the base template](images/flask/full-app.png) diff --git a/docs/python/unit-testing.md b/docs/python/unit-testing.md index d03ca0a633..a793fcc5a8 100644 --- a/docs/python/unit-testing.md +++ b/docs/python/unit-testing.md @@ -71,7 +71,7 @@ The following steps give you a quick walkthrough of working with tests in VS Cod 1. VS Code displays tests results directly in the editor, where you can see that one test passed and one failed: - ![Test result adornments on a unit test methods](images/unit-testing/result-adornments.png) + ![Test result adornments on a unit test method](images/unit-testing/result-adornments.png) VS Code also shows test results in the **Python Test Log** output panel (use the **View** > **Output** menu command to show the **Output** panel, then select **Python Test Log** from the drop-down on the right side): @@ -192,7 +192,7 @@ The behavior of unit testing with Python is driven by both general settings and The default arguments for UnitTest are as follows: - `-v` sets default verbosity. Remove this argument for simpler output. -- `-s .` specifies the starting directory for discovering tests. If you have tests in a "test" folder, you can change this to `-s test` (meaning `"-s", "test"` in the arguments array). +- `-s .` specifies the starting directory for discovering tests. If you have tests in a "test" folder, change the argument to `-s test` (meaning `"-s", "test"` in the arguments array). - `-p *test*.py` is the discovery pattern used to look for tests. In this case, it's any `.py` file that includes the word "test". If you name test files differently, such as appending "\_test" to every filename, then use a pattern like `*_test.py` in the appropriate argument of the array. To stop a test run on the first failure, add the fail fast option `"-f"` to the arguments array.