04 - Advanced vscode for Python Developers

Preliminaries

Shortcuts

You can specify conditions to when a command should be run. Therefore, I can have the same key mapping that executes different functions depending of these conditions.

python.createTerminal CMD+T editorLangId == 'python'

Conditional Operators

Here it is a list of available conditional operators.

VS Code Jargon

Activity Bar: The main navigation tool which is located on the left-hand site of VSCode by default. The acitivity bar is made of several views:
Explorer View: To explore and search for files.
Source Control View: Commits, Branches ...
Search View.
Run and Debug View.
Extensions View.

Hint

You cand drag a panel that is inside the view to the activity bar to create a permanent shortcut to it.

Setting up your terminal

Oh-my-posh

This is a project that allows you to create themes for your terminal prompt. The idea is to customize your prompt with information you care and using a style that pleases you.

There are several predefined themes available. A list can be checked here.

Nerd Fonts

I was having a problem with the Hack font that I patched myself with glyphs. Not all the icons were being displayed. I realized that the patched font was not even being recognized by the system. That's why it was not working.

A nice thing to do is use a patched font such that your terminal can display icons. You can see some examples of them here

VSCode settings

For each configuration file, VSCode offers two levels of granularity.

Workspace. Commonly located at the project folder under the directory .vscode.
User. Commonly located at ~/.config/Code

settings.json

General settings. If unsure where to define a setting, look it here first.

Use the macro ${env:HOME} in settings.json to access your home folder.

launch.json

Holds the profiles your project will execute from the Run and Debug menu

tasks.json

Any additional tasks to execute, such as build steps.

Predefined variables

Predefined variable	Meaning
`${env:VARIABLE}`	Any environment variable
`${workspaceFolder}`	The path of the folder opened in VS Code
`{file}`	The currently opened file
`${cwd}`	The task runner's current working directory on startup
`${pathSeparator}`	The character used by the OS to separate path components

These variables come in handy when you need environment agnostic settings. For example, those that are shared by a team and are pushed to the repository. A list of them can be found here.

Lint and Formatting

Execute formatting when you save the file.
It can even organize the imports by alphabetica order and context (standard library, modules, external modules).
You can set

Testing in VSCode

How this pipeline plays with tox and pyproject.toml? The article mentioned pytest.ini but this is not standard anymore.

Real Package Project Setting VSCode

1. Setup a dev venv

In the dev venv you are going to install the development packages such as formatters, linters and testing packages. For example:

Formatting: black
General linter: pylint
Security linter: bandit
Type checker: mypy
Testing: pytest
Test coverage: pytest-cov

2. Setup your vscode workspace settings

You need to setup some paths in order to vscode to serch the tools on your dev venv. The idea is that you are also going to install your package in the dev venv, therefore the linter and test tools will have access to your package imports.

{
  "python.testing.pytestArgs": [
    "test"
  ],
  "python.testing.unittestEnabled": false,
  "python.testing.pytestEnabled": true,
  "python.linting.banditPath": "${workspaceFolder}/.venv/bin/bandit",
  "python.linting.pylintEnabled": true,
  "python.linting.pylintPath": "${workspaceFolder}/.venv/bin/pylint",
  "python.linting.mypyPath": "${workspaceFolder}/.venv/bin/mypy",
  "python.linting.lintOnSave": true,
  "python.formatting.blackPath": "${workspaceFolder}/.venv/bin/black",
  "python.formatting.provider": "black",
}

3. Setup some scripts and the vscode tasks.json

I use tasks.json to invoke some tox tasks from the vscode interface. In particular, I can use the task explorer extension.

{
  // See https://go.microsoft.com/fwlink/?LinkId=733558
  // for the documentation about the tasks.json format
  "version": "2.0.0",
  "tasks": [
    {
      "type": "shell",
      "command": "dev/clean/clean.sh",
      "args": [],
      "isBackground": false,
      "options": {"cwd": "${workspaceFolder}"},
      "label": "Clean",
      "group": {
          "kind": "test",
          "isDefault": true
      }
    },
    {
      "type": "shell",
      "command": "./dev/extract-sdist/extract-sdist.sh",
      "args": [],
      "isBackground": false,
      "options": {"cwd": "${workspaceFolder}"},
      "label": "Export package",
      "dependsOn":["Pre-packaging suite"],
      "group": {
          "kind": "test",
          "isDefault": true
      }
    },
    {
      "type": "shell",
      "command": "tox",
      "args": ["-e","docsdev"],
      "isBackground": false,
      "options": {"cwd": "${workspaceFolder}"},
      "label": "Build documentation (dev)",
      "group": {
          "kind": "test",
          "isDefault": true
      }
    },
    {
      "type": "shell",
      "command": "tox",
      "args": ["-e","docs"],
      "isBackground": false,
      "options": {"cwd": "${workspaceFolder}"},
      "label": "Build documentation",
      "group": {
          "kind": "test",
          "isDefault": true
      }
    },
    {
      "type": "shell",
      "command": "tox",
      "args": ["-e","testenv"],
      "isBackground": false,
      "options": {"cwd": "${workspaceFolder}"},
      "label": "Run tests",
      "group": {
          "kind": "test",
          "isDefault": true
      }
    },
    {
      "type": "shell",
      "command": "tox",
      "args": ["-e","format, typecheck, testenv, docs"],
      "isBackground": false,
      "options": {"cwd": "${workspaceFolder}"},
      "label": "Pre-packaging suite",
      "dependsOn":"Clean",
      "group": {
          "kind": "test",
          "isDefault": true
      }
    }
  ]
}

Development with container in VSCode

This is interesting, but I don't have any pratical case to apply it right now.

Exercise

What is a task in VSCode? You can access them by clicking the + button in the integrated terminal view.
Setup a default user and workspace settings and push it to the config-templates repository.
Rewrite these notes in the form of a vscode configuration file to illustrate the different sections explored here.
Create a snippet to create a pyproject.toml from a template.
It is not clear how to setup the pieces in VSCode in order to have a proper workflow. I think it is useful to have a development virtual env in which vscode will be based to. But I would like to separate developing dependencies such as black from the project dependencies. How to accomplish that?