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:
   ```bash
   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:

```bash
# 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:
```bash
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`:

```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`:

```json
{
  "typeCheckingMode": "strict"
}
```

Or in `pyproject.toml`:

```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:
   ```python
   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`:

```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:

```ini
[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`:
   ```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