edocapi 0.0.2__py3-none-any.whl

edocapi/document.py

@@ -0,0 +1,290 @@
+"""Document abstraction for eDocAPI."""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Any, Sequence
+
+from edocapi.exceptions import ConversionError, InvalidDocument, ProcessingError
+from edocapi.processors.base import get_processor_class, list_supported_types
+from edocapi.storage.temporary import TemporaryStorage, safe_filename
+from edocapi.validation.files import validate_file
+
+logger = logging.getLogger("edocapi.document")
+
+
+class Document:
+    """High-level document abstraction.
+
+    Developers interact primarily with this class::
+
+        Document(file).to_pdf()
+        Document(file).extract_text()
+        Document.merge([f1, f2])
+    """
+
+    def __init__(
+        self,
+        source: Path | str | bytes | None = None,
+        *,
+        filename: str | None = None,
+        doc_type: str | None = None,
+        temp_storage: TemporaryStorage | None = None,
+        max_size: int = 50 * 1024 * 1024,
+    ) -> None:
+        self._temp = temp_storage or TemporaryStorage()
+        self._max_size = max_size
+        self._path: Path | None = None
+        self._type: str | None = doc_type
+        self._name: str | None = filename
+
+        if source is None:
+            return  # empty document (used by classmethods)
+
+        if isinstance(source, (str, Path)):
+            path = Path(source)
+            self._path = path
+            self._name = filename or path.name
+            self._type = validate_file(path, max_size=max_size)
+        elif isinstance(source, bytes):
+            if not filename:
+                raise InvalidDocument("filename is required when creating Document from bytes")
+            safe = safe_filename(filename)
+            path = self._temp.create_file(
+                suffix=Path(safe).suffix,
+                prefix="doc_",
+                content=source,
+            )
+            # Rename to keep original name
+            target = path.with_name(safe)
+            if target != path:
+                path.rename(target)
+                path = target
+            self._path = path
+            self._name = safe
+            self._type = validate_file(path, max_size=max_size)
+        else:
+            raise TypeError(
+                f"Unsupported source type for Document: {type(source)}. "
+                "Expected Path, str, or bytes."
+            )
+
+        logger.debug("Document created: %s (type=%s)", self._name, self._type)
+
+    # ------------------------------------------------------------------
+    # Properties
+    # ------------------------------------------------------------------
+
+    @property
+    def path(self) -> Path:
+        if self._path is None:
+            raise InvalidDocument("Document has no underlying file path.")
+        return self._path
+
+    @property
+    def name(self) -> str:
+        return self._name or (self._path.name if self._path else "unnamed")
+
+    @property
+    def size(self) -> int:
+        return self.path.stat().st_size
+
+    @property
+    def type(self) -> str:
+        return self._type or "unknown"
+
+    @property
+    def extension(self) -> str:
+        return self.path.suffix.lower()
+
+    @property
+    def mime_type(self) -> str:
+        import mimetypes
+
+        mime, _ = mimetypes.guess_type(self.name)
+        return mime or "application/octet-stream"
+
+    # ------------------------------------------------------------------
+    # Class constructors for in-memory content
+    # ------------------------------------------------------------------
+
+    @classmethod
+    def html(cls, content: str, *, filename: str = "document.html") -> "Document":
+        """Create a Document from an HTML string."""
+        data = content.encode("utf-8")
+        return cls(data, filename=filename, doc_type="html")
+
+    @classmethod
+    def markdown(cls, content: str, *, filename: str = "document.md") -> "Document":
+        """Create a Document from a Markdown string."""
+        data = content.encode("utf-8")
+        return cls(data, filename=filename, doc_type="markdown")
+
+    @classmethod
+    def text(cls, content: str, *, filename: str = "document.txt") -> "Document":
+        """Create a Document from plain text."""
+        data = content.encode("utf-8")
+        return cls(data, filename=filename, doc_type="txt")
+
+    # ------------------------------------------------------------------
+    # Processor access
+    # ------------------------------------------------------------------
+
+    def _processor(self):
+        cls = get_processor_class(self.type)
+        return cls(self.path, temp_storage=self._temp)
+
+    # ------------------------------------------------------------------
+    # Conversion methods
+    # ------------------------------------------------------------------
+
+    def to_pdf(self) -> "Document":
+        """Convert this document to PDF and return a new Document."""
+        logger.info("Converting %s -> PDF", self.name)
+        try:
+            out_path = self._processor().to_pdf()
+            return Document(out_path, temp_storage=self._temp)
+        except Exception as exc:
+            raise ConversionError(
+                str(exc), source=self.type, target="pdf"
+            ) from exc
+
+    def to_text(self) -> str:
+        """Extract plain text content."""
+        logger.info("Extracting text from %s", self.name)
+        try:
+            return self._processor().to_text()
+        except NotImplementedError:
+            raise ConversionError(
+                f"Text extraction not supported for type '{self.type}'.",
+                source=self.type,
+                target="txt",
+            )
+        except Exception as exc:
+            raise ConversionError(str(exc), source=self.type, target="txt") from exc
+
+    def extract_text(self) -> str:
+        """Alias for to_text()."""
+        return self.to_text()
+
+    def to_html(self) -> str:
+        """Convert to HTML string."""
+        logger.info("Converting %s -> HTML", self.name)
+        try:
+            return self._processor().to_html()
+        except NotImplementedError:
+            raise ConversionError(
+                f"HTML conversion not supported for type '{self.type}'.",
+                source=self.type,
+                target="html",
+            )
+        except Exception as exc:
+            raise ConversionError(str(exc), source=self.type, target="html") from exc
+
+    def to_images(self, *, format: str = "png") -> list["Document"]:
+        """Convert pages to images. Returns a list of Document objects."""
+        logger.info("Converting %s -> images (%s)", self.name, format)
+        try:
+            paths = self._processor().to_images(format=format)
+            return [Document(p, temp_storage=self._temp) for p in paths]
+        except NotImplementedError:
+            raise ConversionError(
+                f"Image conversion not supported for type '{self.type}'.",
+                source=self.type,
+                target="images",
+            )
+        except Exception as exc:
+            raise ConversionError(str(exc), source=self.type, target="images") from exc
+
+    # ------------------------------------------------------------------
+    # PDF operations (delegated when type is PDF)
+    # ------------------------------------------------------------------
+
+    def info(self) -> dict[str, Any]:
+        """Return document metadata / information."""
+        try:
+            return self._processor().info()
+        except Exception:
+            # Fallback basic info
+            return {
+                "filename": self.name,
+                "type": self.type,
+                "size": self.size,
+                "extension": self.extension,
+                "mime_type": self.mime_type,
+            }
+
+    def compress(self, level: str = "medium") -> "Document":
+        """Compress a PDF. Returns a new Document."""
+        if self.type != "pdf":
+            raise ProcessingError("compress() is only available for PDF documents.")
+        from edocapi.processors.pdf import PDFProcessor
+
+        proc = PDFProcessor(self.path, temp_storage=self._temp)
+        out = proc.compress(level=level)
+        return Document(out, temp_storage=self._temp)
+
+    def split(self) -> list["Document"]:
+        """Split a PDF into individual pages."""
+        if self.type != "pdf":
+            raise ProcessingError("split() is only available for PDF documents.")
+        from edocapi.processors.pdf import PDFProcessor
+
+        proc = PDFProcessor(self.path, temp_storage=self._temp)
+        paths = proc.split()
+        return [Document(p, temp_storage=self._temp) for p in paths]
+
+    def extract_pages(self, start: int, end: int | None = None) -> "Document":
+        """Extract a page range (1-based inclusive)."""
+        if self.type != "pdf":
+            raise ProcessingError("extract_pages() is only available for PDF documents.")
+        from edocapi.processors.pdf import PDFProcessor
+
+        proc = PDFProcessor(self.path, temp_storage=self._temp)
+        out = proc.extract_pages(start, end)
+        return Document(out, temp_storage=self._temp)
+
+    def rotate(self, degrees: int = 90, pages: Sequence[int] | None = None) -> "Document":
+        """Rotate pages (1-based). Default rotates all pages by 90 degrees."""
+        if self.type != "pdf":
+            raise ProcessingError("rotate() is only available for PDF documents.")
+        from edocapi.processors.pdf import PDFProcessor
+
+        proc = PDFProcessor(self.path, temp_storage=self._temp)
+        out = proc.rotate(degrees, pages=pages)
+        return Document(out, temp_storage=self._temp)
+
+    # ------------------------------------------------------------------
+    # Class-level operations
+    # ------------------------------------------------------------------
+
+    @classmethod
+    def merge(cls, files: Sequence[Path | str | "Document"]) -> "Document":
+        """Merge multiple PDF documents into one."""
+        from edocapi.processors.pdf import PDFProcessor
+
+        paths: list[Path] = []
+        for f in files:
+            if isinstance(f, Document):
+                paths.append(f.path)
+            else:
+                paths.append(Path(f))
+
+        if not paths:
+            raise ProcessingError("No files provided for merge.")
+
+        temp = TemporaryStorage()
+        out = PDFProcessor.merge(paths, temp_storage=temp)
+        return cls(out, temp_storage=temp)
+
+    # ------------------------------------------------------------------
+    # Utility
+    # ------------------------------------------------------------------
+
+    def __repr__(self) -> str:
+        return f"<Document name={self.name!r} type={self.type!r} size={self.size}>"
+
+    @staticmethod
+    def supported_types() -> list[str]:
+        return list_supported_types()

edocapi/exceptions.py

@@ -0,0 +1,104 @@
+"""eDocAPI exception hierarchy."""
+
+from __future__ import annotations
+
+
+class EdocAPIError(Exception):
+    """Base exception for all eDocAPI errors."""
+
+    def __init__(self, message: str = "An error occurred in eDocAPI.") -> None:
+        self.message = message
+        super().__init__(self.message)
+
+    def to_dict(self) -> dict:
+        return {
+            "error": self.__class__.__name__,
+            "message": self.message,
+        }
+
+
+class UnsupportedFileType(EdocAPIError):
+    """Raised when the uploaded or provided file type is not supported."""
+
+    def __init__(
+        self,
+        message: str = "The uploaded file type is not supported.",
+        *,
+        mime_type: str | None = None,
+        extension: str | None = None,
+    ) -> None:
+        if mime_type or extension:
+            details = []
+            if mime_type:
+                details.append(f"MIME type: {mime_type}")
+            if extension:
+                details.append(f"extension: {extension}")
+            message = f"{message} ({', '.join(details)})"
+        super().__init__(message)
+        self.mime_type = mime_type
+        self.extension = extension
+
+
+class InvalidDocument(EdocAPIError):
+    """Raised when a file cannot be parsed as a valid document."""
+
+    def __init__(self, message: str = "The file is not a valid document.") -> None:
+        super().__init__(message)
+
+
+class FileTooLarge(EdocAPIError):
+    """Raised when an uploaded file exceeds the configured size limit."""
+
+    def __init__(
+        self,
+        message: str = "The uploaded file exceeds the maximum allowed size.",
+        *,
+        size: int | None = None,
+        max_size: int | None = None,
+    ) -> None:
+        if size is not None and max_size is not None:
+            message = (
+                f"File size {size} bytes exceeds maximum allowed size "
+                f"of {max_size} bytes."
+            )
+        super().__init__(message)
+        self.size = size
+        self.max_size = max_size
+
+
+class FileNotFound(EdocAPIError):
+    """Raised when a required file cannot be found."""
+
+    def __init__(self, message: str = "The requested file was not found.") -> None:
+        super().__init__(message)
+
+
+class ConversionError(EdocAPIError):
+    """Raised when a document conversion fails."""
+
+    def __init__(
+        self,
+        message: str = "Document conversion failed.",
+        *,
+        source: str | None = None,
+        target: str | None = None,
+    ) -> None:
+        if source and target:
+            message = f"Failed to convert from {source} to {target}: {message}"
+        super().__init__(message)
+        self.source = source
+        self.target = target
+
+
+class ProcessingError(EdocAPIError):
+    """Raised when a document processing operation fails."""
+
+    def __init__(self, message: str = "Document processing failed.") -> None:
+        super().__init__(message)
+
+
+class ValidationError(EdocAPIError):
+    """Raised when file or input validation fails."""
+
+    def __init__(self, message: str = "Validation failed.") -> None:
+        super().__init__(message)

edocapi/files.py

@@ -0,0 +1,97 @@
+"""File upload helpers for eDocAPI."""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+import uuid
+from typing import Any
+
+from starlette.datastructures import UploadFile
+from starlette.requests import Request
+
+from edocapi.exceptions import FileTooLarge, ValidationError
+from edocapi.storage.temporary import TemporaryStorage
+from edocapi.validation.files import detect_type_from_bytes, validate_extension
+
+logger = logging.getLogger("edocapi.files")
+
+
+async def extract_uploads(
+    request: Request,
+    *,
+    max_size: int,
+    max_files: int = 20,
+    temp_storage: TemporaryStorage | None = None,
+) -> list[Path]:
+    """Extract and validate uploaded files from a multipart request.
+
+    Returns a list of paths to temporary files that contain the uploaded content.
+    """
+    content_type = request.headers.get("content-type", "")
+    if "multipart/form-data" not in content_type:
+        raise ValidationError(
+            "Expected multipart/form-data for file uploads. "
+            "Did you forget to set enctype='multipart/form-data'?"
+        )
+
+    form = await request.form()
+    uploads: list[Path] = []
+
+    # Collect all UploadFile instances (single 'file' or multiple 'files')
+    candidates: list[UploadFile] = []
+    for key in form:
+        value = form.getlist(key)
+        for item in value:
+            if isinstance(item, UploadFile):
+                candidates.append(item)
+
+    if not candidates:
+        raise ValidationError("No file part found in the request.")
+
+    if len(candidates) > max_files:
+        raise ValidationError(
+            f"Too many files uploaded ({len(candidates)}). Maximum is {max_files}."
+        )
+
+    storage = temp_storage or TemporaryStorage()
+
+    for upload in candidates:
+        filename = upload.filename or "unnamed"
+        path: Path | None = None
+        try:
+            safe_name = validate_extension(filename)
+            detected = bytearray()
+            path = storage.create_file(suffix=Path(safe_name).suffix, prefix="upload_")
+            size = 0
+            with path.open("wb") as destination:
+                while chunk := await upload.read(min(64 * 1024, max_size - size + 1)):
+                    size += len(chunk)
+                    if size > max_size:
+                        raise FileTooLarge(size=size, max_size=max_size)
+                    destination.write(chunk)
+                    if len(detected) < 4096:
+                        detected.extend(chunk[:4096 - len(detected)])
+
+            kind = detect_type_from_bytes(bytes(detected))
+            if kind is None and Path(safe_name).suffix.lower() not in {
+                ".txt", ".md", ".markdown", ".html", ".htm"
+            }:
+                raise ValidationError("Unable to determine a supported file type from content.")
+
+            named_path = path.with_name(f"{uuid.uuid4().hex}_{safe_name}")
+            path.rename(named_path)
+            storage._files.discard(path)
+            path = storage.register(named_path)
+
+            uploads.append(path)
+            logger.info("Document uploaded: %s (%d bytes)", safe_name, size)
+        except Exception:
+            # A rejected or partially written upload must not remain on disk.
+            if path is not None:
+                storage.discard(path)
+            raise
+        finally:
+            await upload.close()
+
+    return uploads

edocapi/processors/__init__.py

@@ -0,0 +1,16 @@
+"""Document processors  import side-effects register the processors."""
+
+from edocapi.processors.base import (
+    BaseProcessor,
+    get_processor_class,
+    list_supported_types,
+    register_processor,
+)
+from edocapi.processors import pdf, docx, html, markdown, image, txt  # noqa: F401
+
+__all__ = [
+    "BaseProcessor",
+    "get_processor_class",
+    "list_supported_types",
+    "register_processor",
+]

edocapi/processors/base.py

@@ -0,0 +1,101 @@
+"""Base processor and registry for eDocAPI document processors."""
+
+from __future__ import annotations
+
+import logging
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import Any, Type
+
+logger = logging.getLogger("edocapi.processors")
+
+
+class BaseProcessor(ABC):
+    """Abstract base class for format-specific document processors."""
+
+    # Formats this processor can handle as input (e.g. {"pdf"}, {"docx", "doc"})
+    supported_input_types: set[str] = set()
+
+    # Formats this processor can produce as output
+    supported_output_types: set[str] = set()
+
+    def __init__(self, path: Path, *, temp_storage: Any = None) -> None:
+        self.path = Path(path)
+        self.temp_storage = temp_storage
+
+    @abstractmethod
+    def to_pdf(self) -> Path:
+        """Convert the document to PDF. Returns path to the PDF file."""
+        ...
+
+    def to_text(self) -> str:
+        """Extract plain text from the document."""
+        raise NotImplementedError(
+            f"{self.__class__.__name__} does not support text extraction."
+        )
+
+    def to_html(self) -> str:
+        """Convert the document to HTML string."""
+        raise NotImplementedError(
+            f"{self.__class__.__name__} does not support HTML conversion."
+        )
+
+    def to_images(self, *, format: str = "png") -> list[Path]:
+        """Convert document pages to images. Returns list of image paths."""
+        raise NotImplementedError(
+            f"{self.__class__.__name__} does not support image conversion."
+        )
+
+    def info(self) -> dict[str, Any]:
+        """Return basic information about the document."""
+        stat = self.path.stat()
+        return {
+            "filename": self.path.name,
+            "type": next(iter(self.supported_input_types), "unknown"),
+            "size": stat.st_size,
+            "extension": self.path.suffix.lower(),
+        }
+
+    def extract_text(self) -> str:
+        """Alias for to_text() for clearer naming."""
+        return self.to_text()
+
+
+# ---------------------------------------------------------------------------
+# Processor registry
+# ---------------------------------------------------------------------------
+
+_REGISTRY: dict[str, Type[BaseProcessor]] = {}
+
+
+def register_processor(
+    *types: str,
+) -> callable:
+    """Decorator to register a processor for one or more input types."""
+
+    def decorator(cls: Type[BaseProcessor]) -> Type[BaseProcessor]:
+        for t in types:
+            key = t.lower().lstrip(".")
+            _REGISTRY[key] = cls
+            logger.debug("Registered processor %s for type %s", cls.__name__, key)
+        return cls
+
+    return decorator
+
+
+def get_processor_class(doc_type: str) -> Type[BaseProcessor]:
+    """Return the processor class for a given document type."""
+    key = doc_type.lower().lstrip(".")
+    if key not in _REGISTRY:
+        from edocapi.exceptions import UnsupportedFileType
+
+        raise UnsupportedFileType(
+            f"No processor registered for document type '{doc_type}'.",
+            extension=key,
+        )
+    return _REGISTRY[key]
+
+
+def list_supported_types() -> list[str]:
+    """Return a sorted list of currently supported input types."""
+    return sorted(_REGISTRY.keys())