Guidelines for Writing Source Code

Type Annotations

Every function, variable, and class attribute must be strictly typed. No exceptions.

Use modern Python 3.12+ syntax:

• Type aliases with type statement
• PEP 695 type parameters ([T], [**P])
• Pipe unions (str | int, not Union[str, int])
• Proper optional types (str | None, not Optional[str])

Linting and Type Checking

Always run just check and just format before committing. just check must show zero errors:

just format
just check

If there's absolutely no alternative, use # pyright: ignore[errorCode] or #NOQA: errorCode to ignore typing or linting errors.

Docstrings

Use Google-style docstrings. Include a "Why" section and "Example" section when it adds value:

def resolve_relative_path(
    path: pathlib.Path, info: pydantic.ValidationInfo, must_exist: bool = True
) -> pathlib.Path:
    """Convert relative path to absolute path based on input file location.

    Why:
        Users reference files like `photo: profile.jpg` relative to their CV
        YAML. This validator resolves such paths to absolute form and validates
        existence, enabling file access during rendering.

    Args:
        path: Path to resolve (may be relative or absolute).
        info: Validation context containing input file path.
        must_exist: Whether to raise error if path doesn't exist.

    Returns:
        Absolute path.
    """

Docstring order:

1. Brief description (one line)
2. Why section (when it adds value)
3. Example section (when it adds value)
4. Args section (mandatory)
5. Returns section (mandatory)
6. Raises section (mandatory if function raises exceptions)