nlbone 0.1.38__tar.gz → 0.3.0__tar.gz

{nlbone-0.1.38 → nlbone-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nlbone
-Version: 0.1.38
+Version: 0.3.0
 Summary: Backbone package for interfaces and infrastructure in Python projects
 Author-email: Amir Hosein Kahkbazzadeh <a.khakbazzadeh@gmail.com>
 License: MIT

{nlbone-0.1.38 → nlbone-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "nlbone"
-version = "0.1.38"
+version = "0.3.0"
 description = "Backbone package for interfaces and infrastructure in Python projects"
 readme = "README.md"
 requires-python = ">=3.10"

{nlbone-0.1.38 → nlbone-0.3.0}/src/nlbone/adapters/db/__init__.py

@@ -1,2 +1,3 @@
 from .sqlalchemy.engine import init_async_engine, async_session, async_ping, init_sync_engine, sync_session, sync_ping
-from .sqlalchemy import *
+from .sqlalchemy import get_paginated_response, apply_pagination
+from .sqlalchemy.base import Base

nlbone-0.3.0/src/nlbone/adapters/db/sqlalchemy/__init__.py

@@ -0,0 +1 @@
+from .query_builder import get_paginated_response, apply_pagination

{nlbone-0.1.38/src/nlbone/adapters/db → nlbone-0.3.0/src/nlbone/adapters/db/sqlalchemy}/query_builder.py

@@ -1,4 +1,7 @@
+from typing import Union, Callable, Any, Optional, Type, Sequence
+
 from sqlalchemy import asc, desc, or_
+from sqlalchemy.orm.interfaces import LoaderOption
 from sqlalchemy.sql.sqltypes import (
     String, Text, Integer, BigInteger, SmallInteger, Numeric, Float, Boolean, Enum as SAEnum
 )
@@ -6,7 +9,7 @@ from sqlalchemy.orm import Session, Query
 from sqlalchemy.dialects.postgresql import ENUM as PGEnum
 
 from nlbone.interfaces.api.exceptions import UnprocessableEntityException
-from nlbone.interfaces.api.pagination import PaginateRequest
+from nlbone.interfaces.api.pagination import PaginateRequest, PaginateResponse
 
 NULL_SENTINELS = {"None", "null", ""}
 
@@ -15,7 +18,7 @@ class _InvalidEnum(Exception):
     pass
 
 
-def _apply_order(pagination, entity, query):
+def _apply_order(pagination: PaginateRequest, entity, query):
     if pagination.sort:
         order_clauses = []
         for sort in pagination.sort:
@@ -170,10 +173,84 @@ def _apply_filters(pagination, entity, query):
     return query
 
 
-def apply_pagination(pagination: PaginateRequest, entity, session: Session, limit=True) -> Query:
-    query = session.query(entity)
+def apply_pagination(pagination: PaginateRequest, entity, session: Session, limit=True, query=None) -> Query:
+    if not query:
+        query = session.query(entity)
     query = _apply_filters(pagination, entity, query)
     query = _apply_order(pagination, entity, query)
     if limit:
         query = query.limit(pagination.limit).offset(pagination.offset)
     return query
+
+
+OutputType = Union[type, Callable[[Any], Any], None]
+
+
+def _serialize_item(item: Any, output_cls: OutputType) -> Any:
+    """Serialize a single ORM item based on output_cls (Pydantic v1/v2 or custom mapper)."""
+    if output_cls is None:
+        return item
+
+    if callable(output_cls) and not isinstance(output_cls, type):
+        return output_cls(item)
+
+    if hasattr(output_cls, "model_validate"):
+        try:
+            model = output_cls.model_validate(item, from_attributes=True)  # type: ignore[attr-defined]
+            if hasattr(model, "model_dump"):
+                return model.model_dump()  # type: ignore[attr-defined]
+            return model
+        except Exception:
+            pass
+
+    if hasattr(output_cls, "from_orm"):
+        try:
+            model = output_cls.from_orm(item)  # type: ignore[attr-defined]
+            if hasattr(model, "dict"):
+                return model.dict()  # type: ignore[attr-defined]
+            return model
+        except Exception:
+            pass
+
+    try:
+        obj = output_cls(item)  # type: ignore[call-arg]
+        try:
+            from dataclasses import is_dataclass, asdict
+            if is_dataclass(obj):
+                return asdict(obj)
+        except Exception:
+            pass
+        return obj
+    except Exception:
+        return item
+
+
+def get_paginated_response(
+    pagination,
+    entity,
+    session: Session,
+    *,
+    with_count: bool = True,
+    output_cls: Optional[Type] = None,
+    eager_options: Optional[Sequence[LoaderOption]] = None,
+) -> dict:
+    # پایه‌ی کوئری
+    query = session.query(entity)
+    if eager_options:
+        query = query.options(*eager_options)
+
+    query = apply_pagination(pagination, entity, session, not with_count, query=query)
+
+    total_count = None
+    if with_count:
+        total_count = query.count()
+        query = query.limit(pagination.limit).offset(pagination.offset)
+
+    rows = query.all()
+
+    if output_cls is not None:
+        data = [output_cls.model_validate(r, from_attributes=True).model_dump() for r in rows]
+    else:
+        data = rows
+    return PaginateResponse(total_count=total_count, data=data, limit=pagination.limit,
+                            offset=pagination.offset).to_dict()

{nlbone-0.1.38 → nlbone-0.3.0}/src/nlbone/config/settings.py

@@ -15,8 +15,8 @@ def _guess_env_file() -> str | None:
     if cwd_env.exists():
         return str(cwd_env)
 
-    for i in range(1, 8):
-        p = Path(__file__).resolve().parents[i]
+    for i in range(0, 8):
+        p = Path.cwd().resolve().parents[i]
         f = p / ".env"
         if f.exists():
             return str(f)

nlbone-0.3.0/src/nlbone/interfaces/api/dependencies/auth.py

@@ -0,0 +1,48 @@
+import functools
+
+from nlbone.adapters.auth import KeycloakAuthService
+from nlbone.interfaces.api.exceptions import ForbiddenException, UnauthorizedException
+from nlbone.utils.context import current_request
+
+
+def client_has_access(*, permissions=None):
+    def decorator(func):
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            request = current_request()
+            if not KeycloakAuthService().client_has_access(request.state.token, permissions=permissions):
+                raise ForbiddenException(f"Forbidden {permissions}")
+
+            return func(*args, **kwargs)
+
+        return wrapper
+    return decorator
+
+
+
+def user_authenticated(func):
+    @functools.wraps(func)
+    async def wrapper(*args, **kwargs):
+        request = current_request()
+        if not request.state.user_id:
+            raise UnauthorizedException()
+        return await func(*args, **kwargs)
+
+    return wrapper
+
+
+def has_access(*, permissions=None):
+    def decorator(func):
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            request = current_request()
+            if not request.state.user_id:
+                raise UnauthorizedException()
+            if not KeycloakAuthService().has_access(request.state.token, permissions=permissions):
+                raise ForbiddenException(f"Forbidden {permissions}")
+
+            return func(*args, **kwargs)
+
+        return wrapper
+    return decorator
+

nlbone-0.3.0/src/nlbone/interfaces/api/exception_handlers.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+from typing import Any, Optional, Mapping
+from uuid import uuid4
+
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse
+from fastapi.exceptions import RequestValidationError
+from pydantic import ValidationError
+from fastapi import HTTPException as FastAPIHTTPException
+from starlette.exceptions import HTTPException as StarletteHTTPException
+
+from .exceptions import BaseHttpException
+
+
+# ---- Helpers ---------------------------------------------------------------
+
+def _ensure_trace_id(request: Request) -> str:
+    rid = request.headers.get("X-Request-Id") or request.headers.get("X-Trace-Id")
+    return rid or str(uuid4())
+
+
+def _json_response(
+        request: Request,
+        status_code: int,
+        *,
+        detail: Any,
+        headers: Optional[Mapping[str, str]] = None,
+        trace_id: Optional[str] = None,
+        extra: Optional[Mapping[str, Any]] = None,
+) -> JSONResponse:
+    payload: dict[str, Any] = {"detail": detail}
+    if extra:
+        payload.update(extra)
+    tid = trace_id or _ensure_trace_id(request)
+
+    payload.setdefault("trace_id", tid)
+
+    base_headers = {"X-Trace-Id": tid}
+    if headers:
+        base_headers.update(headers)
+
+    return JSONResponse(status_code=status_code, content=payload, headers=base_headers)
+
+
+# ---- Public Installer ------------------------------------------------------
+
+def install_exception_handlers(
+        app: FastAPI,
+        *,
+        logger: Any = None,
+        expose_server_errors: bool = False,
+) -> None:
+    @app.exception_handler(BaseHttpException)
+    async def _handle_base_http_exception(request: Request, exc: BaseHttpException):
+        if logger:
+            logger.warning(
+                "http_error",
+                extra={"status": exc.status_code, "detail": exc.detail, "path": request.url.path},
+            )
+        return _json_response(request, exc.status_code, detail=exc.detail)
+
+    @app.exception_handler(FastAPIHTTPException)
+    async def _handle_fastapi_http_exception(request: Request, exc: FastAPIHTTPException):
+        if logger:
+            logger.warning(
+                "fastapi_http_error",
+                extra={"status": exc.status_code, "detail": exc.detail, "path": request.url.path},
+            )
+        return _json_response(request, exc.status_code, detail=exc.detail)
+
+    @app.exception_handler(StarletteHTTPException)
+    async def _handle_starlette_http_exception(request: Request, exc: StarletteHTTPException):
+        if logger:
+            logger.warning(
+                "starlette_http_error",
+                extra={"status": exc.status_code, "detail": exc.detail, "path": request.url.path},
+            )
+        return _json_response(request, exc.status_code, detail=exc.detail)
+
+    # 3) خطاهای اعتبارسنجی FastAPI (request body/query/path)
+    @app.exception_handler(RequestValidationError)
+    async def _handle_request_validation_error(request: Request, exc: RequestValidationError):
+        errors = exc.errors()
+        if logger:
+            logger.info(
+                "request_validation_error",
+                extra={"errors": errors, "path": request.url.path},
+            )
+        return _json_response(request, 422, detail=errors)
+
+    @app.exception_handler(ValidationError)
+    async def _handle_pydantic_validation_error(request: Request, exc: ValidationError):
+        errors = exc.errors()
+        if logger:
+            logger.info(
+                "pydantic_validation_error",
+                extra={"errors": errors, "path": request.url.path},
+            )
+        return _json_response(request, 422, detail=errors)
+
+    @app.exception_handler(Exception)
+    async def _handle_unexpected_exception(request: Request, exc: Exception):
+        tid = _ensure_trace_id(request)
+        if logger:
+            logger.exception("unhandled_exception", extra={"trace_id": tid, "path": request.url.path})
+        detail = str(exc) if expose_server_errors else "internal server error"
+        return _json_response(request, 500, detail=detail, trace_id=tid)

nlbone-0.3.0/src/nlbone/interfaces/api/exceptions.py

@@ -0,0 +1,81 @@
+from typing import Any, Iterable
+from fastapi import HTTPException, status
+
+
+def _error_entry(loc: Iterable[Any] | None, detail: str, type_: str) -> dict:
+    return {
+        "loc": list(loc) if loc else [],
+        "msg": detail,
+        "type": type_,
+    }
+
+
+def _errors(loc: Iterable[Any] | None, detail: str, type_: str) -> list[dict]:
+    return [_error_entry(loc, detail, type_)]
+
+
+class BaseHttpException(HTTPException):
+    pass
+
+
+class BadRequestException(BaseHttpException):
+    def __init__(self, detail: str):
+        super().__init__(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=detail,
+        )
+
+
+class UnauthorizedException(BaseHttpException):
+    def __init__(self, detail: str = "unauthorized"):
+        super().__init__(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail=detail,
+        )
+
+
+class ForbiddenException(BaseHttpException):
+    def __init__(self, detail: str = "forbidden"):
+        super().__init__(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail=detail,
+        )
+
+
+class NotFoundException(BaseHttpException):
+    def __init__(self, detail: str = "not found"):
+        super().__init__(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=detail,
+        )
+
+
+class ConflictException(BaseHttpException):
+    def __init__(self, detail: str = "conflict"):
+        super().__init__(
+            status_code=status.HTTP_409_CONFLICT,
+            detail=detail,
+        )
+
+
+class NotSupportedException(BaseHttpException):
+    def __init__(self, detail: str = "NotSupported"):
+        super().__init__(
+            status_code=status.HTTP_501_NOT_IMPLEMENTED,
+            detail=detail,
+        )
+
+
+class UnprocessableEntityException(BaseHttpException):
+    def __init__(self, detail: str, loc: Iterable[Any] | None = None, type_: str = "unprocessable_entity"):
+        super().__init__(
+            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            detail=_errors(loc, detail, type_),
+        )
+
+
+class LogicalValidationException(UnprocessableEntityException):
+    def __init__(self, detail: str, loc: Iterable[Any] | None = None, type_: str = "logical_error"):
+        super().__init__(detail=detail, loc=loc, type_=type_)
+
+

nlbone-0.3.0/src/nlbone/interfaces/api/pagination/__init__.py

@@ -0,0 +1,20 @@
+from typing import Generic, List, Optional, TypeVar
+from pydantic import BaseModel
+from fastapi import Depends
+
+from .offset_base import PaginateResponse, PaginateRequest
+
+
+def get_pagination(
+        req: PaginateRequest = Depends(PaginateRequest)
+) -> PaginateRequest:
+    return req
+
+
+T = TypeVar("T")
+
+
+class Paginated(BaseModel, Generic[T]):
+    total_count: Optional[int]
+    total_page: Optional[int]
+    data: List[T]

{nlbone-0.1.38 → nlbone-0.3.0}/src/nlbone/interfaces/api/pagination/offset_base.py

@@ -1,6 +1,3 @@
-# src/nlbone/interfaces/api/pagination.py
-from __future__ import annotations
-
 import json
 from math import ceil
 from typing import Any, Optional
@@ -21,7 +18,7 @@ class PaginateRequest:
         limit: int = 10,
         offset: int = 0,
         sort: Optional[str] = None,
-        filters: Optional[str] = Query(None, description="e.g. title:abc or JSON"),
+        filters: Optional[str] = Query(None, description="e.g. title:abc"),
     ) -> None:
         self.limit = max(0, limit)
         self.offset = max(0, offset)
@@ -78,26 +75,6 @@ class PaginateRequest:
             filters_dict[key] = value_cast
         return filters_dict
 
-    # Helpers for SQLAlchemy usage:
-    def build_order_by(self, model) -> list[Any]:
-        """
-        Translate parsed sort to SQLAlchemy order_by list.
-        Example: model.created_at.desc(), model.id.asc()
-        """
-        items: list[Any] = []
-        for item in self.sort:
-            field = getattr(model, item["field"], None)
-            if field is None:
-                continue
-            items.append(desc(field) if item["order"] == "desc" else asc(field))
-        return items
-
-    def filter_kwargs(self) -> dict[str, Any]:
-        """
-        Return simple equality filters (for model.filter_by(**kwargs)).
-        For advanced ops, extend this to parse operators (gt, lt, like, in, etc.).
-        """
-        return {k: v for k, v in self.filters.items() if k != "$"}
 
 
 class PaginateResponse:

nlbone-0.1.38/src/nlbone/adapters/db/sqlalchemy/__init__.py

@@ -1,4 +0,0 @@
-from .query import apply_pagination, apply_filters, apply_order
-from .base import Base
-
-__all__ = ["apply_pagination", "apply_filters", "apply_order", "Base"]

nlbone-0.1.38/src/nlbone/adapters/db/sqlalchemy/query/__init__.py

@@ -1,3 +0,0 @@
-from .builder import apply_pagination, apply_filters, apply_order
-
-__all__ = ["apply_pagination", "apply_filters", "apply_order"]

nlbone-0.1.38/src/nlbone/adapters/db/sqlalchemy/query/builder.py

@@ -1,21 +0,0 @@
-from __future__ import annotations
-from sqlalchemy.orm import Session, Query
-
-from nlbone.adapters.db.sqlalchemy.query.filters import apply_filters_to_query
-from nlbone.adapters.db.sqlalchemy.query.ordering import apply_order_to_query
-
-
-def apply_pagination(pagination, entity, session: Session, limit: bool = True) -> Query:
-    q: Query = session.query(entity)
-    q = apply_filters_to_query(pagination, entity, q)
-    from nlbone.adapters.db.sqlalchemy.query.ordering import apply_order_to_query
-    q = apply_order_to_query(pagination, entity, q)
-    if limit:
-        q = q.limit(pagination.limit).offset(pagination.offset)
-    return q
-
-def apply_filters(pagination, entity, query: Query) -> Query:
-    return apply_filters_to_query(pagination, entity, query)
-
-def apply_order(pagination, entity, query: Query) -> Query:
-    return apply_order_to_query(pagination, entity, query)

nlbone-0.1.38/src/nlbone/adapters/db/sqlalchemy/query/coercion.py

@@ -1,64 +0,0 @@
-from sqlalchemy.sql.sqltypes import (
-    String, Text, Integer, BigInteger, SmallInteger, Numeric, Float, Boolean, Enum as SAEnum
-)
-try:
-    from sqlalchemy.dialects.postgresql import ENUM as PGEnum
-except Exception:
-    PGEnum = type("PGEnum", (), {})
-
-from .types import InvalidEnum
-
-def is_text_type(coltype) -> bool:
-    return isinstance(coltype, (String, Text))
-
-def looks_like_wildcard(s: str) -> bool:
-    return isinstance(s, str) and ("*" in s or "%" in s)
-
-def to_like_pattern(s: str) -> str:
-    s = (s or "")
-    s = s.replace("*", "%")
-    return s if "%" in s else f"%{s}%"
-
-def _coerce_enum(col_type, raw):
-    if raw is None:
-        return None
-    enum_cls = getattr(col_type, "enum_class", None)
-    if enum_cls is not None:
-        if isinstance(raw, enum_cls):
-            return raw
-        if isinstance(raw, str):
-            low = raw.strip().lower()
-            for m in enum_cls:
-                if m.name.lower() == low or str(m.value).lower() == low:
-                    return m
-        raise InvalidEnum(f"'{raw}' is not one of {[m.name for m in enum_cls]}")
-    choices = list(getattr(col_type, "enums", []) or [])
-    if isinstance(raw, str):
-        low = raw.strip().lower()
-        for c in choices:
-            if c.lower() == low:
-                return c
-    raise InvalidEnum(f"'{raw}' is not one of {choices or '[no choices defined]'}")
-
-def coerce_value_for_column(coltype, v):
-    if v is None:
-        return None
-    if isinstance(coltype, (SAEnum, PGEnum)):
-        return _coerce_enum(coltype, v)
-    if is_text_type(coltype):
-        return str(v)
-    if isinstance(coltype, (Integer, BigInteger, SmallInteger)):
-        return int(v)
-    if isinstance(coltype, (Float, Numeric)):
-        return float(v)
-    if isinstance(coltype, Boolean):
-        if isinstance(v, bool):
-            return v
-        if isinstance(v, (int, float)):
-            return bool(v)
-        if isinstance(v, str):
-            vl = v.strip().lower()
-            if vl in {"true", "1", "yes", "y", "t"}: return True
-            if vl in {"false", "0", "no", "n", "f"}: return False
-        return None
-    return v

nlbone-0.1.38/src/nlbone/adapters/db/sqlalchemy/query/filters.py

@@ -1,57 +0,0 @@
-from __future__ import annotations
-from sqlalchemy import or_
-from sqlalchemy.orm import Query
-
-try:
-    from sqlalchemy.dialects.postgresql import ENUM as PGEnum  # اختیاری
-except Exception:
-    PGEnum = type("PGEnum", (), {})  # fallback dummy
-
-from nlbone.interfaces.api.exceptions import UnprocessableEntityException
-from nlbone.interfaces.api.pagination import PaginateRequest
-from .coercion import coerce_value_for_column, to_like_pattern, is_text_type, looks_like_wildcard
-from .types import NULL_SENTINELS, InvalidEnum, parse_field_and_op
-
-def apply_filters_to_query(pagination: PaginateRequest, entity, query: Query) -> Query:
-    if not getattr(pagination, "filters", None):
-        return query
-
-    for raw_field, value in pagination.filters.items():
-        if value is None or value in NULL_SENTINELS or value == [] or value == {}:
-            value = None
-
-        field, op_hint = parse_field_and_op(raw_field)
-        if not hasattr(entity, field):
-            continue
-
-        col = getattr(entity, field)
-        coltype = getattr(col, "type", None)
-
-        def _use_ilike(v) -> bool:
-            if op_hint == "ilike":
-                return True
-            return is_text_type(coltype) and isinstance(v, str) and looks_like_wildcard(v)
-
-        try:
-            if isinstance(value, (list, tuple, set)):
-                vals = [v for v in value if v not in (None, "", "null", "None")]
-                if not vals:
-                    continue
-                if any(_use_ilike(v) for v in vals) and is_text_type(coltype):
-                    patterns = [to_like_pattern(str(v)) for v in vals]
-                    query = query.filter(or_(*[col.ilike(p) for p in patterns]))
-                else:
-                    coerced = [coerce_value_for_column(coltype, v) for v in vals]
-                    if not coerced:
-                        continue
-                    query = query.filter(col.in_(coerced))
-            else:
-                if _use_ilike(value) and is_text_type(coltype):
-                    query = query.filter(col.ilike(to_like_pattern(str(value))))
-                else:
-                    v = coerce_value_for_column(coltype, value)
-                    query = query.filter(col.is_(None) if v is None else (col == v))
-        except InvalidEnum as e:
-            raise UnprocessableEntityException(str(e), loc=["query", "filters", raw_field]) from e
-
-    return query

nlbone-0.1.38/src/nlbone/adapters/db/sqlalchemy/query/ordering.py

@@ -1,14 +0,0 @@
-from sqlalchemy import asc, desc
-from sqlalchemy.orm import Query
-
-def apply_order_to_query(pagination, entity, query: Query) -> Query:
-    if not pagination.sort:
-        return query
-    clauses = []
-    for s in pagination.sort:
-        field = s["field"]
-        order = s["order"]
-        if hasattr(entity, field):
-            col = getattr(entity, field)
-            clauses.append(asc(col) if order == "asc" else desc(col))
-    return query.order_by(*clauses) if clauses else query

nlbone-0.1.38/src/nlbone/adapters/db/sqlalchemy/query/types.py

@@ -1,11 +0,0 @@
-NULL_SENTINELS = {"None", "null", ""}
-
-class InvalidEnum(Exception):
-    pass
-
-def parse_field_and_op(field: str) -> tuple[str, str]:
-    if "__" in field:
-        base, op = field.rsplit("__", 1)
-        if op.lower() == "ilike":
-            return base, "ilike"
-    return field, "eq"

nlbone-0.1.38/src/nlbone/interfaces/api/exceptions.py

@@ -1,8 +0,0 @@
-from fastapi import HTTPException, status
-
-class UnprocessableEntityException(HTTPException):
-    def __init__(self, detail: str, loc: list[str] | None = None):
-        super().__init__(
-            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
-            detail={"msg": detail, "loc": loc or []},
-        )

nlbone-0.1.38/src/nlbone/interfaces/api/pagination/__init__.py

@@ -1 +0,0 @@
-from .offset_base import PaginateResponse, PaginateRequest