Editor Integration

pycmdcheck provides an LSP (Language Server Protocol) server for integration with code editors. This enables real-time diagnostics as you work on your Python packages.

Installation

Install pycmdcheck with LSP support:

pip install pycmdcheck[lsp]
uv pip install pycmdcheck[lsp]
pipx install pycmdcheck[lsp]

Verify the installation:

pycmdcheck-lsp --help

VS Code

Using the Extension

  1. Install the pycmdcheck extension from the VS Code marketplace
  2. Open a Python project with a pyproject.toml
  3. Diagnostics appear automatically when you open or save files

Manual Setup

If not using the extension, configure VS Code manually:

  1. Install pylsp or similar
  2. Add pycmdcheck as a plugin

Extension Settings

Setting Type Default Description
pycmdcheck.enable boolean true Enable pycmdcheck diagnostics
pycmdcheck.pythonPath string "" Path to Python executable
pycmdcheck.skipChecks array [] Check IDs to skip
pycmdcheck.skipGroups array [] Check groups to skip
pycmdcheck.validateOnOpen boolean true Validate on file open
pycmdcheck.validateOnSave boolean true Validate on file save

Neovim

Using nvim-lspconfig

Add to your Neovim configuration:

-- lua/plugins/lspconfig.lua or similar
local lspconfig = require('lspconfig')
local configs = require('lspconfig.configs')

-- Define the pycmdcheck server
if not configs.pycmdcheck then
  configs.pycmdcheck = {
    default_config = {
      cmd = { 'pycmdcheck-lsp' },
      filetypes = { 'python', 'toml' },
      root_dir = lspconfig.util.root_pattern('pyproject.toml'),
      settings = {},
    },
  }
end

-- Enable the server
lspconfig.pycmdcheck.setup({
  on_attach = function(client, bufnr)
    -- Your on_attach configuration
  end,
})

Using Mason

If you use mason.nvim:

-- After pycmdcheck is added to Mason registry
require('mason-lspconfig').setup({
  ensure_installed = { 'pycmdcheck' },
})

Emacs

Using lsp-mode

Add to your Emacs configuration:

;; In your init.el or .emacs
(with-eval-after-load 'lsp-mode
  (add-to-list 'lsp-language-id-configuration
    '(python-mode . "python"))

  (lsp-register-client
    (make-lsp-client
      :new-connection (lsp-stdio-connection '("pycmdcheck-lsp"))
      :activation-fn (lsp-activate-on "python" "toml")
      :server-id 'pycmdcheck
      :priority -1)))  ; Lower priority than pyright/pylsp

Using eglot

For Emacs 29+ with built-in eglot:

(with-eval-after-load 'eglot
  (add-to-list 'eglot-server-programs
    '((python-mode python-ts-mode) . ("pycmdcheck-lsp"))))

Helix

Add to ~/.config/helix/languages.toml:

[[language]]
name = "python"
language-servers = ["pylsp", "pycmdcheck"]

[language-server.pycmdcheck]
command = "pycmdcheck-lsp"

Sublime Text

Using LSP package:

  1. Install the LSP package via Package Control
  2. Add to LSP settings (Preferences > Package Settings > LSP > Settings):
{
  "clients": {
    "pycmdcheck": {
      "enabled": true,
      "command": ["pycmdcheck-lsp"],
      "selector": "source.python | source.toml"
    }
  }
}

How It Works

The pycmdcheck LSP server:

  1. Watches files: Monitors Python and TOML files in your project
  2. Finds project root: Locates pyproject.toml to identify the package
  3. Runs checks: Executes pycmdcheck on file open and save
  4. Reports diagnostics: Converts results to LSP diagnostics

Diagnostic Severity Mapping

pycmdcheck Severity LSP Severity Editor Display
ERROR Error (1) Red squiggle
WARNING Warning (2) Yellow squiggle
NOTE Information (3) Blue squiggle

Performance

The LSP server runs checks on demand (file open/save), not continuously. For large projects, you may notice a brief delay while checks run.

To improve performance:

  • Skip expensive checks in your editor configuration
  • Use tool.pycmdcheck.skip in pyproject.toml
  • Consider using profiles for different contexts

Troubleshooting

Server not starting

  1. Verify pycmdcheck-lsp is installed: which pycmdcheck-lsp
  2. Check it runs manually: pycmdcheck-lsp
  3. Check editor logs for error messages

No diagnostics appearing

  1. Ensure the file is in a project with pyproject.toml
  2. Check that pycmdcheck finds issues: pycmdcheck /path/to/project
  3. Verify the LSP server is connected (editor status bar)

Wrong Python interpreter

If using virtual environments:

  1. Activate the environment before starting the editor
  2. Or set the Python path explicitly in editor settings
  3. Or install pycmdcheck globally with pipx

Diagnostics on wrong lines

Some checks report project-level issues (missing files) on line 1 of pyproject.toml. This is expected behavior - click the diagnostic to see details.

API

The LSP server is implemented in pycmdcheck.lsp.server:

from pycmdcheck.lsp import PycmdcheckLanguageServer

# Create server instance
server = PycmdcheckLanguageServer()

# Start in stdio mode (for editor integration)
server.start_io()

For custom integrations, you can use the helper functions:

from pycmdcheck.lsp.server import (
    find_project_root,
    results_to_diagnostics,
    uri_to_path,
    path_to_uri,
)