nvim/docs/guides/python-workflow.md

Python Development Workflow

This guide covers Python development in Neovim with virtual environment support, testing, and debugging.

Overview

Your config includes:

• LSP: Pyright (via LazyVim python extra)
• Linting: Ruff or pylint
• Testing: pytest via neotest
• Debugging: debugpy via DAP
• Virtual Environments: venv-selector

Getting Started

Project Setup

1. Open your Python project:

   nvim /path/to/project
   

2. Select virtual environment:

   <leader>cv    Open venv selector
   

3. The LSP will restart with the selected venv.

Virtual Environment Management

Selecting a Virtual Environment

<leader>cv    Open venv selector

This searches for:

• .venv/ in project
• venv/ in project
• Poetry environments
• Conda environments
• pyenv environments

Creating a Virtual Environment

If you don't have one:

# In terminal or with <leader>ft (float term)
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Then <leader>cv to select it.

LSP Features

Navigation

Key	Action
gd	Go to definition
gr	Go to references
gI	Go to implementation
K	Hover documentation

Code Actions

Key	Action
<leader>ca	Code actions
<leader>cr	Rename symbol
<leader>cf	Format document

Diagnostics

Key	Action
<leader>cd	Line diagnostics
]d / [d	Next/prev diagnostic
<leader>xx	Toggle trouble

Testing with pytest

Running Tests

Key	Action
<leader>tt	Run test at cursor
<leader>tf	Run file tests
<leader>ta	Run all tests
<leader>tl	Re-run last test

Test Discovery

pytest finds tests in:

• test_*.py files
• *_test.py files
• Functions named test_*
• Classes named Test*

Test Output

<leader>ts    Toggle test summary
<leader>to    Show test output
<leader>tO    Toggle output panel
]t / [t       Jump to next/prev failed test

Debugging Tests

<leader>td    Debug test at cursor

This starts debugpy and allows stepping through test code.

Debugging

Setup

debugpy should be installed in your virtual environment:

pip install debugpy

Setting Breakpoints

Key	Action
<leader>db	Toggle breakpoint
<leader>dB	Conditional breakpoint

Running Debugger

Key	Action
<leader>dc	Continue/Start
<leader>di	Step into
<leader>do	Step over
<leader>dO	Step out
<leader>dt	Terminate

DAP UI

<leader>du    Toggle DAP UI
<leader>de    Evaluate expression

launch.json

For custom configurations, create .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Python: Current File",
      "type": "python",
      "request": "launch",
      "program": "${file}",
      "console": "integratedTerminal"
    },
    {
      "name": "Python: Flask",
      "type": "python",
      "request": "launch",
      "module": "flask",
      "args": ["run", "--debug"],
      "env": {
        "FLASK_APP": "app.py"
      }
    },
    {
      "name": "Python: FastAPI",
      "type": "python",
      "request": "launch",
      "module": "uvicorn",
      "args": ["main:app", "--reload"]
    }
  ]
}

Code Quality

Formatting

<leader>cf    Format with black/ruff

Import Sorting

If using isort or ruff:

<leader>ca    Code actions → Organize imports

Type Checking

Pyright provides type checking. For strict mode, add pyrightconfig.json:

{
  "typeCheckingMode": "strict"
}

Or in pyproject.toml:

[tool.pyright]
typeCheckingMode = "strict"

AI Assistance

Key	Action
<leader>ka	Ask opencode
<leader>ke	Explain code
<leader>kR	Refactor selection
<leader>kt	Generate tests
<leader>kd	Generate docstrings

Generate Docstrings

1. Place cursor on function
2. <leader>kd (or use neogen: <leader>cn)
3. Review and adjust

Common Workflows

Starting New Feature

1. <leader>cv - Ensure correct venv
2. Create/open file
3. <leader>H - Mark with harpoon
4. Write code with LSP assistance
5. <leader>tt - Test as you go

Debugging an Issue

1. <leader>xx - View all diagnostics
2. Navigate to issue
3. <leader>db - Set breakpoint
4. <leader>dc - Start debugger
5. Step through code

Adding Tests

1. Create test_*.py file
2. Write test function:

   def test_something():
       assert my_function() == expected
   

3. <leader>tt - Run test
4. <leader>to - View output

Project Configuration

pyproject.toml

Modern Python projects use pyproject.toml:

[project]
name = "myproject"
version = "0.1.0"
requires-python = ">=3.11"

[tool.pytest.ini_options]
testpaths = ["tests"]
python_files = "test_*.py"

[tool.ruff]
line-length = 88
select = ["E", "F", "I"]

[tool.pyright]
venvPath = "."
venv = ".venv"

pytest.ini

For pytest configuration:

[pytest]
testpaths = tests
python_files = test_*.py
addopts = -v --tb=short

Tips

Quick REPL

<leader>ft    Open floating terminal
python        Start Python REPL

Run Current File

:!python %    Run current file

Or use executor:

<leader>Brs   Set command: python %
<leader>Brr   Run it

Documentation

• K on any symbol shows docstring
• Works with standard library and packages

Find TODOs

<leader>xt    Show all TODO/FIXME comments

Troubleshooting

LSP Not Finding Imports

1. Check venv is selected: <leader>cv
2. :LspInfo - Verify pyright is attached
3. Check pyrightconfig.json or pyproject.toml

Wrong Python Version

1. <leader>cv - Select correct venv
2. Or set explicitly in pyrightconfig.json:

   {
     "pythonVersion": "3.11"
   }
   

Tests Not Found

1. Check file naming: test_*.py
2. Check function naming: test_*
3. Verify pytest is installed in venv

Debugger Not Starting

1. Install debugpy: pip install debugpy
2. Check :DapShowLog for errors
3. Verify venv is active