machow Great-Tables Code Standards
These standards are derived from PR review patterns. Apply them when writing or reviewing code.
Principles
- Test one behavior per case - Each test should verify exactly one thing
- Keep gt.py thin - Delegate implementation to specialized modules
- Interface over isinstance - Types implement methods instead of branching on type
- Be specific in docstrings - Reference parameter names, not vague terms
- Use functools.partial for variants - Reduce duplication for context-specific versions
- Use None for auto-detect defaults - Allow override while enabling smart defaults
- Separate features from refactoring - One PR = one logical change
- Co-locate and consolidate - Avoid single-use imports, use existing methods, validate once
Quick Reference
| Pattern | Key Technique |
|---|---|
| Testing | @pytest.mark.parametrize("kwargs,expected", [...]) - only non-defaults |
| Architecture | Attach functions from _export.py as methods on GT |
| Interfaces | Classes implement .to_html() / .to_latex() methods |
| Docstrings | "Apply func to matches of pattern" - use param names |
| Variants | partial(fmt_context, context="html") |
| Defaults | def f(option=None): where None means auto-detect |
| PRs | Feature PR + Refactor PR separately |
| Organization | Co-locate single-use code; use existing methods; validate once |
Detailed Examples
See individual files for before/after examples:
- 01-test-one-behavior.md
- 02-keep-gt-thin.md
- 03-interface-over-isinstance.md
- 04-specific-docstrings.md
- 05-use-partial.md
- 06-none-for-autodetect.md
- 07-separate-prs.md
- 08-code-organization.md