1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
|
# libtmux Python Project Rules
<project_stack>
- uv - Python package management and virtual environments
- ruff - Fast Python linter and formatter
- py.test - Testing framework
- pytest-watcher - Continuous test runner
- mypy - Static type checking
- doctest - Testing code examples in documentation
</project_stack>
<coding_style>
- Use a consistent coding style throughout the project
- Format code with ruff before committing
- Run linting and type checking before finalizing changes
- Verify tests pass after each significant change
</coding_style>
<python_docstrings>
- Use reStructuredText format for all docstrings in src/**/*.py files
- Keep the main description on the first line after the opening `"""`
- Use NumPy docstyle for parameter and return value documentation
- Format docstrings as follows:
```python
"""Short description of the function or class.
Detailed description using reStructuredText format.
Parameters
----------
param1 : type
Description of param1
param2 : type
Description of param2
Returns
-------
type
Description of return value
"""
```
</python_docstrings>
<python_doctests>
- Use narrative descriptions for test sections rather than inline comments
- Format doctests as follows:
```python
"""
Examples
--------
Create an instance:
>>> obj = ExampleClass()
Verify a property:
>>> obj.property
'expected value'
"""
```
- Add blank lines between test sections for improved readability
- Keep doctests simple and focused on demonstrating usage
- Move complex examples to dedicated test files at tests/examples/<path_to_module>/test_<example>.py
- Utilize pytest fixtures via doctest_namespace for complex scenarios
</python_doctests>
<testing_practices>
- Run tests with `uv run py.test` before committing changes
- Use pytest-watcher for continuous testing: `uv run ptw . --now --doctest-modules`
- Fix any test failures before proceeding with additional changes
</testing_practices>
<git_workflow>
- Make atomic commits with conventional commit messages
- Start with an initial commit of functional changes
- Follow with separate commits for formatting, linting, and type checking fixes
</git_workflow>
<git_commit_standards>
- Use the following commit message format:
```
Component/File(commit-type[Subcomponent/method]): Concise description
why: Explanation of necessity or impact.
what:
- Specific technical changes made
- Focused on a single topic
refs: #issue-number, breaking changes, or relevant links
```
- Common commit types:
- **feat**: New features or enhancements
- **fix**: Bug fixes
- **refactor**: Code restructuring without functional change
- **docs**: Documentation updates
- **chore**: Maintenance (dependencies, tooling, config)
- **test**: Test-related updates
- **style**: Code style and formatting
- Prefix Python package changes with:
- `py(deps):` for standard packages
- `py(deps[dev]):` for development packages
- `py(deps[extra]):` for extras/sub-packages
- General guidelines:
- Subject line: Maximum 50 characters
- Body lines: Maximum 72 characters
- Use imperative mood (e.g., "Add", "Fix", not "Added", "Fixed")
- Limit to one topic per commit
- Separate subject from body with a blank line
- Mark breaking changes clearly: `BREAKING:`
</git_commit_standards>
<pytest_testing_guidelines>
- Use fixtures from conftest.py instead of monkeypatch and MagicMock when available
- For instance, if using libtmux, use provided fixtures: server, session, window, and pane
- Document in test docstrings why standard fixtures weren't used for exceptional cases
- Use tmp_path (pathlib.Path) fixture over Python's tempfile
- Use monkeypatch fixture over unittest.mock
</pytest_testing_guidelines>
<import_guidelines>
- Prefer namespace imports over importing specific symbols
- Import modules and access attributes through the namespace:
- Use `import enum` and access `enum.Enum` instead of `from enum import Enum`
- This applies to standard library modules like pathlib, os, and similar cases
- For typing, use `import typing as t` and access via the namespace:
- Access typing elements as `t.NamedTuple`, `t.TypedDict`, etc.
- Note primitive types like unions can be done via `|` pipes
- Primitive types like list and dict can be done via `list` and `dict` directly
- Benefits of namespace imports:
- Improves code readability by making the source of symbols clear
- Reduces potential naming conflicts
- Makes import statements more maintainable
</import_guidelines>
|
