Development guidelines for Python database obfuscation package using pydantic and UUIDs to map data models to ArangoDB
Expert development assistant for the DB Facade project - a Python package that uses pydantic data classes and maps data to UUIDs for obfuscation in ArangoDB.
DB Facade is a database abstraction layer that:
Before making changes, review:
1. **README.md** - Project overview and usage
2. **DESIGN.md** - Architecture and technical specifications
3. **CONTRIBUTING.md** - Coding standards
4. **TODO.md** - Implementation plan
**NEVER implement fallbacks or paper over errors.** DB Facade follows a strict FAIL-STOP model:
1. **ALWAYS fail immediately and visibly** when issues occur
2. **NEVER substitute mock/fake data** when real data is unavailable
3. **ALWAYS exit with clear error message** (`sys.exit(1)`) rather than continuing with degraded functionality
4. **Database security is paramount** - silently substituting mock data compromises integrity
```python
import sys
import logging
try:
result = essential_database_operation()
if not result:
logging.error("CRITICAL: Database operation failed")
sys.exit(1)
except Exception as e:
logging.error(f"CRITICAL: {e}")
sys.exit(1)
try:
result = recoverable_operation()
except ValueError as e:
logging.error(f"Processing failed: {e}")
raise DBFacadeProcessingError(f"Failed: {str(e)}") from e
```
```bash
pip install uv
uv pip install -e .
```
```bash
source .venv-linux-python3.13/bin/activate
.venv-win32-python3.12\Scripts\Activate.ps1
.venv-win32-python3.12\Scripts\activate.bat
source .venv-macos-python3.12/bin/activate
```
```python
data = model.dict()
data = model.model_dump()
json_str = model.model_dump_json()
doc = json.loads(model.model_dump_json())
```
```python
class OldModel(BaseModel):
name: str
class Config:
arbitrary_types_allowed = True
class NewModel(BaseModel):
name: str
model_config = {"arbitrary_types_allowed": True}
```
```python
from pydantic import BaseModel, Field
from datetime import datetime, timezone
class UserModel(BaseModel):
name: str = Field(default="Anonymous")
created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
```
**ALWAYS use timezone-aware datetimes for ArangoDB:**
```python
from datetime import datetime, timezone
from pydantic import BaseModel, Field, field_validator
class MyModel(BaseModel):
created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
@field_validator('created_at')
def ensure_timezone(cls, v):
if v.tzinfo is None:
return v.replace(tzinfo=timezone.utc)
return v
```
```python
if isinstance(results, Cursor):
result_list = [doc for doc in results]
result_data["results"] = result_list
else:
result_data["results"] = results
```
```python
cursor = db.aql.execute(query, bind_vars=params, batch_size=1000)
results = []
max_results = 10000
for doc in cursor:
results.append(doc)
if len(results) >= max_results:
logging.info(f"Reached max {max_results} results")
break
processed = 0
for doc in cursor:
process_document(doc)
processed += 1
if processed % 10000 == 0:
logging.info(f"Processed {processed} documents")
```
Direct database access via MCP:
Use these to verify database state and diagnose issues.
```python
import sys
import logging
from pydantic import BaseModel, Field
from dbfacade.models import MyModel
```
```python
from typing import Optional, List
def process_data(items: List[str], max_count: Optional[int] = None) -> dict[str, int]:
"""Process items and return count statistics.
Args:
items: List of strings to process
max_count: Optional maximum items to process
Returns:
Dictionary with processing statistics
"""
pass
```
Use Python 3.13+ features:
```python
match status:
case "active":
return process_active()
case "pending":
return process_pending()
case _:
return handle_unknown()
```
```bash
pytest tests/
black .
ruff check .
flake8 .
```
**Use sys.exit(1) for:**
**Use exceptions for:**
1. **Activate virtual environment** for your platform
2. **Review relevant documentation** (README, DESIGN, TODO)
3. **Write type-safe code** with proper hints and Pydantic V2 patterns
4. **Use timezone-aware datetimes** for all temporal data
5. **Implement fail-stop** for critical paths
6. **Handle cursors properly** based on result set size
7. **Test cross-platform** if making script changes
8. **Run tests and linting** before committing
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/db-facade-development/raw