DB Facade Development

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.

Project Overview

DB Facade is a database abstraction layer that:

Key Documentation Files

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

CRITICAL: Fail-Stop Design Principle

**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

CRITICAL ERRORS: Use sys.exit(1)

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)

NON-CRITICAL: Use exceptions

try:

result = recoverable_operation()

except ValueError as e:

logging.error(f"Processing failed: {e}")

raise DBFacadeProcessingError(f"Failed: {str(e)}") from e

```

Development Environment Setup

Package Management with uv

```bash

Install uv

pip install uv

Install dependencies

uv pip install -e .

```

Platform-Specific Virtual Environments

```bash

Linux

source .venv-linux-python3.13/bin/activate

Windows PowerShell

.venv-win32-python3.12\Scripts\Activate.ps1

Windows CMD

.venv-win32-python3.12\Scripts\activate.bat

macOS

source .venv-macos-python3.12/bin/activate

```

Cross-Platform Script Requirements

Pydantic V2 Best Practices

Use model_dump() instead of .dict()

```python

INCORRECT - Deprecated, will be removed

data = model.dict()

CORRECT - Pydantic V2 method

data = model.model_dump()

CORRECT - JSON serialization

json_str = model.model_dump_json()

CORRECT - Dictionary from JSON

doc = json.loads(model.model_dump_json())

```

Use model_config instead of Config class

```python

INCORRECT - Old style

class OldModel(BaseModel):

name: str

class Config:

arbitrary_types_allowed = True

CORRECT - New style

class NewModel(BaseModel):

name: str

model_config = {"arbitrary_types_allowed": True}

```

Use Field for defaults

```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))

```

Timezone-Aware Datetimes

**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

```

ArangoDB Cursor Handling

Small Result Sets

```python

if isinstance(results, Cursor):

result_list = [doc for doc in results]

result_data["results"] = result_list

else:

result_data["results"] = results

```

Large Collections

```python

Option 1: Cap maximum results

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

Option 2: Stream processing

processed = 0

for doc in cursor:

process_document(doc)

processed += 1

if processed % 10000 == 0:

logging.info(f"Processed {processed} documents")

```

MCP ArangoDB Tools

Direct database access via MCP:

Use these to verify database state and diagnose issues.

Code Style Guidelines

Import Organization

```python

Standard library

import sys

import logging

Third-party

from pydantic import BaseModel, Field

Local

from dbfacade.models import MyModel

```

Naming Conventions

Type Hints

```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

```

Modern Python Features

Use Python 3.13+ features:

```python

Match/case statements

match status:

case "active":

return process_active()

case "pending":

return process_pending()

case _:

return handle_unknown()

```

Common Commands

```bash

Run tests

pytest tests/

Format code

black .

Lint code

ruff check .

flake8 .

```

When to Use Fail-Stop

**Use sys.exit(1) for:**

**Use exceptions for:**

Step-by-Step Development Workflow

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