Skip to content

Commit 2d375e7

Browse files
committed
cursor(rules[dev-loop]) Sync with latest python loop
1 parent 6e7d0cd commit 2d375e7

File tree

1 file changed

+164
-14
lines changed

1 file changed

+164
-14
lines changed

.cursor/rules/dev-loop.mdc

Lines changed: 164 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,37 +1,187 @@
11
---
22
description: QA every edit
33
globs: *.py
4+
alwaysApply: true
45
---
56

6-
# First: QA Every edit
7+
# Development Process
78

8-
Run these commands between edits:
9+
## Project Stack
910

10-
Check typings:
11+
The project uses the following tools and technologies:
12+
13+
- **uv** - Python package management and virtual environments
14+
- **ruff** - Fast Python linter and formatter
15+
- **py.test** - Testing framework
16+
- **pytest-watcher** - Continuous test runner
17+
- **mypy** - Static type checking
18+
- **doctest** - Testing code examples in documentation
19+
20+
## 1. Start with Formatting
21+
22+
Format your code first:
1123

1224
```
13-
uv run mypy
25+
uv run ruff format .
26+
```
27+
28+
## 2. Run Tests
29+
30+
Verify that your changes pass the tests:
31+
32+
```
33+
uv run py.test
1434
```
1535

16-
Lint:
36+
For continuous testing during development, use pytest-watcher:
1737

1838
```
19-
uv run ruff check . --fix --show-fixes; uv run ruff format .;
39+
# Watch all tests
40+
uv run ptw .
41+
42+
# Watch and run tests immediately, including doctests
43+
uv run ptw . --now --doctest-modules
44+
45+
# Watch specific files or directories
46+
uv run ptw . --now --doctest-modules src/libtmux/_internal/
2047
```
2148

22-
Check tests:
49+
## 3. Commit Initial Changes
50+
51+
Make an atomic commit for your changes using conventional commits.
52+
Use `@git-commits.mdc` for assistance with commit message standards.
53+
54+
## 4. Run Linting and Type Checking
55+
56+
Check and fix linting issues:
57+
58+
```
59+
uv run ruff check . --fix --show-fixes
60+
```
61+
62+
Check typings:
63+
64+
```
65+
uv run mypy
66+
```
67+
68+
## 5. Verify Tests Again
69+
70+
Ensure tests still pass after linting and type fixes:
2371

2472
```
2573
uv run py.test
2674
```
2775

28-
Between every edit, rerun:
29-
- Type checks
30-
- Lint
31-
- Tests
76+
## 6. Final Commit
77+
78+
Make a final commit with any linting/typing fixes.
79+
Use `@git-commits.mdc` for assistance with commit message standards.
80+
81+
## Development Loop Guidelines
82+
83+
If there are any failures at any step due to your edits, fix them before proceeding to the next step.
84+
85+
## Python Code Standards
86+
87+
### Docstring Guidelines
88+
89+
For `src/**/*.py` files, follow these docstring guidelines:
90+
91+
1. **Use reStructuredText format** for all docstrings.
92+
```python
93+
"""Short description of the function or class.
94+
95+
Detailed description using reStructuredText format.
96+
97+
Parameters
98+
----------
99+
param1 : type
100+
Description of param1
101+
param2 : type
102+
Description of param2
103+
104+
Returns
105+
-------
106+
type
107+
Description of return value
108+
"""
109+
```
110+
111+
2. **Keep the main description on the first line** after the opening `"""`.
112+
113+
3. **Use NumPy docstyle** for parameter and return value documentation.
114+
115+
### Doctest Guidelines
116+
117+
For doctests in `src/**/*.py` files:
118+
119+
1. **Use narrative descriptions** for test sections rather than inline comments:
120+
```python
121+
"""Example function.
122+
123+
Examples
124+
--------
125+
Create an instance:
126+
127+
>>> obj = ExampleClass()
128+
129+
Verify a property:
130+
131+
>>> obj.property
132+
'expected value'
133+
"""
134+
```
135+
136+
2. **Move complex examples** to dedicated test files at `tests/examples/<path_to_module>/test_<example>.py` if they require elaborate setup or multiple steps.
137+
138+
3. **Utilize pytest fixtures** via `doctest_namespace` for more complex test scenarios:
139+
```python
140+
"""Example with fixture.
141+
142+
Examples
143+
--------
144+
>>> # doctest_namespace contains all pytest fixtures from conftest.py
145+
>>> example_fixture = getfixture('example_fixture')
146+
>>> example_fixture.method()
147+
'expected result'
148+
"""
149+
```
150+
151+
4. **Keep doctests simple and focused** on demonstrating usage rather than comprehensive testing.
152+
153+
5. **Add blank lines between test sections** for improved readability.
154+
155+
6. **Test your doctests continuously** using pytest-watcher during development:
156+
```
157+
# Watch specific modules for doctest changes
158+
uv run ptw . --now --doctest-modules src/path/to/module.py
159+
```
160+
161+
### Pytest Testing Guidelines
162+
163+
1. **Use existing fixtures over mocks**:
164+
- Use fixtures from conftest.py instead of `monkeypatch` and `MagicMock` when available
165+
- For instance, if using libtmux, use provided fixtures: `server`, `session`, `window`, and `pane`
166+
- Document in test docstrings why standard fixtures weren't used for exceptional cases
167+
168+
2. **Preferred pytest patterns**:
169+
- Use `tmp_path` (pathlib.Path) fixture over Python's `tempfile`
170+
- Use `monkeypatch` fixture over `unittest.mock`
171+
172+
### Import Guidelines
32173

33-
If there's any failures *due to the edits*, fix them first, then:
174+
1. **Prefer namespace imports**:
175+
- Import modules and access attributes through the namespace instead of importing specific symbols
176+
- Example: Use `import enum` and access `enum.Enum` instead of `from enum import Enum`
177+
- This applies to standard library modules like `pathlib`, `os`, and similar cases
34178

35-
# When your edit is complete: Commit it
179+
2. **Standard aliases**:
180+
- For `typing` module, use `import typing as t`
181+
- Access typing elements via the namespace: `t.NamedTuple`, `t.TypedDict`, etc.
182+
- Note primitive types like unions can be done via `|` pipes and primitive types like list and dict can be done via `list` and `dict` directly.
36183

37-
Make an atomic commit for the edit, using conventional commits.
184+
3. **Benefits of namespace imports**:
185+
- Improves code readability by making the source of symbols clear
186+
- Reduces potential naming conflicts
187+
- Makes import statements more maintainable

0 commit comments

Comments
 (0)