Skip to content

Commit bad25e2

Browse files
Copilotpre-commit-ci[bot]shaypal5
authored
Improve CLAUDE.md with comprehensive backend coverage, testing guidance, and copilot integration (#284)
* Initial plan * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * Improve CLAUDE.md with better backend coverage, testing guidance, and copilot integration Co-authored-by: shaypal5 <917954+shaypal5@users.noreply.github.com> * Add example validation and Redis example reference to CLAUDE.md Co-authored-by: shaypal5 <917954+shaypal5@users.noreply.github.com> * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> Co-authored-by: shaypal5 <917954+shaypal5@users.noreply.github.com>
1 parent 67c9ae4 commit bad25e2

1 file changed

Lines changed: 93 additions & 50 deletions

File tree

‎CLAUDE.md‎

Lines changed: 93 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -7,13 +7,14 @@
77
- **Repository:** [python-cachier/cachier](https://github.com/python-cachier/cachier)
88
- **Primary Language:** Python 3.9+
99
- **Key Dependencies:** `portalocker`, `watchdog` (optional: `pymongo`, `sqlalchemy`, `redis`)
10-
- **Test Framework:** `pytest`
11-
- **Linting:** `ruff`
10+
- **Test Framework:** `pytest` with backend-specific markers
11+
- **Linting:** `ruff` (replaces black/flake8)
1212
- **Type Checking:** `mypy`
13-
- **CI:** GitHub Actions (matrix for backends/OS)
13+
- **CI:** GitHub Actions (matrix for backends/OS with Dockerized services)
1414
- **Issue Tracking:** GitHub Issues
15+
- **Additional Docs:** `.github/copilot-instructions.md` for contributor guidelines
1516

16-
---
17+
______________________________________________________________________
1718

1819
## 🗂️ Repository Structure
1920

@@ -44,33 +45,54 @@ cachier/
4445
└── ... (see full tree above)
4546
```
4647

47-
---
48+
______________________________________________________________________
4849

4950
## 🚦 Quick Start
5051

5152
1. **Install core dependencies:**
53+
5254
```bash
5355
pip install .[all]
5456
```
57+
5558
- For backend-specific dev: see `tests/*_requirements.txt`.
5659

5760
2. **Run tests:**
61+
5862
```bash
59-
pytest
63+
pytest # All tests
64+
pytest -m "pickle or memory" # Basic backends only
65+
pytest -m "not (mongo or sql)" # Exclude external service backends
6066
```
6167

6268
3. **Lint and type-check:**
69+
6370
```bash
6471
ruff check .
6572
mypy src/cachier/
6673
```
6774

6875
4. **Try an example:**
76+
6977
```bash
78+
# Quick test
79+
python -c "
80+
from cachier import cachier
81+
import datetime
82+
83+
@cachier(stale_after=datetime.timedelta(days=1))
84+
def test_func(x):
85+
return x * 2
86+
87+
print(test_func(5)) # Calculates and caches
88+
print(test_func(5)) # Returns from cache
89+
"
90+
91+
# Or run the Redis example (requires Redis server)
7092
python examples/redis_example.py
7193
```
7294

73-
---
95+
______________________________________________________________________
7496

7597
## 🧑‍💻 Development Guidelines
7698

@@ -88,8 +110,9 @@ cachier/
88110

89111
- **Default:** Pickle (local file cache, `~/.cachier/`)
90112
- **Others:** Memory, MongoDB, SQL, Redis
91-
- **Adding a backend:** Implement in `src/cachier/cores/`, subclass `BaseCore`, add tests, update docs, and CI matrix if needed.
92-
- **Optional dependencies:** Code/tests must gracefully skip if backend deps are missing.
113+
- **Adding a backend:** Implement in `src/cachier/cores/`, subclass `BaseCore`, add tests with appropriate markers, update docs, and CI matrix if needed.
114+
- **Optional dependencies:** Code/tests must gracefully skip if backend deps are missing. Install backend-specific deps via `tests/*_requirements.txt`.
115+
- **Requirements files:** `tests/sql_requirements.txt`, `tests/redis_requirements.txt` for backend-specific dependencies.
93116

94117
### 3. **Decorator Usage**
95118

@@ -100,9 +123,11 @@ cachier/
100123
### 4. **Testing**
101124

102125
- **Run all tests:** `pytest`
103-
- **Backend-specific:** Use markers, e.g. `pytest -m mongo`
126+
- **Backend-specific:** Use markers, e.g. `pytest -m mongo`, `pytest -m redis`, `pytest -m sql`
127+
- **Available markers:** `mongo`, `memory`, `pickle`, `redis`, `sql`, `maxage` (see `pyproject.toml`)
104128
- **Requirements:** See `tests/*_requirements.txt` for backend test deps.
105-
- **CI:** Matrix covers OS/backend combinations. Mongo/SQL require Dockerized services.
129+
- **CI:** Matrix covers OS/backend combinations. Mongo/SQL/Redis require Dockerized services.
130+
- **Missing deps:** Tests gracefully skip if optional backend dependencies are missing.
106131

107132
### 5. **Documentation**
108133

@@ -115,37 +140,44 @@ cachier/
115140
- **No import-time warnings for missing optional deps.**
116141
- **Raise errors/warnings only when backend is used.**
117142
- **Graceful fallback/skip for missing backend deps in tests.**
143+
- **Thread-safety:** All backends must be thread-safe and handle concurrent access properly.
118144

119145
### 7. **Backward Compatibility**
120146

121147
- **Public API must remain backward compatible** unless breaking change is approved.
122148
- **Support for Python 3.9+ only.**
123149

124-
### 8. **Global Configuration**
150+
### 8. **Global Configuration & Compatibility**
125151

126152
- Use `set_default_params`, `set_global_params`, `enable_caching`, `disable_caching` for global config.
153+
- **Copilot Integration:** This file works alongside `.github/copilot-instructions.md` for comprehensive contributor guidance.
127154

128-
---
155+
______________________________________________________________________
129156

130157
## 🛠️ Common Bash & MCP Commands
131158

132159
- **Install all dev dependencies:**
133160
```bash
134-
pip install .[all]
161+
pip install -e .
135162
pip install -r tests/requirements.txt
163+
# For specific backends:
164+
pip install -r tests/sql_requirements.txt
165+
pip install -r tests/redis_requirements.txt
136166
```
137167
- **Run all tests:** `pytest`
138-
- **Run backend-specific tests:** `pytest -m <backend>`
168+
- **Run backend-specific tests:** `pytest -m <backend>` (mongo, redis, sql, memory, pickle, maxage)
169+
- **Run multiple backends:** `pytest -m "redis or sql"`
170+
- **Exclude backends:** `pytest -m "not mongo"`
139171
- **Lint:** `ruff check .`
140172
- **Type check:** `mypy src/cachier/`
141173
- **Format:** `ruff format .`
142174
- **Pre-commit:** `pre-commit run --all-files`
143175
- **Build package:** `python -m build`
144176
- **Check docs:** `python setup.py checkdocs`
145177
- **Run example:** `python examples/redis_example.py`
146-
- **Update requirements:** Edit `tests/*_requirements.txt` as needed.
178+
- **Update requirements:** Edit `tests/*_requirements.txt` as needed (sql_requirements.txt, redis_requirements.txt).
147179

148-
---
180+
______________________________________________________________________
149181

150182
## 🧩 Claude Code Integration
151183

@@ -161,12 +193,13 @@ cachier/
161193

162194
### b. **Best Practices for Claude**
163195

164-
- **Always check for backend-specific requirements** before running backend tests or code.
165-
- **When adding a backend:** Update all relevant places (core, tests, docs, CI).
196+
- **Always check for backend-specific requirements** before running backend tests or code (see `tests/*_requirements.txt`).
197+
- **When adding a backend:** Update all relevant places (core, tests, docs, CI matrix, requirements files).
166198
- **When editing core logic:** Ensure all backends are still supported and tested.
167199
- **When updating the decorator API:** Update docstrings, README, and tests.
168200
- **When adding config options:** Update `config.py`, docstrings, README, and add tests.
169201
- **When changing global config:** Ensure backward compatibility and update docs.
202+
- **Cross-reference:** Always check `.github/copilot-instructions.md` for additional contributor guidelines.
170203

171204
### c. **Claude-Specific Tips**
172205

@@ -180,24 +213,27 @@ cachier/
180213
- **Use per-file or per-line ignores for mypy/ruff only when justified.**
181214
- **All new code must have full type annotations and numpy-style docstrings.**
182215

183-
---
216+
______________________________________________________________________
184217

185218
## 🧪 Testing Matrix & Markers
186219

187-
- **Markers:** `@pytest.mark.<backend>` (e.g., `@pytest.mark.sql`)
188-
- **Mongo/SQL:** Require Dockerized services for CI.
220+
- **Markers:** `@pytest.mark.<backend>` (mongo, memory, pickle, redis, sql, maxage)
221+
- **Backend services:** Mongo/SQL/Redis require Dockerized services for CI.
189222
- **Tests must not break if optional backend deps are missing.**
190-
- **CI matrix:** See `.github/workflows/` for details.
223+
- **CI matrix:** See `.github/workflows/` for details on OS/backend combinations.
224+
- **Local testing:** Use specific requirement files for backends you want to test.
191225

192-
---
226+
______________________________________________________________________
193227

194228
## 📝 Documentation & Examples
195229

196230
- **README.rst:** Main user/developer doc. Update for new features/backends.
197231
- **Examples:** Add usage examples for new features/backends in `examples/`.
198232
- **Docstrings:** Numpy style, multi-line, no single-line docstrings.
233+
- **Copilot Instructions:** See `.github/copilot-instructions.md` for detailed contributor guidelines.
234+
- **This file:** Update CLAUDE.md when project conventions or workflows change.
199235

200-
---
236+
______________________________________________________________________
201237

202238
## 🛡️ Security & Performance
203239

@@ -206,7 +242,7 @@ cachier/
206242
- **Thread safety:** All backends must be thread-safe.
207243
- **Performance:** Avoid unnecessary serialization/deserialization.
208244

209-
---
245+
______________________________________________________________________
210246

211247
## 🏷️ Branching & Workflow
212248

@@ -215,47 +251,54 @@ cachier/
215251
- **PRs:** Reference relevant issue, link to tests/docs as needed.
216252
- **Commits:** Use MCP tools, not direct git CLI.
217253

218-
---
254+
______________________________________________________________________
219255

220256
## 🧭 Quick Reference
221257

222-
| Task | Command/Location |
223-
|-----------------------------|-----------------------------------------|
224-
| Run all tests | `pytest` |
225-
| Run backend-specific tests | `pytest -m <backend>` |
226-
| Lint | `ruff check .` |
227-
| Type check | `mypy src/cachier/` |
228-
| Format code | `ruff format .` |
229-
| Build package | `python -m build` |
230-
| Check docs | `python setup.py checkdocs` |
231-
| Update requirements | `tests/*_requirements.txt` |
232-
| Main decorator | `src/cachier/core.py` |
233-
| Backends | `src/cachier/cores/` |
234-
| Global config | `src/cachier/config.py` |
235-
| Tests | `tests/` |
236-
| Examples | `examples/` |
237-
| Documentation | `README.rst` |
238-
239-
---
258+
| Task | Command/Location |
259+
| -------------------------- | ---------------------------------- |
260+
| Run all tests | `pytest` |
261+
| Run backend-specific tests | `pytest -m <backend>` |
262+
| Test multiple backends | `pytest -m "redis or sql"` |
263+
| Exclude backends | `pytest -m "not mongo"` |
264+
| Lint | `ruff check .` |
265+
| Type check | `mypy src/cachier/` |
266+
| Format code | `ruff format .` |
267+
| Build package | `python -m build` |
268+
| Check docs | `python setup.py checkdocs` |
269+
| Backend requirements | `tests/sql_requirements.txt`, etc. |
270+
| Main decorator | `src/cachier/core.py` |
271+
| Backends | `src/cachier/cores/` |
272+
| Global config | `src/cachier/config.py` |
273+
| Tests | `tests/` |
274+
| Examples | `examples/` |
275+
| Documentation | `README.rst` |
276+
| Contributor guidelines | `.github/copilot-instructions.md` |
277+
278+
______________________________________________________________________
240279

241280
## 🧠 Claude Code: Special Instructions
242281

243-
- **This file is commited to the repository and so should never include any secrets.**
282+
- **This file is committed to the repository and so should never include any secrets.**
244283
- **Always read this file and the README.rst before making changes.**
245-
- **When adding new features/backends, update all relevant docs, tests, and CI.**
284+
- **Cross-reference:** Also read `.github/copilot-instructions.md` for detailed contributor guidelines.
285+
- **When adding new features/backends, update all relevant docs, tests, CI, and requirements files.**
246286
- **If a test fails due to missing optional dependency, skip gracefully.**
247287
- **Never emit warnings/errors for missing optional deps at import time.**
248288
- **All code must be Python 3.9+ compatible.**
249289
- **All new code must have full type annotations and numpy-style docstrings.**
250-
- **If you are unsure about a pattern, check the README and this file first.**
290+
- **Backend consistency:** Ensure all backends (pickle, memory, mongo, sql, redis) are supported.\*\*
291+
- **Validation:** Test examples in this file work: `python -c "from cachier import cachier; ..."` should succeed.
292+
- **If you are unsure about a pattern, check the README, this file, and .github/copilot-instructions.md first.**
251293
- **If you are stuck, suggest opening a new chat with the latest context.**
252294

253-
---
295+
______________________________________________________________________
254296

255297
## 🏁 Final Notes
256298

257299
- **This file is the canonical quick reference for Claude Code and human contributors.**
300+
- **Works alongside `.github/copilot-instructions.md` for comprehensive guidance.**
258301
- **Update this file whenever project conventions, workflows, or best practices change.**
259302
- **Keep this file concise, actionable, and up-to-date.**
260303
- **For detailed documentation, see README.rst and the codebase.**
261-
- **This file is commited to the repository and so should never include any secrets.**
304+
- **This file is committed to the repository and so should never include any secrets.**

0 commit comments

Comments
 (0)