fastapi-mongo-base 1.5.2__tar.gz → 1.5.3__tar.gz

{fastapi_mongo_base-1.5.2/src/fastapi_mongo_base.egg-info → fastapi_mongo_base-1.5.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-mongo-base
-Version: 1.5.2
+Version: 1.5.3
 Summary: A simple boilerplate application, including models and schemas and abstract router, for FastAPI with MongoDB
 Author-email: Mahdi Kiani <mahdikiany@gmail.com>
 Maintainer-email: Mahdi Kiani <mahdikiany@gmail.com>

{fastapi_mongo_base-1.5.2 → fastapi_mongo_base-1.5.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "fastapi-mongo-base"
-version = "1.5.2"
+version = "1.5.3"
 description = "A simple boilerplate application, including models and schemas and abstract router, for FastAPI with MongoDB"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -103,7 +103,7 @@ select = [
   "ERA", # remove commented code
   "RUF", # ruff-specific improvements
 ]
-per-file-ignores = { "tests/*" = ["G004", "S101"], "server/db.py" = ["TRY"] }
+per-file-ignores = { "tests/*" = ["G004", "S101", "ASYNC", "D", "ANN", "N806", "E501", "ERA001", "RUF029", "TRY300"], "server/db.py" = ["TRY"] }
 ignore = ["TRY003", "COM812", "B008", "D202", "D203", "D209", "D212", "D413"]
 
 [tool.ruff.format]

{fastapi_mongo_base-1.5.2 → fastapi_mongo_base-1.5.3}/pytest.ini

@@ -11,7 +11,7 @@ addopts =
     --cov=src
     --cov-report=term-missing
     --cov-report=html
-    --cov-fail-under=50
+    --cov-fail-under=85
 
 filterwarnings =
     ignore:.*model_fields.*:DeprecationWarning

{fastapi_mongo_base-1.5.2 → fastapi_mongo_base-1.5.3}/src/fastapi_mongo_base/errors/__init__.py

@@ -9,18 +9,6 @@ from .handlers import (
     pydantic_exception_handler,
     request_validation_exception_handler,
 )
-from .http import (
-    AlreadyExistsError,
-    BadRequestError,
-    ConflictError,
-    ForbiddenError,
-    GoneError,
-    LockedError,
-    NotFoundError,
-    PaymentRequiredError,
-    ServerError,
-    UnauthorizedError,
-)
 from .mongodb import (
     DocumentAlreadyExistsError,
     DocumentDuplicateKeyError,
@@ -51,6 +39,25 @@ from .responses import (
     ValidationReason,
     setup_openapi_errors,
 )
+from .status import (
+    AlreadyExistsError,
+    BadRequestError,
+    ConflictError,
+    FeatureNotImplementedError,
+    ForbiddenError,
+    GatewayTimeoutError,
+    GoneError,
+    LockedError,
+    MethodNotAllowedError,
+    NotFoundError,
+    PaymentRequiredError,
+    PreconditionFailedError,
+    ServerError,
+    ServiceUnavailableError,
+    TeaPotError,
+    TooManyRequestsError,
+    UnauthorizedError,
+)
 
 __all__ = [
     "COMMON_ERROR_RESPONSES",
@@ -63,10 +70,13 @@ __all__ = [
     "DocumentAlreadyExistsError",
     "DocumentDuplicateKeyError",
     "DocumentNotFoundError",
+    "FeatureNotImplementedError",
     "ForbiddenError",
+    "GatewayTimeoutError",
     "GoneError",
     "InternalErrorResponseModel",
     "LockedError",
+    "MethodNotAllowedError",
     "MongoDBConnectionError",
     "MongoDBError",
     "MongoDBTimeoutError",
@@ -74,6 +84,7 @@ __all__ = [
     "MultipleDocumentsFoundError",
     "NotFoundError",
     "PaymentRequiredError",
+    "PreconditionFailedError",
     "RedisConnectionError",
     "ResourceAlreadyExistsError",
     "ResourceConflictError",
@@ -83,6 +94,9 @@ __all__ = [
     "ResourceNotFoundError",
     "ResourcePaymentRequiredError",
     "ServerError",
+    "ServiceUnavailableError",
+    "TeaPotError",
+    "TooManyRequestsError",
     "UnauthorizedError",
     "ValidationErrorResponseModel",
     "ValidationReason",

{fastapi_mongo_base-1.5.2 → fastapi_mongo_base-1.5.3}/src/fastapi_mongo_base/errors/exceptions.py

@@ -1,7 +1,7 @@
 """Exceptions for the fastapi-mongo-base package."""
 
 from .base import BaseHTTPException
-from .http import (
+from .status import (
     AlreadyExistsError,
     BadRequestError,
     ConflictError,

{fastapi_mongo_base-1.5.2 → fastapi_mongo_base-1.5.3}/src/fastapi_mongo_base/errors/mongodb.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 from typing import TYPE_CHECKING
 
 from .base import BaseHTTPException
-from .http import (
+from .status import (
     AlreadyExistsError,
     NotFoundError,
 )

{fastapi_mongo_base-1.5.2 → fastapi_mongo_base-1.5.3}/src/fastapi_mongo_base/errors/resource.py

@@ -1,6 +1,6 @@
 """Backward compatibility aliases for HTTP client errors."""
 
-from .http import (
+from .status import (
     AlreadyExistsError,
     ConflictError,
     ForbiddenError,

{fastapi_mongo_base-1.5.2 → fastapi_mongo_base-1.5.3}/src/fastapi_mongo_base/errors/responses.py

@@ -4,6 +4,9 @@ import fastapi
 from fastapi.openapi.utils import get_openapi
 from pydantic import BaseModel, ConfigDict, Field
 
+from . import status as _status_errors
+from .base import BaseHTTPException
+
 
 class APIErrorResponseModel(BaseModel):
     """Structured error response for BaseHTTPException handlers."""
@@ -43,47 +46,37 @@ class InternalErrorResponseModel(BaseModel):
     error: str = "Exception"
 
 
+def _status_error_descriptions() -> dict[int, str]:
+    """Map HTTP status codes to OpenAPI descriptions from status exceptions."""
+    descriptions: dict[int, set[str]] = {}
+    for name in dir(_status_errors):
+        exc_type = getattr(_status_errors, name)
+        if not (
+            isinstance(exc_type, type)
+            and issubclass(exc_type, BaseHTTPException)
+        ):
+            continue
+        code = exc_type.status_code
+        if not isinstance(code, int):
+            continue
+        label = exc_type.message_en or name
+        descriptions.setdefault(code, set()).add(label)
+    return {
+        code: " / ".join(sorted(labels))
+        for code, labels in descriptions.items()
+    }
+
+
 COMMON_ERROR_RESPONSES: dict[int, dict[str, object]] = {
-    400: {
-        "model": APIErrorResponseModel,
-        "description": "Bad request",
-    },
-    401: {
-        "model": APIErrorResponseModel,
-        "description": "Unauthorized",
-    },
-    402: {
-        "model": APIErrorResponseModel,
-        "description": "Payment required",
-    },
-    403: {
+    code: {
         "model": APIErrorResponseModel,
-        "description": "Forbidden",
-    },
-    404: {
-        "model": APIErrorResponseModel,
-        "description": "Not found",
-    },
-    409: {
-        "model": APIErrorResponseModel,
-        "description": "Conflict",
-    },
-    410: {
-        "model": APIErrorResponseModel,
-        "description": "Gone",
-    },
-    422: {
-        "model": ValidationErrorResponseModel,
-        "description": "Validation error",
-    },
-    423: {
-        "model": APIErrorResponseModel,
-        "description": "Locked",
-    },
-    500: {
-        "model": APIErrorResponseModel,
-        "description": "Internal server error",
-    },
+        "description": description,
+    }
+    for code, description in _status_error_descriptions().items()
+}
+COMMON_ERROR_RESPONSES[422] = {
+    "model": ValidationErrorResponseModel,
+    "description": "Validation error",
 }
 
 

fastapi_mongo_base-1.5.3/src/fastapi_mongo_base/errors/status.py

@@ -0,0 +1,211 @@
+"""HTTP status-code API error exceptions."""
+
+from .base import BaseHTTPException
+
+
+class BadRequestError(BaseHTTPException):
+    """Raised when a request is invalid."""
+
+    status_code = 400
+    error_code = "bad_request"
+    message_en = "Bad request"
+    message_fa = "درخواست نامعتبر"
+
+
+try:
+    from usso.exceptions import PermissionDenied as _USSOPermissionDenied
+    from usso.exceptions import USSOException as _USSOException
+
+    class UnauthorizedError(BaseHTTPException, _USSOException):
+        """Raised when a request is unauthorized (when USSO is installed)."""
+
+        status_code = 401
+        error_code = "unauthorized"
+        message_en = "Unauthorized"
+        message_fa = "لطفا وارد حساب کاربری خود شوید."
+
+        def __init__(
+            self,
+            error_code: str | None = None,
+            detail: str | None = None,
+            message: dict | None = None,
+            **kwargs: object,
+        ) -> None:
+            """Initialize with package HTTP error fields (USSO-compatible)."""
+            BaseHTTPException.__init__(
+                self,
+                status_code=self.status_code,
+                error_code=error_code or self.error_code,
+                detail=detail,
+                message=message,
+                **kwargs,
+            )
+
+    class ForbiddenError(BaseHTTPException, _USSOPermissionDenied):
+        """Raised when a request is forbidden (when USSO is installed)."""
+
+        status_code = 403
+        error_code = "permission_denied"
+        message_en = "Permission denied"
+        message_fa = "دسترسی غیر مجاز"
+
+        def __init__(
+            self,
+            error_code: str | None = None,
+            detail: str | None = None,
+            message: dict | None = None,
+            **kwargs: object,
+        ) -> None:
+            """Initialize with package HTTP error fields (USSO-compatible)."""
+            BaseHTTPException.__init__(
+                self,
+                status_code=self.status_code,
+                error_code=error_code or self.error_code,
+                detail=detail,
+                message=message,
+                **kwargs,
+            )
+
+except ImportError:
+
+    class UnauthorizedError(BaseHTTPException):
+        """Raised when a request is unauthorized."""
+
+        status_code = 401
+        error_code = "unauthorized"
+        message_en = "Unauthorized"
+        message_fa = "لطفا وارد حساب کاربری خود شوید."
+
+    class ForbiddenError(BaseHTTPException):
+        """Raised when a request is forbidden."""
+
+        status_code = 403
+        error_code = "permission_denied"
+        message_en = "Permission denied"
+        message_fa = "دسترسی غیر مجاز"
+
+
+class PaymentRequiredError(BaseHTTPException):
+    """Raised when payment is required before access."""
+
+    status_code = 402
+    error_code = "resource_payment_required"
+    message_en = "Resource payment required"
+    message_fa = "برای دسترسی، پرداخت لازم است"
+
+
+class NotFoundError(BaseHTTPException):
+    """Raised when a requested entity is not found."""
+
+    status_code = 404
+    error_code = "resource_not_found"
+    message_en = "Resource not found"
+    message_fa = "نمونه یافت نشد"
+
+
+class MethodNotAllowedError(BaseHTTPException):
+    """Raised when a request method is not allowed."""
+
+    status_code = 405
+    error_code = "method_not_allowed"
+    message_en = "Method not allowed"
+    message_fa = "متد درخواستی مجاز نیست"
+
+
+class AlreadyExistsError(BaseHTTPException):
+    """Raised when an entity already exists."""
+
+    status_code = 409
+    error_code = "resource_already_exists"
+    message_en = "Resource already exists"
+    message_fa = "نمونه‌ی مشابه وجود دارد"
+
+
+class ConflictError(BaseHTTPException):
+    """Raised when a request conflicts with current state."""
+
+    status_code = 409
+    error_code = "resource_conflict"
+    message_en = "Resource conflict"
+    message_fa = "اطلاعات ارسال شده تداخل دارد"
+
+
+class GoneError(BaseHTTPException):
+    """Raised when an entity is no longer available."""
+
+    status_code = 410
+    error_code = "resource_gone"
+    message_en = "Resource gone"
+    message_fa = "در دسترس نیست"
+
+
+class PreconditionFailedError(BaseHTTPException):
+    """Raised when a precondition failed."""
+
+    status_code = 412
+    error_code = "precondition_failed"
+    message_en = "Precondition failed"
+    message_fa = "پیش‌شرط نقض شده است"
+
+
+class TeaPotError(BaseHTTPException):
+    """Raised when a request is a teapot."""
+
+    status_code = 418
+    error_code = "teapot"
+    message_en = "I'm a teapot"
+    message_fa = "من نمی‌خواهم پاسخ بدهم!"
+
+
+class LockedError(BaseHTTPException):
+    """Raised when an entity is locked."""
+
+    status_code = 423
+    error_code = "resource_locked"
+    message_en = "Resource locked"
+    message_fa = "قفل شده است"
+
+
+class TooManyRequestsError(BaseHTTPException):
+    """Raised when a request is made too many times."""
+
+    status_code = 429
+    error_code = "too_many_requests"
+    message_en = "Too many requests"
+    message_fa = "درخواست‌های همزمان زیادی ارسال شده است."
+
+
+class ServerError(BaseHTTPException):
+    """Base exception for application API errors."""
+
+    status_code: int = 500
+    error_code: str = "internal_server_error"
+    message_en: str = "Internal server error"
+    message_fa: str | None = "خطای داخلی سرور رخ داده است"
+
+
+class FeatureNotImplementedError(BaseHTTPException):
+    """Raised when a requested feature is not implemented (HTTP 501)."""
+
+    status_code = 501
+    error_code = "not_implemented"
+    message_en = "Not implemented"
+    message_fa = "این قابلیت هنوز فعال نشده است."
+
+
+class ServiceUnavailableError(BaseHTTPException):
+    """Raised when a service is unavailable."""
+
+    status_code = 503
+    error_code = "service_unavailable"
+    message_en = "Service unavailable"
+    message_fa = "سرویس در دسترس نیست."
+
+
+class GatewayTimeoutError(BaseHTTPException):
+    """Raised when a request times out."""
+
+    status_code = 504
+    error_code = "gateway_timeout"
+    message_en = "Gateway timeout"
+    message_fa = "درگاه در دسترس نیست."

{fastapi_mongo_base-1.5.2 → fastapi_mongo_base-1.5.3}/src/fastapi_mongo_base/schemas.py

@@ -103,6 +103,24 @@ class BaseEntitySchema(BaseModel):
         ])
 
 
+class OwnerOverrideCreateMixin(BaseModel):
+    """Optional user owner override on create payloads (service/admin)."""
+
+    user_id: str | None = Field(
+        None,
+        description="Target user id (omitted = authenticated user)",
+    )
+
+
+class OwnedOverrideCreateMixin(BaseModel):
+    """Optional owner override on create payloads (service/admin)."""
+
+    owner_id: str | None = Field(
+        None,
+        description="Target owner id (omitted = authenticated owner)",
+    )
+
+
 class UserOwnedEntitySchema(BaseEntitySchema):
     """Schema for entities owned by a user."""
 

fastapi_mongo_base-1.5.3/src/fastapi_mongo_base/utils/usso/__init__.py

@@ -0,0 +1,15 @@
+"""USSO integration helpers (optional ``[usso]`` extra)."""
+
+from .principals import (
+    SERVICE_SUB_TYPES,
+    is_service_auth,
+    is_service_request,
+    is_service_user,
+)
+
+__all__ = [
+    "SERVICE_SUB_TYPES",
+    "is_service_auth",
+    "is_service_request",
+    "is_service_user",
+]

fastapi_mongo_base-1.5.3/src/fastapi_mongo_base/utils/usso/principals.py

@@ -0,0 +1,60 @@
+"""Detect USSO service principals (API key, agent) on requests and claims."""
+
+from collections.abc import Mapping
+from typing import Protocol, runtime_checkable
+
+SERVICE_SUB_TYPES = frozenset({"agent", "api_key"})
+
+
+@runtime_checkable
+class RequestWithHeaders(Protocol):
+    """Minimal request interface needed to identify API-key requests."""
+
+    headers: Mapping[str, str]
+
+
+@runtime_checkable
+class UserWithClaims(Protocol):
+    """Minimal user interface for USSO-style service subject types."""
+
+    claims: Mapping[str, object] | None
+
+
+def _header_api_key(headers: Mapping[str, str]) -> str | None:
+    for name in ("x-api-key", "X-Api-Key", "X-API-Key", "X_API_KEY"):
+        value = headers.get(name)
+        if value:
+            return str(value)
+    return None
+
+
+def is_service_request(request: object) -> bool:
+    """Return True when the request authenticated via an API key header."""
+    if not isinstance(request, RequestWithHeaders):
+        msg = "request must expose headers mapping"
+        raise TypeError(msg)
+    return _header_api_key(request.headers) is not None
+
+
+def is_service_user(user: object) -> bool:
+    """
+    Return True when ``user`` is a service principal (agent or API key).
+
+    Relies on USSO ``sub_type`` claim values ``agent`` and ``api_key``.
+    """
+    claims = getattr(user, "claims", None)
+    if not claims:
+        return False
+    sub_type = claims.get("sub_type")
+    return sub_type in SERVICE_SUB_TYPES
+
+
+def is_service_auth(
+    *,
+    request: object | None = None,
+    user: object | None = None,
+) -> bool:
+    """Return True when either the request or user indicates service auth."""
+    if request is not None and is_service_request(request):
+        return True
+    return bool(user is not None and is_service_user(user))