Skip to content

Commit 5d27eb5

Browse files
wesmwesm
authored
Claude Code: Seed .claude instructions for working on the Python extension kernel (#9180)
Without these, when you ask Claude to help with the Python extension (and the positron module in particular), it has to do some work to discover the right approach to run the unit tests etc., and it can go down dark alleys. These instructions can surely be made much better. Adds helper scripts for testing whole codebase style / formatting.
1 parent bca395e commit 5d27eb5

File tree

3 files changed

+242
-0
lines changed

3 files changed

+242
-0
lines changed

‎.claude/positron-python.md

Lines changed: 183 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,183 @@
1+
# Positron Python Extension Development
2+
3+
## Overview
4+
The Positron Python extension provides comprehensive Python language support and advanced data science features for Positron IDE, including interactive data exploration, kernel management, debugging, and environment detection. This extension is a fork of Microsoft's Python extension, enhanced for data science workflows.
5+
6+
## Project Structure
7+
```
8+
extensions/positron-python/
9+
├── src/ # TypeScript extension code
10+
├── python_files/ # Python runtime components
11+
│ ├── posit/ # Positron-specific Python modules
12+
│ │ ├── positron/ # Core Positron Python functionality
13+
│ │ │ └── tests/ # Python unit tests for Positron modules
14+
│ │ ├── pyproject.toml # Python project configuration
15+
│ │ └── test-requirements.txt # Python test dependencies
16+
│ └── lib/ # Vendored Python dependencies
17+
├── build/ # Build configurations and CI helpers
18+
├── package.json # Node.js extension manifest
19+
└── requirements.txt # Base Python dependencies
20+
```
21+
22+
## Development Environment Setup
23+
24+
We assume for now that the user is responsible for setting up their development environment.
25+
26+
## Claude Code Configuration
27+
28+
### Recommended Bash Command Permissions
29+
30+
When working with Claude Code on the Python extension, consider allowing these commands for efficient development:
31+
32+
```bash
33+
# Python testing (from extensions/positron-python/python_files/posit)
34+
cd extensions/positron-python/python_files/posit && python -m pytest*
35+
36+
# TypeScript extension testing (from root directory)
37+
npm run test-extension -- -l positron-python*
38+
39+
# Code quality commands (only for posit directory)
40+
cd extensions/positron-python/python_files/posit && ruff check*
41+
cd extensions/positron-python/python_files/posit && ruff format*
42+
cd extensions/positron-python/python_files/posit && pyright positron/*
43+
44+
# Helper scripts (from extensions/positron-python)
45+
cd extensions/positron-python && ./scripts/check-python-quality.sh
46+
cd extensions/positron-python && ./scripts/fix-python-format.sh
47+
```
48+
49+
These permissions enable Claude to run tests, check code quality, and apply formatting fixes without requiring manual approval for each command.
50+
51+
## Testing Framework
52+
53+
### Python Testing
54+
**CRITICAL**: All Python tests MUST be run from `extensions/positron-python/python_files/posit` directory:
55+
56+
```bash
57+
# ALWAYS start from project root, then navigate to the correct directory
58+
cd extensions/positron-python/python_files/posit
59+
60+
# Run all Positron Python tests
61+
python -m pytest
62+
63+
# Run specific test modules
64+
python -m pytest positron/tests/test_data_explorer.py
65+
66+
# Run with coverage
67+
python -m pytest --cov=positron --cov-report=term-missing
68+
69+
# Run specific test with verbose output
70+
python -m pytest positron/tests/test_data_explorer.py::test_specific_function -v
71+
```
72+
73+
### TypeScript Extension Testing
74+
**Run from project root directory**:
75+
76+
```bash
77+
# Test the positron-python extension TypeScript code
78+
npm run test-extension -- -l positron-python
79+
80+
# With grep pattern for specific tests
81+
npm run test-extension -- -l positron-python --grep "test pattern"
82+
```
83+
84+
### Test Requirements
85+
- **Module Resolution**: Always run pytest from `python_files/posit` directory
86+
- **No Main Blocks**: Never use `if __name__ == "__main__"` in test files
87+
88+
## Code Quality & Linting
89+
90+
### Automatic Formatting
91+
Code formatting is handled automatically via Claude Code hooks using ruff format.
92+
93+
### Helper Scripts
94+
95+
```bash
96+
# Run all Python quality checks (linting + type checking)
97+
cd extensions/positron-python
98+
./scripts/check-python-quality.sh
99+
100+
# Fix formatting and safe linting issues
101+
./scripts/fix-python-format.sh
102+
```
103+
104+
### Manual Quality Checks
105+
106+
```bash
107+
# Python linting (from python_files/posit/)
108+
cd extensions/positron-python/python_files/posit
109+
ruff check .
110+
ruff format --check
111+
112+
# Type checking with Pyright (from python_files/posit/)
113+
pyright positron/
114+
```
115+
116+
### Tool Versions
117+
118+
- **Pyright**: Version 1.1.308 (matches CI)
119+
- **Ruff**: Latest version
120+
121+
## Development Workflows
122+
123+
### Adding New Features
124+
1. **Plan**: Use TodoWrite tool for complex multi-step tasks
125+
2. **Develop**: Follow existing code patterns and conventions
126+
3. **Test**: Write comprehensive tests covering edge cases
127+
4. **Lint**: Code passes ruff and pyright checks
128+
129+
## Dependencies & Compatibility
130+
131+
### Core Dependencies
132+
- **Required**: Python 3.9+, core data science libraries
133+
- **Testing**: pytest, pytest-asyncio, pytest-mock, syrupy
134+
- **Optional**: Various data science packages for enhanced functionality
135+
136+
### Version Support
137+
- **Python**: 3.9, 3.10, 3.11, 3.12, 3.13
138+
- **Platforms**: Windows, macOS, Linux
139+
- **Data Libraries**: Latest stable versions with fallbacks for older Python
140+
141+
## Common Development Patterns
142+
143+
### Error Handling
144+
```python
145+
# Graceful degradation for missing dependencies
146+
try:
147+
import optional_library
148+
HAS_OPTIONAL = True
149+
except ImportError:
150+
HAS_OPTIONAL = False
151+
152+
def enhanced_function(data):
153+
if HAS_OPTIONAL:
154+
return optional_library.process(data)
155+
else:
156+
return fallback_implementation(data)
157+
```
158+
159+
### Testing Best Practices
160+
```python
161+
import pytest
162+
163+
@pytest.mark.parametrize("input_data,expected", [
164+
# Regular cases
165+
([1, 2, 3, 4, 5], "expected_result_1"),
166+
([1.1, 2.2, 3.3], "expected_result_2"),
167+
# Edge cases
168+
([], "empty_result"),
169+
([1], "single_item_result"),
170+
])
171+
def test_function_with_various_inputs(input_data, expected):
172+
"""Test function with different input types and edge cases."""
173+
result = function_under_test(input_data)
174+
assert result == expected
175+
```
176+
177+
## Troubleshooting
178+
179+
### Common Issues
180+
1. **Import errors**: Always run pytest from `python_files/posit` directory
181+
2. **Module not found**: Check that your Python environment has required packages
182+
3. **Test failures**: Ensure test requirements are installed
183+
4. **Type errors**: Run pyright to catch type issues early

‎extensions/positron-python/scripts/check-python-quality.sh

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
#!/bin/bash
2+
# Helper script for running Python linting and type checking on Positron-specific code
3+
# Run from extensions/positron-python directory
4+
# Only checks the posit/ directory (Positron-specific code)
5+
6+
set -e
7+
8+
echo "Running Python code quality checks on posit/ directory..."
9+
echo
10+
11+
# Navigate to posit directory where Positron-specific Python code lives
12+
cd python_files/posit
13+
14+
echo "1. Running ruff linter..."
15+
ruff check .
16+
echo "✓ Ruff linting passed"
17+
echo
18+
19+
echo "2. Running ruff format check..."
20+
ruff format --check .
21+
echo "✓ Ruff format check passed"
22+
echo
23+
24+
echo "3. Running pyright type checker on posit directory only..."
25+
pyright positron/
26+
echo "✓ Pyright type checking passed"
27+
echo
28+
29+
echo "All Python quality checks passed successfully for posit/ directory!"

‎extensions/positron-python/scripts/fix-python-format.sh

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
#!/bin/bash
2+
# Helper script for fixing Python formatting and safe linting issues in Positron-specific code
3+
# Run from extensions/positron-python directory
4+
# Only formats the posit/ directory (Positron-specific code)
5+
6+
set -e
7+
8+
echo "Fixing Python code formatting and linting issues in posit/ directory..."
9+
echo
10+
11+
# Navigate to posit directory where Positron-specific Python code lives
12+
cd python_files/posit
13+
14+
echo "1. Running ruff format..."
15+
ruff format .
16+
echo "✓ Ruff formatting applied"
17+
echo
18+
19+
echo "2. Running ruff check with --fix for safe fixes..."
20+
ruff check --fix .
21+
echo "✓ Ruff safe fixes applied"
22+
echo
23+
24+
echo "3. Running final check to show any remaining issues..."
25+
echo
26+
ruff check .
27+
28+
echo
29+
echo "Formatting and safe fixes complete for posit/ directory!"
30+
echo "Run ./scripts/check-python-quality.sh to verify all checks pass."

0 commit comments

Comments
 (0)