vault backup: 2025-12-23 16:41:40

AGENT.md

@@ -11,16 +11,20 @@ The rest of this document describes coding conventions to follow when writing co
 - Do not create a summary .md file unless asked.
 - Do not create a README.md file unless asked.
 - When installing a new dependency, prefer to use the latest version.
+- Try to reduce indentation, prefer to use early returns or continue everwhere, be excessive about it.
 
 ## Python
 - Use uv for handling python installations
 - Use pyproject.toml to handle dependencies
 - Avoid exceptions if possible
-- When exceptions are necessary, use specific exception types, provide meaningful messages, and handle them appropriately.
+- When exceptions are necessary, use specific exception types, provide meaningful messages, and handle them appropriately. 
 - Exceptions try/except blocks should be as narrow as possible, try extra hard to avoid catching exceptions you did not intend to catch.
 - Use type hints for all functions and methods.
+- Use global constants for compiled regex patterns, capitalized and ending with `_RE`.
+- Document regex patterns with inline comments using multiple strings inside `re.compile()`. This overrides the general rule against docstrings/comments.
 
 ## Python unit testing:
+- we should have a tests package under each implementation that has a test and the corresponding test foo/bar.py is tested in foo/bar/tests/test_bar.py
 - Use pytest framework, version 9 or higher.
 - Configure using pyproject.toml, avoid pytest.ini to be able to have all configuration in one place.
 - Prefer parametrized tests for functions that need to be tested with multiple sets of inputs and expected outputs.
@@ -42,3 +46,11 @@ def test_parametrized(subtests: pytest.Subtests) -> None:
 - Prefer function based views over class based views
 - Use django-stubs for type hints
 - Use pytest-django for testing django applications
+- Avoid comments in settings.
+
+## Style Learnings
+- **Stateful Parsing**: For complex tasks like parsing, prefer stateful classes that share context via `self` to avoid passing many arguments.
+- **Match Statement Inlining**: Prefer inlining simple, single-statement logic directly into `match` cases.
+- **Semantic Naming**: Use names that reflect the domain (e.g. `answer`) rather than implementation details (e.g. `spoiler`).
+- **Data Propagation**: Ensure all calculated metrics (like question counts) are consistently propagated to the final output structure.
+- **Factory Helpers**: Use centralized factory methods (e.g. `_create_question`) to instantiate objects with many shared common fields.- **Test Organization**: Place tests in a `tests` package within each implementation directory. Test files should be named `test_xxx.py` corresponding to the `xxx.py` file they test.