Latent Config Lab for VS Code
Editor support for the config files of Latent Config Lab:
the YAML and JSON files whose nodes name Python classes, such as
<OBJECT:my_project.configs.DatabaseConfig>:. The extension checks each file the way the
library reads it, completes class paths, field names and links, explains fields on hover, and
jumps from a class path or a field to its Python source.
Everything it knows comes from your own code. The extension starts a language server in your
project's Python environment, and that server imports the config classes a file names, so the
fields, defaults and errors it shows are those of the classes you run. The extension itself
holds no knowledge of the syntax: it finds the interpreter, starts the server and colours the
tags.
What it does
The extension works on .yaml, .yml and .json files that sit under a directory named
configs or that contain a config node key such as <BASIC:...>. It leaves every other YAML
and JSON file alone.
- Diagnostics. Each file is read with the library's
ConfigReader, as the validate
command reads it, while you type. An error is placed on the key or value it concerns: a class
path that cannot be imported, a class of the wrong kind, an unknown or missing field, a value
of the wrong type, a link to a file that does not exist, a <COMMAND:...> node below the
root, or invalid YAML. An error inside a linked file is shown on the link. A file that
latent-config-lab validate accepts shows no diagnostic.
- Completion. After
<, the node kinds. Inside <BASIC:, <OBJECT: or <COMMAND:, the
config classes of that kind defined in the workspace and the class paths its config files
already use. Inside a config node, the fields its class declares and the file does not set
yet, each with its type, default and description. After a field name, true and false,
the values of an enum or a Literal, and null for an optional field. Inside <LINK:, the
config files under the nearest configs directory. After <TARGET>:, the targets the
workspace uses with the same config class and the class's default target.
- Hover. On a class path, the docstring of the class. On a field, its description, type
and default. On a link, the file it resolves to. On
${NAME}, whether the variable is set,
never its value.
- Go to definition. From a class path or a
<TARGET> to the class in its Python file,
from a field name to the line declaring the field, and from a link to the linked file. Links
are also clickable.
- Add missing fields. On a config node key, the code action Add missing fields with
their defaults writes every field the node does not set with its default value, indented
like the rest of the file. A required field is written empty, with a
# required comment,
so the file stays invalid until you fill it in.
- Colours. The node kind, the class path,
<TARGET>, link paths and ${...} variables
get their own colours, on top of the YAML and JSON grammars of VS Code.
The server picks up changes to the Python files of the workspace by itself: it re-imports
the classes and checks the open files again.
Install
You need VS Code 1.93 or later, and a project whose environment has Latent Config Lab with
its language-server extra.
Add the extra to your project. With uv:
uv add "latent-config-lab[language-server]" --upgrade-package latent-config-lab
uv add keeps the source your project already uses for the library, such as a Git
repository, and --upgrade-package lets it move to a version that has the extra. The extra
installs pygls and overrides; the library itself does not need them. Check it with
uv run python -m latent_config_lab.language_server --help, which prints the usage of the
server.
Install the extension from the Visual Studio Marketplace: search for Latent Config Lab
in the Extensions view, or run:
code --install-extension Latent-Lab.latent-config-lab
Open your project. The extension starts when the workspace holds a configs directory
with YAML or JSON files. In another workspace, run
Latent Config Lab: Restart Language Server to start it.
Which Python it uses
The server must run in the interpreter of your project, because it imports your classes. The
extension takes the first of these that exists:
- the
latentConfigLab.pythonPath setting;
- the interpreter selected in the Python extension, when that extension is installed;
.venv/bin/python in the workspace folder, or .venv\Scripts\python.exe on Windows.
It starts the server in the workspace folder, so relative paths in your configs and the .env
file resolve as they do when you run your CLI from the project root. In a workspace with
several folders, the server uses the interpreter of the first folder.
Settings
| Setting |
Default |
Effect |
latentConfigLab.pythonPath |
empty |
Interpreter that runs the language server. Accepts ${workspaceFolder}. Empty means the Python extension's interpreter, then .venv in the workspace folder. |
latentConfigLab.trace.server |
off |
Logs the messages between VS Code and the server in the Latent Config Lab output channel: messages for their names, verbose for their content. |
The command Latent Config Lab: Restart Language Server stops the server, finds the
interpreter again and starts a new one. Run it after installing the extra or changing the
interpreter.
Troubleshooting
The server writes its log to the Latent Config Lab output channel (View > Output), which
is the first place to look when something is off.
| What you see |
What to do |
| No Python interpreter found to run the language server. |
Set latentConfigLab.pythonPath, select an interpreter in the Python extension, or create the environment with uv sync so that .venv exists. Then restart the server. |
The interpreter ... cannot run the language server and a uv add command |
The extra is missing from that environment. Run the command shown, then restart the server. The message appears once; the extension does not retry on its own. |
| Diagnostics or completions about another syntax, or every config file flagged |
Another extension claims files named *config*.yaml. Disable it in the workspaces that use this syntax: in the Extensions view, open its menu and choose Disable (Workspace). |
| A class path is reported as not importable, but the CLI imports it |
The server runs in another interpreter than the CLI. Check which one the output channel names, and point latentConfigLab.pythonPath at the right one. |
${NAME} is reported as unset, although it is set in your shell |
VS Code started from the Dock or a launcher does not inherit the variables of your shell. Put the variable in the .env file of the project, which the reader loads, or start VS Code with code . from the shell. |
| Completions of fields or hovers are missing right after opening a project |
The server imports the classes of a file the first time it needs them, which can take several seconds when they import a large framework. They appear once the import is done. |
| |