svc-infra 0.1.595__py3-none-any.whl → 1.1.0__py3-none-any.whl

svc_infra/documents/add.py

@@ -0,0 +1,263 @@
+"""
+FastAPI integration for document management.
+
+Mounts document endpoints with authentication and storage backend integration.
+Uses svc-infra's dual router pattern for public/protected routes.
+
+Quick Start:
+    >>> from fastapi import FastAPI
+    >>> from svc_infra.documents import add_documents
+    >>>
+    >>> app = FastAPI()
+    >>> manager = add_documents(app)
+    >>>
+    >>> # Documents available at:
+    >>> # POST /documents/upload (protected)
+    >>> # GET /documents/{document_id} (protected)
+    >>> # GET /documents/list (protected)
+    >>> # DELETE /documents/{document_id} (protected)
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, cast
+
+from fastapi import HTTPException, Request, Response
+
+from svc_infra.documents.models import Document
+
+if TYPE_CHECKING:
+    from fastapi import FastAPI
+
+    from svc_infra.storage.base import StorageBackend
+
+    from .ease import DocumentManager
+
+
+def get_documents_manager(app: FastAPI) -> DocumentManager:
+    """
+    Dependency to get document manager from app state.
+
+    Args:
+        app: FastAPI application
+
+    Returns:
+        Document manager instance
+
+    Raises:
+        RuntimeError: If add_documents() has not been called
+    """
+    if not hasattr(app.state, "documents"):
+        raise RuntimeError("Documents not configured. Call add_documents(app) first.")
+
+    return cast("DocumentManager", app.state.documents)
+
+
+def add_documents(
+    app: FastAPI,
+    storage_backend: StorageBackend | None = None,
+    prefix: str = "/documents",
+    tags: list[str] | None = None,
+) -> DocumentManager:
+    """
+    Add document management endpoints to FastAPI app.
+
+    Mounts 4 endpoints:
+    1. POST /documents/upload - Upload new document
+    2. GET /documents/{document_id} - Get document metadata
+    3. GET /documents/list - List user's documents
+    4. DELETE /documents/{document_id} - Delete document
+
+    Args:
+        app: FastAPI application
+        storage_backend: Storage backend (auto-detected if None)
+        prefix: URL prefix for document endpoints (default: /documents)
+        tags: OpenAPI tags for documentation
+
+    Returns:
+        Document manager instance for programmatic access
+
+    Examples:
+        >>> from fastapi import FastAPI
+        >>> from svc_infra.documents import add_documents
+        >>>
+        >>> app = FastAPI()
+        >>> manager = add_documents(app)
+        >>>
+        >>> # Endpoints available at /documents/*
+        >>> # Use manager programmatically:
+        >>> doc = manager.upload("user_123", file_bytes, "file.pdf")
+
+    Notes:
+        - All routes require user authentication (uses dual router pattern)
+        - Stores manager on app.state.documents for route access
+        - Storage backend auto-detected from environment if not provided
+    """
+    from svc_infra.api.fastapi.dual.protected import user_router
+
+    from .ease import easy_documents
+
+    # Create manager with storage backend
+    manager = easy_documents(storage_backend)
+
+    # Store manager on app state
+    app.state.documents = manager
+
+    # Create protected router for document endpoints (requires user authentication)
+    router = user_router(prefix=prefix, tags=tags or ["Documents"])
+
+    # Route 1: Upload document
+    @router.post("/upload", response_model=Document)
+    async def upload_document(request: Request) -> Document:
+        """
+        Upload a document.
+
+        Args:
+            request: FastAPI request with form data
+                - user_id (required): User uploading the document
+                - file (required): File to upload
+                - Any additional fields become document metadata
+
+        Returns:
+            Document metadata with storage information
+
+        Examples:
+            ```bash
+            curl -X POST http://localhost:8000/documents/upload \\
+              -F "user_id=user_123" \\
+              -F "file=@contract.pdf" \\
+              -F "category=legal" \\
+              -F "year=2024"
+            ```
+        """
+        # Parse form data
+        form = await request.form()
+
+        # Extract required fields
+        user_id = form.get("user_id")
+        file = form.get("file")
+
+        if not user_id or not isinstance(user_id, str):
+            raise HTTPException(status_code=422, detail="user_id is required")
+
+        # NOTE: request.form() yields Starlette's UploadFile, not FastAPI's wrapper.
+        from starlette.datastructures import UploadFile as StarletteUploadFile
+
+        if not file or not isinstance(file, StarletteUploadFile):
+            raise HTTPException(status_code=422, detail="file is required")
+
+        # Read file content
+        file_content = await file.read()
+
+        # Build metadata from all other form fields
+        metadata = {}
+        for key, value in form.items():
+            if key not in ("user_id", "file"):
+                metadata[key] = value
+
+        # Upload document
+        doc = await manager.upload(
+            user_id=user_id,
+            file=file_content,
+            filename=file.filename or "unnamed",
+            metadata=metadata,
+            content_type=file.content_type,
+        )
+
+        return doc
+
+    # Route 2: List user's documents (must come before /{document_id} to avoid conflicts)
+    @router.get("/list")
+    async def list_user_documents(
+        user_id: str,
+        limit: int = 100,
+        offset: int = 0,
+    ) -> dict:
+        """
+        List user's documents with pagination.
+
+        Args:
+            user_id: User identifier
+            limit: Maximum number of documents (default: 100)
+            offset: Number of documents to skip (default: 0)
+
+        Returns:
+            Dict with "documents", "total", "limit", "offset" keys
+
+        Examples:
+            ```bash
+            # Get first page
+            curl "http://localhost:8000/documents/list?user_id=user_123&limit=20"
+
+            # Get second page
+            curl "http://localhost:8000/documents/list?user_id=user_123&limit=20&offset=20"
+            ```
+        """
+        # Get all docs for total count (before pagination)
+        all_docs = manager.list(user_id=user_id, limit=999999, offset=0)
+        total_count = len(all_docs)
+
+        # Get paginated docs
+        docs = manager.list(user_id=user_id, limit=limit, offset=offset)
+
+        return {
+            "documents": docs,
+            "total": total_count,
+            "limit": limit,
+            "offset": offset,
+        }
+
+    # Route 3: Get document metadata
+    @router.get("/{document_id}", response_model=Document)
+    async def get_document_metadata(document_id: str) -> Document:
+        """
+        Get document metadata.
+
+        Args:
+            document_id: Document identifier
+
+        Returns:
+            Document metadata
+
+        Raises:
+            HTTPException: 404 if document not found
+
+        Examples:
+            ```bash
+            curl http://localhost:8000/documents/doc_abc123
+            ```
+        """
+        doc = manager.get(document_id)
+        if not doc:
+            raise HTTPException(status_code=404, detail="Document not found")
+        return doc
+
+    # Route 4: Delete document
+    @router.delete("/{document_id}", status_code=204)
+    async def delete_document_route(document_id: str) -> Response:
+        """
+        Delete a document and its file content.
+
+        Args:
+            document_id: Document identifier
+
+        Returns:
+            204 No Content on success
+
+        Raises:
+            HTTPException: 404 if document not found
+
+        Examples:
+            ```bash
+            curl -X DELETE http://localhost:8000/documents/doc_abc123
+            ```
+        """
+        success = await manager.delete(document_id)
+        if not success:
+            raise HTTPException(status_code=404, detail="Document not found")
+        return Response(status_code=204)
+
+    # Mount router
+    app.include_router(router)
+
+    return manager

svc_infra/documents/ease.py

@@ -0,0 +1,233 @@
+"""
+Easy builder for document management.
+
+Provides a simple interface for document operations with automatic
+storage backend integration.
+
+Quick Start:
+    >>> from svc_infra.documents import easy_documents
+    >>>
+    >>> # Create manager with auto-detected storage
+    >>> manager = easy_documents()
+    >>>
+    >>> # Upload document
+    >>> doc = manager.upload(
+    ...     user_id="user_123",
+    ...     file=file_bytes,
+    ...     filename="document.pdf",
+    ...     metadata={"category": "legal"}
+    ... )
+    >>>
+    >>> # Download document
+    >>> file_data = manager.download(doc.id)
+    >>>
+    >>> # List user's documents
+    >>> docs = manager.list(user_id="user_123")
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from svc_infra.storage.base import StorageBackend
+
+    from .models import Document
+
+
+class DocumentManager:
+    """
+    Document manager for upload, download, and metadata operations.
+
+    This class provides a convenient interface for all document operations,
+    automatically handling storage backend integration.
+
+    Attributes:
+        storage: Storage backend instance (S3, local, memory)
+
+    Examples:
+        >>> from svc_infra.storage import easy_storage
+        >>> from svc_infra.documents import DocumentManager
+        >>>
+        >>> storage = easy_storage()
+        >>> manager = DocumentManager(storage)
+        >>>
+        >>> # Upload
+        >>> doc = manager.upload("user_123", file_bytes, "contract.pdf")
+        >>>
+        >>> # Download
+        >>> file_data = manager.download(doc.id)
+        >>>
+        >>> # List
+        >>> docs = manager.list("user_123")
+        >>>
+        >>> # Delete
+        >>> manager.delete(doc.id)
+    """
+
+    def __init__(self, storage: StorageBackend):
+        """
+        Initialize document manager.
+
+        Args:
+            storage: Storage backend instance
+        """
+        self.storage = storage
+
+    async def upload(
+        self,
+        user_id: str,
+        file: bytes,
+        filename: str,
+        metadata: dict | None = None,
+        content_type: str | None = None,
+    ) -> Document:
+        """
+        Upload a document.
+
+        Args:
+            user_id: User uploading the document
+            file: File content as bytes
+            filename: Original filename
+            metadata: Optional custom metadata
+            content_type: Optional MIME type
+
+        Returns:
+            Document with storage information
+
+        Examples:
+            >>> doc = await manager.upload(
+            ...     user_id="user_123",
+            ...     file=pdf_bytes,
+            ...     filename="contract.pdf",
+            ...     metadata={"category": "legal", "year": 2024}
+            ... )
+        """
+        from .storage import upload_document
+
+        return await upload_document(
+            storage=self.storage,
+            user_id=user_id,
+            file=file,
+            filename=filename,
+            metadata=metadata,
+            content_type=content_type,
+        )
+
+    async def download(self, document_id: str) -> bytes:
+        """
+        Download a document by ID.
+
+        Args:
+            document_id: Document identifier
+
+        Returns:
+            Document file content
+
+        Examples:
+            >>> file_data = await manager.download("doc_abc123")
+            >>> with open("file.pdf", "wb") as f:
+            ...     f.write(file_data)
+        """
+        from .storage import download_document
+
+        return await download_document(self.storage, document_id)
+
+    def get(self, document_id: str) -> Document | None:
+        """
+        Get document metadata by ID.
+
+        Args:
+            document_id: Document identifier
+
+        Returns:
+            Document metadata or None if not found
+
+        Examples:
+            >>> doc = manager.get("doc_abc123")
+            >>> if doc:
+            ...     print(doc.filename, doc.file_size)
+        """
+        from .storage import get_document
+
+        return get_document(document_id)
+
+    async def delete(self, document_id: str) -> bool:
+        """
+        Delete a document.
+
+        Args:
+            document_id: Document identifier
+
+        Returns:
+            True if deleted, False if not found
+
+        Examples:
+            >>> success = await manager.delete("doc_abc123")
+        """
+        from .storage import delete_document
+
+        return await delete_document(self.storage, document_id)
+
+    def list(
+        self,
+        user_id: str,
+        limit: int = 100,
+        offset: int = 0,
+    ) -> list[Document]:
+        """
+        List user's documents.
+
+        Args:
+            user_id: User identifier
+            limit: Maximum number of documents
+            offset: Number of documents to skip
+
+        Returns:
+            List of documents
+
+        Examples:
+            >>> # Get all documents
+            >>> docs = manager.list("user_123")
+            >>>
+            >>> # Paginated
+            >>> docs = manager.list("user_123", limit=20, offset=20)
+        """
+        from .storage import list_documents
+
+        return list_documents(user_id, limit, offset)
+
+
+def easy_documents(storage: StorageBackend | None = None) -> DocumentManager:
+    """
+    Create a document manager with auto-configured storage.
+
+    Args:
+        storage: Optional storage backend (auto-detected if not provided)
+
+    Returns:
+        Document manager instance
+
+    Examples:
+        >>> # Auto-detect storage from environment
+        >>> manager = easy_documents()
+        >>>
+        >>> # Explicit storage backend
+        >>> from svc_infra.storage import easy_storage
+        >>> storage = easy_storage(backend="s3")
+        >>> manager = easy_documents(storage)
+        >>>
+        >>> # Use the manager
+        >>> doc = manager.upload("user_123", file_bytes, "file.pdf")
+
+    Notes:
+        - If storage is None, uses easy_storage() to auto-detect backend
+        - Auto-detection checks for Railway, S3, GCS credentials
+        - Falls back to MemoryBackend if no credentials found
+    """
+    if storage is None:
+        from svc_infra.storage import easy_storage
+
+        storage = easy_storage()
+
+    return DocumentManager(storage)

svc_infra/documents/models.py

@@ -0,0 +1,114 @@
+"""
+Generic document models for file management.
+
+This module provides domain-agnostic document metadata models that work with
+any type of file (PDFs, images, videos, etc.). For domain-specific extensions
+(e.g., tax forms, medical records), see implementation examples in fin-infra.
+
+Quick Start:
+    >>> from svc_infra.documents import Document
+    >>>
+    >>> doc = Document(
+    ...     id="doc_abc123",
+    ...     user_id="user_123",
+    ...     filename="contract.pdf",
+    ...     file_size=524288,
+    ...     storage_path="documents/user_123/doc_abc123.pdf",
+    ...     content_type="application/pdf",
+    ...     metadata={"category": "legal", "year": 2024}
+    ... )
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class Document(BaseModel):
+    """
+    Generic document metadata and storage information.
+
+    This is a base model for any type of document. Domain-specific applications
+    should extend this model with additional fields as needed.
+
+    Attributes:
+        id: Unique document identifier (e.g., "doc_abc123")
+        user_id: User who owns/uploaded the document
+        filename: Original filename
+        file_size: File size in bytes
+        upload_date: When document was uploaded (UTC)
+        storage_path: Storage backend path/key
+        content_type: MIME type (e.g., "application/pdf", "image/jpeg")
+        checksum: Optional file checksum for integrity validation
+        metadata: Flexible metadata dictionary for custom fields
+
+    Examples:
+        >>> # Legal document
+        >>> doc = Document(
+        ...     id="doc_abc123",
+        ...     user_id="user_123",
+        ...     filename="employment_contract.pdf",
+        ...     file_size=524288,
+        ...     storage_path="documents/user_123/2024/legal/doc_abc123.pdf",
+        ...     content_type="application/pdf",
+        ...     metadata={"category": "legal", "type": "contract", "year": 2024}
+        ... )
+        >>>
+        >>> # Medical record
+        >>> doc = Document(
+        ...     id="doc_def456",
+        ...     user_id="patient_789",
+        ...     filename="lab_results.pdf",
+        ...     file_size=102400,
+        ...     storage_path="documents/patient_789/2024/medical/doc_def456.pdf",
+        ...     content_type="application/pdf",
+        ...     metadata={"category": "medical", "test_type": "blood_work", "date": "2024-11-18"}
+        ... )
+        >>>
+        >>> # Invoice
+        >>> doc = Document(
+        ...     id="doc_ghi789",
+        ...     user_id="company_456",
+        ...     filename="invoice_2024_11.pdf",
+        ...     file_size=256000,
+        ...     storage_path="documents/company_456/invoices/doc_ghi789.pdf",
+        ...     content_type="application/pdf",
+        ...     metadata={"category": "invoice", "amount": 1500.00, "month": "2024-11"}
+        ... )
+    """
+
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "id": "doc_abc123",
+                "user_id": "user_123",
+                "filename": "contract.pdf",
+                "file_size": 524288,
+                "upload_date": "2025-11-18T14:30:00Z",
+                "storage_path": "documents/user_123/2024/doc_abc123.pdf",
+                "content_type": "application/pdf",
+                "checksum": "sha256:abc123...",
+                "metadata": {"category": "legal", "year": 2024, "tags": ["important"]},
+            }
+        }
+    )
+
+    id: str = Field(..., description="Unique document identifier")
+    user_id: str = Field(..., description="User who owns this document")
+    filename: str = Field(..., description="Original filename")
+    file_size: int = Field(..., description="File size in bytes", ge=0)
+    upload_date: datetime = Field(
+        default_factory=datetime.utcnow, description="Upload timestamp (UTC)"
+    )
+    storage_path: str = Field(..., description="Storage backend path/key")
+    content_type: str = Field(..., description="MIME type (e.g., application/pdf)")
+    checksum: str | None = Field(
+        None, description="File checksum for integrity validation (e.g., sha256:...)"
+    )
+    metadata: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Flexible metadata for custom fields (category, tags, dates, etc.)",
+    )