Staging

CLAUDE.md

@@ -0,0 +1,62 @@
+# Python Coding & Editing Guidelines
+
+> **Living document – PRs welcome!**
+> Last updated: 2025‑07‑15
+
+## Table of Contents
+
+1. Philosophy
+1. Docstrings & Comments
+1. Type Hints
+1. Documentation
+
+---
+
+## Philosophy
+
+- **Readability, reproducibility, performance – in that order.**
+- Prefer explicit over implicit; avoid hidden state and global flags.
+- Measure before you optimize (`time.perf_counter`, `line_profiler`).
+- Each module holds a **single responsibility**; keep public APIs minimal.
+
+## Docstrings & Comments
+
+- Style: NumPyDoc.
+- Start with a one‑sentence summary in the imperative mood.
+- Sections: Parameters, Returns, Raises, Examples, References.
+- Use backticks for code or referring to variables (e.g. `xarray.DataArray`).
+- Do not use emojis, or non-unicode characters in comments/print statements.
+- Cite peer‑reviewed papers with DOI links when relevant.
+- Write code that explains itself rather than needs comments.
+- For the inline you do add, explain *why*, not what. For example, *don't* write:
+
+```python
+# open the file
+f = open(filename)
+```
+
+- The comments should be things which are not obvious to a reader with typical background knowledge.
+
+## Tools
+
+- ruff is use for most code maintenance, black for formatting, mypy for type checking, pytest for testing
+- You can run `pre-commit run -a` to run all pre-commit hooks and check for style violations
+
+## Code Style
+
+- Annotate all public functions (PEP 484).
+- Prefer `Protocol` over `ABC`s when only an interface is needed.
+- Validate external inputs via Pydantic models (if existing); otherwise, use `dataclasses`
+- Parse, don't validate, with your dataclasses. Checks should be at the serialization boundaries, not scattered everywhere in the code.
+- If you need to add an ignore, ignore a specific check like # type: ignore[specific]
+- Don't write error handing code or smooth over exceptions/errors unless they are expected as part of control flow.
+- In general, write code that will raise an exception early if something isn't expected.
+- Enforce important expectations with asserts, but raise errors for user-facing problems.
+
+## Documentation
+
+- mkdocs + Jupyter. Hosted on ReadTheDocs.
+- Auto API from type hints.
+- Provide tutorial notebooks covering common workflows.
+- Include examples in docstrings.
+- Add high-level guides for key functionality.