HydraLance

HydraLance is a VS Code extension that provides intelligent language support for Hydra configuration files. It bridges the gap between YAML configuration files and Python code by leveraging Pylance to provide code intelligence for _target_ references, parameter completion, and indexes .yaml files to resolve Hydra interpolations.

If you find HydraLance useful, please consider giving it a ⭐ on GitHub!

Features

1. Go-to-Definition for _target_ Values

Navigate directly from YAML configurations to Python source code:

model:
  _target_: torch.nn.Linear  # Ctrl+Click to go to PyTorch source
  in_features: 128
  out_features: 64

Pro tip: Use Ctrl+Shift+F10 to peek at the definition without leaving your current context.

2. Auto-completion for _target_ Values

Get intelligent suggestions for Python modules, classes, and functions:

model:
  _target_: torch.nn.  # Auto-complete shows Linear, Conv2d, etc.

3. Parameter Auto-completion

Get intelligent parameter suggestions based on the target class/function signature:

model:
  _target_: torch.nn.Linear
  # Type here to get completions for: in_features, out_features, bias
  
optimizer:
  _target_: torch.optim.Adam
  # Type here to get completions for: lr, betas, eps, weight_decay, amsgrad, ...

5. Defaults List Navigation

Navigate to referenced config files in Hydra defaults lists:

defaults:
  - default              # Ctrl+Click to go to .default.yaml
  - dataset: imagenet    # Ctrl+Click to open ./dataset/imagenet.yaml

Resolved filenames are displayed on hover.

4. Interpolation Resolution

Navigate between Hydra config interpolations across your entire project:

# In config/dataset/imagenet.yaml
name: imagenet_1k
classes: 1000

# In config/experiment/main.yaml  
experiment:
  dataset_name: "${dataset.name}"     # Ctrl+Click to go to definition(s)

Features:

• Cross-file resolution: Find interpolation targets across your entire workspace
• Smart filtering: Multiple match filtering options (all, top matches, perfect matches)
• Workspace isolation: Keep matches within workspace boundaries
• Level-based ranking: Most specific matches shown first

6. Error Detection and Linting

Invalid _target_ references are highlighted with error diagnostics:

model:
  _target_: torch.nn.InvalidClass  # Shows error: cannot be resolved

How It Works

HydraLance uses multiple approaches:

For _target_ Features:

1. Shadow Documents: Creates virtual Python files containing import statements derived from _target_ values
2. Pylance Integration: Leverages Pylance's language server capabilities for Python symbol resolution
3. Parameter Extraction: Uses signature help to get parameter information from Python functions/classes

For Interpolation Resolution:

1. Workspace Indexing: Scans and indexes all YAML files in your workspace
2. Reverse Path Matching: Builds a reverse lookup index for efficient interpolation resolution
3. Logical Path Construction: Maps file paths and YAML keys to Hydra's logical namespace

Requirements

• Pylance Extension: HydraLance requires the Pylance extension to function
• Python Environment: A configured Python environment with the packages you're referencing in your configurations

Installation

1. Install the Pylance extension (you probably already have it)
2. Install HydraLance from the VS Code marketplace
3. Open a YAML file with Hydra configurations

The extension will automatically:

• Check for Pylance availability
• Wait for Pylance to be ready
• Index your YAML files for interpolation resolution
• Create a hydralance/ folder for temporary files
• Offer to add this folder to your .gitignore

Settings

Core Settings

• hydralance.hideHelperFolder (boolean, default: true)
  Hide the hydralance folder from the VS Code explorer

• hydralance.showOutputOnError (boolean, default: false)
  Automatically open the HydraLance output channel only when you explicitly opt in to seeing logs as soon as an internal error occurs

Interpolation Resolution Settings

• hydralance.excludePatterns (array, default: [".venv/**"])
  Glob patterns to exclude from YAML file indexing for interpolation resolution

• hydralance.matchFilter (enum, default: "top matches only")
  Controls which interpolation matches are shown:

  • "all" - Shows all matches found
  • "top matches only" - Shows only the highest level matches found
  • "perfect matches only" - Shows only matches that exactly match the interpolation depth

• hydralance.isolateWorkspaceFolders (boolean, default: true)
  When enabled, interpolation resolution only considers files within the same workspace folder

Commands

Access these commands via the Command Palette (Ctrl+Shift+P):

• HydraLance: Generate Diagnostic Info - Generate diagnostic information for troubleshooting
• HydraLance: Show Logs - Show extension logs in the output panel
• HydraLance: Refresh YAML Index - Refresh the YAML file index

Notice

HydraLance is an independent project and is not affiliated with or endorsed by the Hydra project or its maintainers. Use at your own discretion.