Improved flow
This commit is contained in:
Morten Olsen
363
docs/guides/python-workflow.md
Normal file
363
docs/guides/python-workflow.md
Normal file
@@ -0,0 +1,363 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user