Skip to content

Commit 67c9ae4

Browse files
shaypal5shaypal5
authored
add CLAUDE.md (#282)
1 parent 6f2127f commit 67c9ae4

1 file changed

Lines changed: 261 additions & 0 deletions

File tree

‎CLAUDE.md‎

Lines changed: 261 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,261 @@
1+
# CLAUDE.md
2+
3+
## 📦 Project Overview
4+
5+
**Cachier** is a Python library providing persistent, stale-free, local and cross-machine caching for Python functions via a decorator API. It supports multiple backends (pickle, memory, MongoDB, SQL, Redis), is thread-safe, and is designed for extensibility and robust cross-platform support.
6+
7+
- **Repository:** [python-cachier/cachier](https://github.com/python-cachier/cachier)
8+
- **Primary Language:** Python 3.9+
9+
- **Key Dependencies:** `portalocker`, `watchdog` (optional: `pymongo`, `sqlalchemy`, `redis`)
10+
- **Test Framework:** `pytest`
11+
- **Linting:** `ruff`
12+
- **Type Checking:** `mypy`
13+
- **CI:** GitHub Actions (matrix for backends/OS)
14+
- **Issue Tracking:** GitHub Issues
15+
16+
---
17+
18+
## 🗂️ Repository Structure
19+
20+
```
21+
cachier/
22+
├── src/cachier/ # Main library code
23+
│ ├── __init__.py
24+
│ ├── core.py # Decorator logic, backend selection
25+
│ ├── cores/ # Backend implementations
26+
│ │ ├── pickle.py
27+
│ │ ├── memory.py
28+
│ │ ├── mongo.py
29+
│ │ ├── sql.py
30+
│ │ ├── redis.py
31+
│ │ └── base.py
32+
│ ├── config.py # Global/default config
33+
│ ├── _types.py # Type definitions
34+
│ ├── _version.py
35+
│ └── __main__.py
36+
├── tests/ # Pytest-based tests, backend-marked
37+
│ ├── test_*.py
38+
│ └── *_requirements.txt # Backend-specific test requirements
39+
├── examples/ # Usage examples
40+
├── README.rst # Main documentation
41+
├── pyproject.toml # Build, lint, type, test config
42+
├── .pre-commit-config.yaml
43+
├── .github/ # CI, issue templates, workflows
44+
└── ... (see full tree above)
45+
```
46+
47+
---
48+
49+
## 🚦 Quick Start
50+
51+
1. **Install core dependencies:**
52+
```bash
53+
pip install .[all]
54+
```
55+
- For backend-specific dev: see `tests/*_requirements.txt`.
56+
57+
2. **Run tests:**
58+
```bash
59+
pytest
60+
```
61+
62+
3. **Lint and type-check:**
63+
```bash
64+
ruff check .
65+
mypy src/cachier/
66+
```
67+
68+
4. **Try an example:**
69+
```bash
70+
python examples/redis_example.py
71+
```
72+
73+
---
74+
75+
## 🧑‍💻 Development Guidelines
76+
77+
### 1. **Code Style & Quality**
78+
79+
- **Python 3.9+** only.
80+
- **Type annotations** required for all new code.
81+
- **Docstrings:** Use numpy style, multi-line, no single-line docstrings.
82+
- **Lint:** Run `ruff` before PRs. Use per-line/file ignores only for justified cases.
83+
- **Type check:** Run `mypy` before PRs.
84+
- **Testing:** All public methods must have at least one test. Use `pytest.mark.<backend>` for backend-specific tests.
85+
- **No warnings/errors for missing optional dependencies at import time.** Only raise when backend is used.
86+
87+
### 2. **Backends**
88+
89+
- **Default:** Pickle (local file cache, `~/.cachier/`)
90+
- **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.
93+
94+
### 3. **Decorator Usage**
95+
96+
- Main API: `@cachier`
97+
- Key params: `stale_after`, `backend`, `mongetter`, `cache_dir`, `pickle_reload`, `separate_files`, `wait_for_calc_timeout`, `allow_none`, `hash_func`
98+
- Arguments to cached functions must be hashable. For unhashable, provide `hash_func`.
99+
100+
### 4. **Testing**
101+
102+
- **Run all tests:** `pytest`
103+
- **Backend-specific:** Use markers, e.g. `pytest -m mongo`
104+
- **Requirements:** See `tests/*_requirements.txt` for backend test deps.
105+
- **CI:** Matrix covers OS/backend combinations. Mongo/SQL require Dockerized services.
106+
107+
### 5. **Documentation**
108+
109+
- **README.rst** is the canonical user/developer doc.
110+
- **New features/backends:** Update README, add usage example, document config options.
111+
- **Doc validation:** `python setup.py checkdocs`
112+
113+
### 6. **Error Handling**
114+
115+
- **No import-time warnings for missing optional deps.**
116+
- **Raise errors/warnings only when backend is used.**
117+
- **Graceful fallback/skip for missing backend deps in tests.**
118+
119+
### 7. **Backward Compatibility**
120+
121+
- **Public API must remain backward compatible** unless breaking change is approved.
122+
- **Support for Python 3.9+ only.**
123+
124+
### 8. **Global Configuration**
125+
126+
- Use `set_default_params`, `set_global_params`, `enable_caching`, `disable_caching` for global config.
127+
128+
---
129+
130+
## 🛠️ Common Bash & MCP Commands
131+
132+
- **Install all dev dependencies:**
133+
```bash
134+
pip install .[all]
135+
pip install -r tests/requirements.txt
136+
```
137+
- **Run all tests:** `pytest`
138+
- **Run backend-specific tests:** `pytest -m <backend>`
139+
- **Lint:** `ruff check .`
140+
- **Type check:** `mypy src/cachier/`
141+
- **Format:** `ruff format .`
142+
- **Pre-commit:** `pre-commit run --all-files`
143+
- **Build package:** `python -m build`
144+
- **Check docs:** `python setup.py checkdocs`
145+
- **Run example:** `python examples/redis_example.py`
146+
- **Update requirements:** Edit `tests/*_requirements.txt` as needed.
147+
148+
---
149+
150+
## 🧩 Claude Code Integration
151+
152+
### a. **File Navigation & Context**
153+
154+
- **Core logic:** `src/cachier/core.py`
155+
- **Backends:** `src/cachier/cores/`
156+
- **Config:** `src/cachier/config.py`
157+
- **Types:** `src/cachier/_types.py`
158+
- **Tests:** `tests/`
159+
- **Examples:** `examples/`
160+
- **Docs:** `README.rst`
161+
162+
### b. **Best Practices for Claude**
163+
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).
166+
- **When editing core logic:** Ensure all backends are still supported and tested.
167+
- **When updating the decorator API:** Update docstrings, README, and tests.
168+
- **When adding config options:** Update `config.py`, docstrings, README, and add tests.
169+
- **When changing global config:** Ensure backward compatibility and update docs.
170+
171+
### c. **Claude-Specific Tips**
172+
173+
- **Use MCP for git operations** (commits, pushes, PRs) instead of CLI.
174+
- **When in doubt, prefer explicit, readable code over cleverness.**
175+
- **Never use non-ASCII characters or the em dash.**
176+
- **If stuck, suggest opening a new chat with latest context.**
177+
- **If adding new dependencies, use context7 MCP to get latest versions.**
178+
- **Always check GitHub Issues before starting new features/PRs.**
179+
- **Create a relevant issue for every new PR.**
180+
- **Use per-file or per-line ignores for mypy/ruff only when justified.**
181+
- **All new code must have full type annotations and numpy-style docstrings.**
182+
183+
---
184+
185+
## 🧪 Testing Matrix & Markers
186+
187+
- **Markers:** `@pytest.mark.<backend>` (e.g., `@pytest.mark.sql`)
188+
- **Mongo/SQL:** Require Dockerized services for CI.
189+
- **Tests must not break if optional backend deps are missing.**
190+
- **CI matrix:** See `.github/workflows/` for details.
191+
192+
---
193+
194+
## 📝 Documentation & Examples
195+
196+
- **README.rst:** Main user/developer doc. Update for new features/backends.
197+
- **Examples:** Add usage examples for new features/backends in `examples/`.
198+
- **Docstrings:** Numpy style, multi-line, no single-line docstrings.
199+
200+
---
201+
202+
## 🛡️ Security & Performance
203+
204+
- **No secrets in code or tests.**
205+
- **Do not emit warnings/errors for missing optional deps at import time.**
206+
- **Thread safety:** All backends must be thread-safe.
207+
- **Performance:** Avoid unnecessary serialization/deserialization.
208+
209+
---
210+
211+
## 🏷️ Branching & Workflow
212+
213+
- **Workflow:** Issue → Feature branch → GitHub PR
214+
- **Branch naming:** `feature/<desc>`, `bugfix/<desc>`, etc.
215+
- **PRs:** Reference relevant issue, link to tests/docs as needed.
216+
- **Commits:** Use MCP tools, not direct git CLI.
217+
218+
---
219+
220+
## 🧭 Quick Reference
221+
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+
---
240+
241+
## 🧠 Claude Code: Special Instructions
242+
243+
- **This file is commited to the repository and so should never include any secrets.**
244+
- **Always read this file and the README.rst before making changes.**
245+
- **When adding new features/backends, update all relevant docs, tests, and CI.**
246+
- **If a test fails due to missing optional dependency, skip gracefully.**
247+
- **Never emit warnings/errors for missing optional deps at import time.**
248+
- **All code must be Python 3.9+ compatible.**
249+
- **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.**
251+
- **If you are stuck, suggest opening a new chat with the latest context.**
252+
253+
---
254+
255+
## 🏁 Final Notes
256+
257+
- **This file is the canonical quick reference for Claude Code and human contributors.**
258+
- **Update this file whenever project conventions, workflows, or best practices change.**
259+
- **Keep this file concise, actionable, and up-to-date.**
260+
- **For detailed documentation, see README.rst and the codebase.**
261+
- **This file is commited to the repository and so should never include any secrets.**

0 commit comments

Comments
 (0)