s1-api-conventions

name: s1-api-conventions description: Python API coding conventions for this BookStore project. Use when writing or reviewing Python code.

S1 — BookStore API Conventions

Follow these conventions when writing or reviewing Python code in this project.

Data Models

• Use @dataclass(slots=True) for all models
• Store monetary values as int in cents (e.g., price_cents: int)
• Use field(default_factory=list) for mutable defaults
• Type-annotate every field using modern syntax (str | None, not Optional[str])

API Functions

• All public API functions return dict (not dataclass instances)
• Include a "status" key in mutation responses ("created", "updated", "deleted")
• Use snake_case with a verb prefix: create_book, get_author, list_books
• Private helpers start with underscore: _to_dict, _validate_input

Docstrings

Every public function must have a docstring with:

"""One-line summary.

Args:
    param_name: Description.

Returns:
    Description of return value.

Raises:
    ValueError: When and why.
"""

Error Handling

• Raise ValueError for invalid inputs (bad data from the caller)
• Raise KeyError for missing resources (not found)
• Never silently swallow exceptions

Imports

• Standard library first, then third-party, then local
• Use absolute imports: from models.book import Book
• No wildcard imports