edocapi 0.0.2__py3-none-any.whl

edocapi/__init__.py

@@ -0,0 +1,49 @@
+"""
+eDocAPI - A lightweight Python framework for building document-processing
+and document-automation APIs.
+
+Simple API for the developer. Powerful document processing underneath.
+
+Author: EMMANUEL EMMANUEL ETIM <emmanuel224etim089@gmail.com>
+Repository: https://github.com/emmanuelemmanueletim/edocApi
+"""
+
+__version__ = "0.0.2"
+__author__ = "EMMANUEL EMMANUEL ETIM"
+__author_email__ = "emmanuel224etim089@gmail.com"
+__license__ = "MIT"
+__copyright__ = "Copyright (c) 2026 EMMANUEL EMMANUEL ETIM"
+__url__ = "https://github.com/emmanuelemmanueletim/edocApi"
+
+from edocapi.app import App
+from edocapi.document import Document
+from edocapi.exceptions import (
+    EdocAPIError,
+    UnsupportedFileType,
+    InvalidDocument,
+    FileTooLarge,
+    FileNotFound,
+    ConversionError,
+    ProcessingError,
+    ValidationError,
+)
+from edocapi.responses import FileResponse, JSONResponse
+
+# Ensure processors are registered on import
+import edocapi.processors  # noqa: F401
+
+__all__ = [
+    "App",
+    "Document",
+    "FileResponse",
+    "JSONResponse",
+    "EdocAPIError",
+    "UnsupportedFileType",
+    "InvalidDocument",
+    "FileTooLarge",
+    "FileNotFound",
+    "ConversionError",
+    "ProcessingError",
+    "ValidationError",
+    "__version__",
+]

edocapi/app.py

@@ -0,0 +1,255 @@
+"""eDocAPI application object built on Starlette."""
+
+from __future__ import annotations
+
+import inspect
+import logging
+from typing import Any, Callable, Sequence
+
+from starlette.applications import Starlette
+from starlette.requests import Request
+from starlette.responses import Response
+from starlette.routing import Route
+from starlette.middleware import Middleware
+from starlette.middleware.exceptions import ExceptionMiddleware
+
+from edocapi.config import Config
+from edocapi.exceptions import EdocAPIError
+from edocapi.responses import JSONResponse, make_error_response
+from edocapi.storage.temporary import TemporaryStorage
+
+logger = logging.getLogger("edocapi")
+
+
+class App:
+    """Main eDocAPI application.
+
+    Example::
+
+        from edocapi import App, Document
+
+        app = App()
+
+        @app.post("/convert")
+        def convert(file):
+            return Document(file).to_pdf()
+    """
+
+    def __init__(
+        self,
+        debug: bool = False,
+        max_file_size: str | int = "10MB",
+        temp_dir: str | None = None,
+        **kwargs: Any,
+    ) -> None:
+        self.config = Config.from_kwargs(
+            debug=debug,
+            max_file_size=max_file_size,
+            temp_dir=temp_dir,
+            **kwargs,
+        )
+        self._routes: list[Route] = []
+        self._temp_storage = TemporaryStorage(self.config.temp_dir)
+        self._starlette: Starlette | None = None
+
+        # Configure logging
+        level = logging.DEBUG if self.config.debug else logging.INFO
+        logging.basicConfig(
+            level=level,
+            format="%(levelname)-5s  %(name)s  %(message)s",
+        )
+
+    # ------------------------------------------------------------------
+    # Routing helpers
+    # ------------------------------------------------------------------
+
+    def _add_route(
+        self,
+        path: str,
+        endpoint: Callable,
+        methods: Sequence[str],
+    ) -> None:
+        """Register a route, wrapping the endpoint to inject request context."""
+
+        async def wrapper(request: Request) -> Response:
+            return await self._dispatch(endpoint, request)
+
+        self._routes.append(Route(path, endpoint=wrapper, methods=list(methods)))
+
+    def get(self, path: str) -> Callable:
+        def decorator(func: Callable) -> Callable:
+            self._add_route(path, func, ["GET"])
+            return func
+
+        return decorator
+
+    def post(self, path: str) -> Callable:
+        def decorator(func: Callable) -> Callable:
+            self._add_route(path, func, ["POST"])
+            return func
+
+        return decorator
+
+    def put(self, path: str) -> Callable:
+        def decorator(func: Callable) -> Callable:
+            self._add_route(path, func, ["PUT"])
+            return func
+
+        return decorator
+
+    def delete(self, path: str) -> Callable:
+        def decorator(func: Callable) -> Callable:
+            self._add_route(path, func, ["DELETE"])
+            return func
+
+        return decorator
+
+    def route(self, path: str, methods: Sequence[str] | None = None) -> Callable:
+        methods = methods or ["GET"]
+
+        def decorator(func: Callable) -> Callable:
+            self._add_route(path, func, methods)
+            return func
+
+        return decorator
+
+    # ------------------------------------------------------------------
+    # Request dispatch
+    # ------------------------------------------------------------------
+
+    async def _dispatch(self, endpoint: Callable, request: Request) -> Response:
+        """Call the user endpoint, injecting file uploads and handling results."""
+        from edocapi.document import Document
+        from edocapi.files import extract_uploads
+
+        try:
+            # Prepare keyword arguments for the endpoint
+            sig = inspect.signature(endpoint)
+            kwargs: dict[str, Any] = {}
+
+            # Inject uploads when the parameter is named 'file' or 'files'
+            uploads = None
+            if any(p in sig.parameters for p in ("file", "files")):
+                uploads = await extract_uploads(
+                    request,
+                    max_size=self.config.max_file_size,
+                    max_files=self.config.max_files,
+                    temp_storage=self._temp_storage,
+                )
+
+            for name, param in sig.parameters.items():
+                if name == "request":
+                    kwargs["request"] = request
+                elif name == "file":
+                    if not uploads:
+                        raise EdocAPIError("No file uploaded.")
+                    kwargs["file"] = uploads[0]
+                elif name == "files":
+                    if not uploads:
+                        raise EdocAPIError("No files uploaded.")
+                    kwargs["files"] = uploads
+                elif name in request.path_params:
+                    kwargs[name] = request.path_params[name]
+                elif param.default is not inspect.Parameter.empty:
+                    continue
+                else:
+                    # Try query params as fallback
+                    if name in request.query_params:
+                        kwargs[name] = request.query_params[name]
+
+            # Call the endpoint (sync or async)
+            if inspect.iscoroutinefunction(endpoint):
+                result = await endpoint(**kwargs)
+            else:
+                result = endpoint(**kwargs)
+
+            return self._make_response(result)
+
+        except EdocAPIError as exc:
+            status = 400
+            if exc.__class__.__name__ == "FileTooLarge":
+                status = 413
+            logger.warning("eDocAPI error: %s", exc)
+            return make_error_response(exc, status_code=status, debug=self.config.debug)
+        except Exception as exc:
+            logger.exception("Unhandled error in endpoint")
+            return make_error_response(
+                exc, status_code=500, debug=self.config.debug
+            )
+
+    def _make_response(self, result: Any) -> Response:
+        """Convert an endpoint return value into a Starlette Response."""
+        from edocapi.document import Document
+        from edocapi.responses import FileResponse, JSONResponse
+        from pathlib import Path
+
+        if result is None:
+            return JSONResponse({"success": True})
+
+        if isinstance(result, Response):
+            return result
+
+        if isinstance(result, Document):
+            # Document returned directly  treat as file response
+            path = result.path
+            return FileResponse(
+                path,
+                filename=path.name,
+                background=self._cleanup_callback(path, result._temp),
+            )
+
+        if isinstance(result, Path):
+            return FileResponse(
+                result,
+                filename=result.name,
+                background=self._cleanup_callback(result, self._temp_storage),
+            )
+
+        if isinstance(result, (dict, list)):
+            return JSONResponse(result)
+
+        if isinstance(result, str):
+            return JSONResponse({"text": result})
+
+        if isinstance(result, bytes):
+            return Response(content=result, media_type="application/octet-stream")
+
+        # Fallback
+        return JSONResponse({"result": str(result)})
+
+    @staticmethod
+    def _cleanup_callback(path: Path, storage: TemporaryStorage):
+        """Clean up managed output files after Starlette finishes streaming."""
+        from starlette.background import BackgroundTask
+
+        return BackgroundTask(storage.discard, path) if path in storage._files else None
+
+    # ------------------------------------------------------------------
+    # ASGI interface
+    # ------------------------------------------------------------------
+
+    @property
+    def asgi(self) -> Starlette:
+        """Return the underlying Starlette ASGI application."""
+        if self._starlette is None:
+            self._starlette = Starlette(
+                debug=self.config.debug,
+                routes=self._routes,
+                exception_handlers={
+                    Exception: self._global_exception_handler,
+                },
+            )
+        return self._starlette
+
+    async def _global_exception_handler(
+        self, request: Request, exc: Exception
+    ) -> Response:
+        logger.exception("Unhandled ASGI exception")
+        return make_error_response(exc, status_code=500, debug=self.config.debug)
+
+    async def __call__(self, scope: dict, receive: Callable, send: Callable) -> None:
+        """ASGI callable  delegates to the Starlette app."""
+        await self.asgi(scope, receive, send)
+
+    def __repr__(self) -> str:
+        return f"<eDocAPI App debug={self.config.debug}>"

edocapi/cli/__init__.py

@@ -0,0 +1,3 @@
+from edocapi.cli.main import main
+
+__all__ = ["main"]

edocapi/cli/main.py

@@ -0,0 +1,94 @@
+"""eDocAPI command-line interface."""
+
+from __future__ import annotations
+
+import argparse
+import importlib
+import sys
+from pathlib import Path
+
+from edocapi import __author__, __version__
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = argparse.ArgumentParser(
+        prog="edocapi",
+        description="eDocAPI - lightweight document-processing API framework",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"eDocAPI {__version__} (by {__author__})",
+    )
+
+    sub = parser.add_subparsers(dest="command")
+
+    # edocapi run
+    run_parser = sub.add_parser("run", help="Start the ASGI server")
+    run_parser.add_argument(
+        "app",
+        nargs="?",
+        default="main:app",
+        help="Application import path (default: main:app)",
+    )
+    run_parser.add_argument(
+        "--host",
+        default="0.0.0.0",
+        help="Bind host (default: 0.0.0.0)",
+    )
+    run_parser.add_argument(
+        "--port",
+        type=int,
+        default=8000,
+        help="Bind port (default: 8000)",
+    )
+    run_parser.add_argument(
+        "--reload",
+        action="store_true",
+        help="Enable auto-reload on code changes",
+    )
+
+    args = parser.parse_args(argv)
+
+    if args.command is None:
+        parser.print_help()
+        sys.exit(0)
+
+    if args.command == "run":
+        _run_server(args)
+
+
+def _run_server(args: argparse.Namespace) -> None:
+    try:
+        import uvicorn
+    except ImportError:
+        print(
+            "uvicorn is required to run the development server.\n"
+            "Install with: pip install 'uvicorn[standard]'",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    module_str, _, attr = args.app.partition(":")
+    if not attr:
+        attr = "app"
+
+    print(f"eDocAPI v{__version__}")
+    print(f"Author:      {__author__}")
+    print()
+    print(f"Application: {args.app}")
+    print(f"Server:      http://{args.host}:{args.port}")
+    print(f"Reload:      {'enabled' if args.reload else 'disabled'}")
+    print()
+
+    uvicorn.run(
+        f"{module_str}:{attr}",
+        host=args.host,
+        port=args.port,
+        reload=args.reload,
+        log_level="info",
+    )
+
+
+if __name__ == "__main__":
+    main()

edocapi/config.py

@@ -0,0 +1,76 @@
+"""Configuration helpers for eDocAPI."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+_SIZE_PATTERN = re.compile(r"^(\d+(?:\.\d+)?)\s*(B|KB|MB|GB)?$", re.IGNORECASE)
+
+_SIZE_MULTIPLIERS = {
+    "B": 1,
+    "KB": 1024,
+    "MB": 1024 ** 2,
+    "GB": 1024 ** 3,
+}
+
+
+def parse_size(value: str | int) -> int:
+    """Parse a human-readable size string into bytes.
+
+    Accepts integers (already in bytes) or strings such as:
+        "10MB", "25 MB", "100kb", "512"
+    """
+    if isinstance(value, int):
+        if value < 0:
+            raise ValueError("Size must be non-negative")
+        return value
+
+    value = value.strip()
+    match = _SIZE_PATTERN.match(value)
+    if not match:
+        raise ValueError(
+            f"Invalid size format: {value!r}. "
+            "Expected formats like '10MB', '25MB', '100KB'."
+        )
+
+    number = float(match.group(1))
+    unit = (match.group(2) or "B").upper()
+    return int(number * _SIZE_MULTIPLIERS[unit])
+
+
+@dataclass
+class Config:
+    """Runtime configuration for an eDocAPI application."""
+
+    debug: bool = False
+    max_file_size: int = 10 * 1024 * 1024  # 10 MB default
+    temp_dir: Path | None = None
+    max_files: int = 20
+
+    # Internal: extra options for future use
+    _extra: dict[str, Any] = field(default_factory=dict, repr=False)
+
+    def __post_init__(self) -> None:
+        if isinstance(self.max_file_size, str):
+            self.max_file_size = parse_size(self.max_file_size)
+        if self.temp_dir is not None and not isinstance(self.temp_dir, Path):
+            self.temp_dir = Path(self.temp_dir)
+
+    @classmethod
+    def from_kwargs(cls, **kwargs: Any) -> "Config":
+        """Build a Config from App() keyword arguments."""
+        known = {f.name for f in cls.__dataclass_fields__.values()}  # type: ignore
+        config_kwargs = {}
+        extra = {}
+        for key, value in kwargs.items():
+            if key in known and key != "_extra":
+                config_kwargs[key] = value
+            else:
+                extra[key] = value
+        cfg = cls(**config_kwargs)
+        cfg._extra = extra
+        return cfg