claude18

Author: bdowning

CLAUDE.md

@@ -42,6 +42,20 @@ tests/
 ├── test_asyncpg.py      # asyncpg integration tests
 ├── test_dataclasses.py  # ModelBase tests
 └── test_sqlalchemy.py   # SQLAlchemy integration tests
+
+docs/
+├── source/
+│   ├── conf.py          # Sphinx configuration
+│   ├── index.rst        # Main documentation page
+│   ├── api/             # API reference documentation
+│   │   ├── index.rst
+│   │   ├── base.rst     # sql_athame.base module docs
+│   │   └── dataclasses.rst  # sql_athame.dataclasses module docs
+│   ├── examples/        # Usage examples and tutorials
+│   │   └── index.rst
+│   └── _static/         # Static files for documentation
+├── build/               # Generated documentation (gitignored)
+└── Makefile             # Standard Sphinx Makefile
 ```
 
 ## Development Environment
@@ -50,16 +64,32 @@ tests/
 - Core: `typing-extensions` only
 - Optional: `asyncpg` for PostgreSQL, `SQLAlchemy` for ORM integration
 - Dev tools: `ruff` (linting), `mypy` (type checking), `pytest` (testing)
+- Documentation: `sphinx`, `sphinx-rtd-theme`, `sphinx-autodoc-typehints`
+
+### Build Commands (via ./run script)
+- `./run tests` - Run tests with coverage and linting
+- `./run lint` - Run linting and type checking
+- `./run refmt` - Reformat code with ruff
+- `./run docs-build` - Build documentation
+- `./run docs-serve` - Build and serve documentation locally at http://localhost:8000
+- `./run docs-clean` - Clean documentation build artifacts
+- `./run bump2version {major|minor|patch}` - Bump version number
 
 ### Testing
-Run tests with: `pytest`
+Run tests with: `./run tests` or `uv run pytest`
 The project has comprehensive test coverage including async database operations.
 
 ### Code Quality
 - Uses `ruff` for linting and formatting
 - Type checked with `mypy`
 - Follows modern Python conventions (3.9+)
 
+### Documentation
+- Full Sphinx documentation with Read the Docs theme
+- Auto-generated API reference from comprehensive docstrings
+- Usage examples and tutorials
+- Available locally via `./run docs-serve`
+
 ## Common Operations
 
 ### Building Queries
@@ -87,15 +117,22 @@ result = await conn.fetch(*query)
 
 ### Dataclass Models
 ```python
+from typing import Annotated, Optional
+from sql_athame import ModelBase, ColumnInfo
+
 @dataclass
 class User(ModelBase, table_name="users", primary_key="id"):
     id: UUID
     name: str
     email: Optional[str] = None
+    metadata: Optional[Annotated[dict, ColumnInfo(type="JSONB")]] = None
 
 # Generate SQL
 create_sql = User.create_table_sql()
 select_sql = User.select_sql(where=sql("active = {}", True))
+
+# Use with asyncpg
+users = await User.select(pool, where=sql("department_id = {}", dept_id))
 ```
 
 ## Safety Notes
@@ -104,6 +141,44 @@ select_sql = User.select_sql(where=sql("active = {}", True))
 - The library automatically handles parameter numbering and escaping
 - Dataclass serialization handles JSON/JSONB conversion automatically
 
+## Key API Reference
+
+### Core Classes (sql_athame.base)
+- `Fragment` - Core SQL fragment class with comprehensive methods
+- `SQLFormatter` (available as `sql`) - Main query builder with utility methods
+
+### ORM Classes (sql_athame.dataclasses)
+- `ModelBase` - Base class for dataclass models with full CRUD operations
+- `ColumnInfo` - Column metadata for type mapping and constraints
+- `ReplaceMultiplePlan` - Planning class for bulk replace operations
+
+### Important Methods
+- **SQL Building**: `sql()`, `sql.all()`, `sql.any()`, `sql.list()`, `sql.literal()`
+- **Model Operations**: `create_table_sql()`, `select_sql()`, `insert_sql()`, `upsert_sql()`
+- **Database Operations**: `select()`, `create()`, `insert()`, `upsert()`, `delete_multiple()`
+- **Bulk Operations**: `insert_multiple()`, `upsert_multiple()`, `replace_multiple()`
+
+## Documentation & Development Notes
+
+### Docstring Coverage
+All major classes and methods have comprehensive Sphinx-style docstrings including:
+- Parameter descriptions with types
+- Return value documentation
+- Usage examples where helpful
+- Cross-references to related functionality
+
+### Column Configuration
+Use `Annotated` types with `ColumnInfo` for column metadata:
+```python
+price: Annotated[Decimal, ColumnInfo(type="NUMERIC(10,2)", constraints="CHECK (price > 0)")]
+tags: Annotated[list, ColumnInfo(type="JSONB", serialize=json.dumps, deserialize=json.loads)]
+```
+
+### Bulk Insert Modes
+- `unnest` (default): Most efficient for PostgreSQL using UNNEST
+- `array_safe`: Uses VALUES syntax with chunking for large datasets  
+- `executemany`: Uses asyncpg's executemany (slowest but most compatible)
+
 ## Version Info
 Current version: 0.4.0-alpha-12 (as of analysis)
 License: MIT