diff --git a/docs/python/images/flask-tutorial/command-palette.png b/docs/python/images/flask-tutorial/command-palette.png new file mode 100644 index 0000000000..16ff6f9a9d --- /dev/null +++ b/docs/python/images/flask-tutorial/command-palette.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:71a8c892aa5b08636cad7200ecc1e4e8f44f117be855f4524dd5217be1256626 +size 125752 diff --git a/docs/python/images/flask-tutorial/debug-status-bar.png b/docs/python/images/flask-tutorial/debug-status-bar.png index 5fbadee95b..e6096bd5fa 100644 --- a/docs/python/images/flask-tutorial/debug-status-bar.png +++ b/docs/python/images/flask-tutorial/debug-status-bar.png @@ -1,3 +1,3 @@ version https://git-lfs.github.com/spec/v1 -oid sha256:3889933dc221e15a74c889d47f3e41a90a7a88f69f46b67368f3298569470935 -size 3361 +oid sha256:ebf9e7a0873f1d8e7cf6efbb187e66d0abc984cae34edfa9c8558b4a09f7b350 +size 18553 diff --git a/docs/python/images/flask-tutorial/new-file-icon.png b/docs/python/images/flask-tutorial/new-file-icon.png index 17555a0219..9137853817 100644 --- a/docs/python/images/flask-tutorial/new-file-icon.png +++ b/docs/python/images/flask-tutorial/new-file-icon.png @@ -1,3 +1,3 @@ version https://git-lfs.github.com/spec/v1 -oid sha256:601a6c91e7f27b01d588722d4b030d0b21d36d5d077b3b10ff2fb30554db4732 -size 5155 +oid sha256:ab45cdb228ce64a8dcc702b5275499877e71365d59078d711a9cdd005cc90db1 +size 27223 diff --git a/docs/python/images/shared/command-palette.png b/docs/python/images/shared/command-palette.png index 9871c0215e..41bc441eba 100644 --- a/docs/python/images/shared/command-palette.png +++ b/docs/python/images/shared/command-palette.png @@ -1,3 +1,3 @@ version https://git-lfs.github.com/spec/v1 -oid sha256:3bcba73fa31c0801ef589bc07e5775bc3aad7384603c526991edc2958de94683 -size 6901 +oid sha256:e8b0efd17d192b8283eb8f3a0d1437e9e23f0fbeed0a1db6a6dd1940ffeb813f +size 127370 diff --git a/docs/python/images/shared/debug-panel-initial-view.png b/docs/python/images/shared/debug-panel-initial-view.png index 73bcf13d60..7790f8a170 100644 --- a/docs/python/images/shared/debug-panel-initial-view.png +++ b/docs/python/images/shared/debug-panel-initial-view.png @@ -1,3 +1,3 @@ version https://git-lfs.github.com/spec/v1 -oid sha256:6a174c568e7f9b6c0c4b234f41b6576dd9d24e033bb1275ce96a863514e25e72 -size 5562 +oid sha256:68365abdd0fca2a03616698353b5299f95f20f3cf0c673b738d2ac60f5da304e +size 64531 diff --git a/docs/python/tutorial-flask.md b/docs/python/tutorial-flask.md index cf973f4213..796ec7ea23 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: 10/27/2021 +DateApproved: 01/20/2023 MetaDescription: Python Flask tutorial showing IntelliSense, debugging, and code navigation support in Visual Studio Code, the best Python IDE. MetaSocialImage: images/tutorial/social.png --- @@ -27,62 +27,30 @@ To successfully complete this Flask tutorial, you must do the following (which a 1. Install the [Python extension](https://marketplace.visualstudio.com/items?itemName=ms-python.python). 1. Install a version of Python 3 (for which this tutorial is written). Options include: - - (All operating systems) A download from [python.org](https://www.python.org/downloads/); typically use the **Download Python 3.9.1** button that appears first on the page (or whatever is the latest version). + - (All operating systems) A download from [python.org](https://www.python.org/downloads/); typically use the **Download** button that appears first on the page. - (Linux) The built-in Python 3 installation works well, but to install other Python packages you must run `sudo apt install python3-pip` in the terminal. - - (macOS) An installation through [Homebrew](https://brew.sh/) on macOS using `brew install python3` (the system install of Python on macOS is not supported). + - (macOS) An installation through [Homebrew](https://brew.sh/) on macOS using `brew install python3`. - (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 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 the Flask tutorial -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 will 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. -1. On your file system, create a project folder for this tutorial, such as `hello_flask`. +1. On your file system, create a folder for this tutorial, such as `hello_flask`. -1. In that folder, use the following command (as appropriate to your computer) to create and activate a virtual environment named `.venv` based on your current interpreter: +1. Open this folder in VS Code by navigating to the folder in a terminal and running `code .`, or by running VS Code and using the **File** > **Open Folder** command. - ```bash - # Linux - sudo apt-get install python3-venv # If needed - python3 -m venv .venv - source .venv/bin/activate - - # macOS - python3 -m venv .venv - source .venv/bin/activate - - # Windows - py -3 -m venv .venv - .venv\scripts\activate - ``` - - > **Note**: Use a stock Python installation when running the above commands. If you use `python.exe` from an Anaconda installation, you see an error because the ensurepip module isn't available, and the environment is left in an unfinished state. - -1. Open the project folder in VS Code by running `code .`, or by running VS Code and using the **File** > **Open Folder** command. - -1. In VS Code, open the Command Palette (**View** > **Command Palette** or (`kb(workbench.action.showCommands)`)). Then select the **Python: Select Interpreter** command: +1. In VS Code, open the Command Palette (**View** > **Command Palette** or (`kb(workbench.action.showCommands)`)). Then select the **Python: Create Environment** command to create a virtual environment in your workspace. Select `venv` and then the Python environment you want to use to create it. + > **Note**: If you want to create an environment manually, or run into error in the environment creation process, visit the [Environments](/docs/python/environments.md#create-a-virtual-environment-in-the-terminal) page. - ![Flask tutorial: opening the Command Palette in VS Code](images/shared/command-palette.png) + ![Flask tutorial: opening the Command Palette in VS Code](images/flask-tutorial/command-palette.png) -1. The command presents a list of available interpreters that VS Code can locate automatically (your list will vary; if you don't see the desired interpreter, see [Configuring Python environments](/docs/python/environments.md)). From the list, select the virtual environment in your project folder that starts with `./.venv` or `.\.venv`: - - ![Flask tutorial: selecting the virtual environment for Python](images/shared/select-virtual-environment.png) - -1. Run [**Terminal: Create New Terminal**](/docs/terminal/basics.md) (`kb(workbench.action.terminal.new)`)) from the Command Palette, which creates a terminal and automatically activates the virtual environment by running its activation script. +1. After your virtual environment creation has been completed, run [**Terminal: Create New Terminal**](/docs/terminal/basics.md) (`kb(workbench.action.terminal.new)`)) from the Command Palette, which creates a terminal and automatically activates the virtual environment by running its activation script. > **Note**: On Windows, if your default terminal type is PowerShell, you may see an error that it cannot run activate.ps1 because running scripts is disabled on the system. The error provides a link for information on how to allow scripts. Otherwise, use **Terminal: Select Default Shell** to set "Command Prompt" or "Git Bash" as your default instead. -1. The selected environment appears on the right side of the VS Code status bar, and notice the **('.venv': venv)** indicator that tells you that you're using a virtual environment: - - ![Flask tutorial: selected environment showing in the VS Code status bar](images/shared/environment-in-status-bar.png) - -1. Update pip in the virtual environment by running the following command in the VS Code Terminal: - - ```bash - python -m pip install --upgrade pip - ``` - 1. Install Flask in the virtual environment by running the following command in the VS Code Terminal: ```bash @@ -200,7 +168,7 @@ Debugging gives you the opportunity to pause a running program on a particular l ![Flask tutorial: a breakpoint set on the first line of the hello_there function](images/flask-tutorial/debug-breakpoint-set.png) -1. Switch to **Run** view in VS Code (using the left-side activity bar or `kb(workbench.action.debug.start)`). You may see the message "To customize Run and Debug create a launch.json file". This means that you don't yet have a `launch.json` file containing debug configurations. VS Code can create that for you if you click on the **create a launch.json file** link: +1. Switch to the **Run and Debug** view in VS Code (using the left-side activity bar or `kb(workbench.view.debug)`). You may see the message "To customize Run and Debug create a launch.json file". This means that you don't yet have a `launch.json` file containing debug configurations. VS Code can create that for you if you click on the **create a launch.json file** link: ![Flask tutorial: initial view of the debug panel](images/shared/debug-panel-initial-view.png) @@ -258,7 +226,7 @@ Debugging gives you the opportunity to pause a running program on a particular l ![Flask tutorial: local variables and arguments in VS Code during debugging](images/flask-tutorial/debug-local-variables.png) -1. When a program is paused, the **Debug Console** panel (which is different from the "Python Debug Console" in the Terminal panel) lets you experiment with expressions and try out bits of code using the current state of the program. For example, once you've stepped over the line `now = datetime.now()`, you might experiment with different date/time formats. In the editor, select the code that reads `now.strftime("%A, %d %B, %Y at %X")`, then right-click and select **Debug: Evaluate** to send that code to the debug console, where it runs: +1. When a program is paused, the **Debug Console** panel (which is different from the "Python Debug Console" in the Terminal panel) lets you experiment with expressions and try out bits of code using the current state of the program. For example, once you've stepped over the line `now = datetime.now()`, you might experiment with different date/time formats. In the editor, select the code that reads `now.strftime("%A, %d %B, %Y at %X")`, then right-click and select **Evaluate in Debug Console** to send that code to the debug console, where it runs: ```bash now.strftime("%A, %d %B, %Y at %X") @@ -422,7 +390,7 @@ The following sections demonstrate both types of static files. ## Create multiple templates that extend a base template -Because most web apps have more than one page, and because those pages typically share many common elements, developers separate those common elements into a base page template that other page templates can then extend. (This is also called template inheritance.) +Because most web apps have more than one page, and because those pages typically share many common elements, developers separate those common elements into a base page template that other page templates can then extend (this is also called template inheritance.) Also, because you'll likely create many pages that extend the same template, it's helpful to create a code snippet in VS Code with which you can quickly initialize new page templates. A snippet helps you avoid tedious and error-prone copy-paste operations. @@ -434,7 +402,7 @@ A base page template in Flask contains all the shared parts of a set of pages, i The following steps demonstrate creating a base template. -1. In the `templates` folder, create a file named `layout.html` with the contents below, which contains blocks named "title" and "content". As you can see, the markup defines a simple nav bar structure with links to Home, About, and Contact pages, which you create in a later section. Each link again uses Flask's `url_for` tag to generate a link at runtime for the matching route. +1. In the `templates` folder, create a file named `layout.html` with the contents below, which contains blocks named "title" and "content". As you can see, the markup defines a simple nav bar structure with links to Home, About, and Contact pages, which you will create in a later section. Each link again uses Flask's `url_for` tag to generate a link at runtime for the matching route. ```html @@ -464,7 +432,7 @@ The following steps demonstrate creating a base template. ``` -1. Add the following styles to `static/site.css` below the existing "message" style, and save the file. (This walkthrough doesn't attempt to demonstrate responsive design; these styles simply generate a reasonably interesting result.) +1. Add the following styles to `static/site.css`, below the existing "message" style, and save the file. Note that this walkthrough doesn't attempt to demonstrate responsive design; these styles simply generate a reasonably interesting result. ```css .navbar { @@ -502,11 +470,11 @@ You can run the app at this point, but because you haven't made use of the base Because the three pages you create in the next section extend `layout.html`, it saves time to create a **code snippet** to initialize a new template file with the appropriate reference to the base template. A code snippet provides a consistent piece of code from a single source, which avoids errors that can creep in when using copy-paste from existing code. -1. In VS Code, select the **File** (Windows/Linux) or **Code** (macOS), menu, then select **Preferences** > **User snippets**. +1. In VS Code, select **File** (**Code** on macOS) > **Preferences** > **Configure User Snippets**. -1. In the list that appears, select **html**. (The option may appear as "html.json" in the **Existing Snippets** section of the list if you've created snippets previously.) +1. In the list that appears, select **html**. The option may appear as "html.json" in the **Existing Snippets** section of the list if you've created snippets previously. -1. After VS code opens `html.json`, add the following entry within the existing curly braces (the explanatory comments, not shown here, describe details such as how the `$0` line indicates where VS Code places the cursor after inserting a snippet): +1. After VS Code opens `html.json`, add the following entry within the existing curly braces (the explanatory comments, not shown here, describe details such as how the `$0` line indicates where VS Code places the cursor after inserting a snippet): ```json "Flask Tutorial: template extending layout.html": { @@ -636,16 +604,6 @@ Throughout this Flask tutorial, all the app code is contained in a single `app.p return app.send_static_file("data.json") ``` -1. Optional: Right-click in the editor and select the **Sort Imports** command, which consolidates imports from identical modules, removes unused imports, and sorts your import statements. Using the command on the code above in `views.py` changes the imports as follows (you can remove the extra lines, of course): - - ```python - from datetime import datetime - - from flask import Flask, render_template - - from . import app - ``` - 1. In the `hello_app` folder, create a file `__init__.py` with the following contents: ```python