crypticorn-utils 0.1.0__py3-none-any.whl

crypticorn_utils/pagination.py

@@ -0,0 +1,286 @@
+"""Utilities for handling paginated API responses, cursor-based pagination, filtering, sorting, etc."""
+
+import math
+from typing import Annotated, Any, Generic, Literal, Optional, Type, TypeVar
+
+from pydantic import BaseModel, Field, model_validator
+
+T = TypeVar("T")
+
+
+class PaginatedResponse(BaseModel, Generic[T]):
+    """Pydantic model for paginated response
+    >>> @router.get("", operation_id="getOrders")
+    >>> async def get_orders(
+    >>>     params: Annotated[PaginationParams, Query()],
+    >>> ) -> PaginatedResponse[Order]:
+    >>>     ...
+    >>> return PaginatedResponse[Order](
+            data=orders,
+            total=count,
+            page=params.page,
+            page_size=params.page_size,
+            prev=PaginatedResponse.get_prev_page(params.page),
+            next=PaginatedResponse.get_next_page(count, params.page_size, params.page),
+            last=PaginatedResponse.get_last_page(count, params.page_size),
+        )
+    """
+
+    data: list[T]
+    total: int = Field(description="The total number of items")
+    page: int = Field(description="The current page number")
+    page_size: int = Field(description="The number of items per page")
+    prev: Optional[int] = Field(None, description="The previous page number")
+    next: Optional[int] = Field(None, description="The next page number")
+    last: Optional[int] = Field(None, description="The last page number")
+
+    @staticmethod
+    def get_next_page(total: int, page_size: int, page: int) -> Optional[int]:
+        """Get the next page number"""
+        if page < math.ceil(total / page_size):
+            return page + 1
+        return None
+
+    @staticmethod
+    def get_prev_page(page: int) -> Optional[int]:
+        """Get the previous page number"""
+        if page > 1:
+            return page - 1
+        return None
+
+    @staticmethod
+    def get_last_page(total: int, page_size: int) -> int:
+        """Get the last page number"""
+        return max(1, math.ceil(total / page_size))
+
+
+class PaginationParams(BaseModel, Generic[T]):
+    """Standard pagination parameters for usage in API endpoints. Check the [fastapi docs](https://fastapi.tiangolo.com/tutorial/query-param-models/?h=qu#query-parameters-with-a-pydantic-model) for usage examples.
+    You should inherit from this class when adding additional parameters. You should use this class in combination with `PaginatedResponse` to return the paginated response.
+    Usage:
+    >>> @router.get("", operation_id="getOrders")
+    >>> async def get_orders(
+    >>>     params: Annotated[PaginationParams[Order], Query()],
+    >>> ) -> PaginatedResponse[Order]:
+    >>>     ...
+
+    The default size is 10 items per page and there is a `HeavyPaginationParams` class with 100 items per page. You can override this default:
+    >>> class LightPaginationParams(PaginationParams):
+    >>>     page_size: int = Field(default=5, description="The number of items per page")
+    """
+
+    page: Optional[int] = Field(default=1, description="The current page number")
+    page_size: Annotated[int, Field(ge=1, le=100)] = Field(
+        10, description="The number of items per page. Default is 10, max is 100."
+    )
+
+
+class HeavyPaginationParams(PaginationParams[T]):
+    """Pagination parameters with a higher default size. Refer to `PaginationParams` for usage examples."""
+
+    page_size: Annotated[int, Field(ge=1, le=1000)] = Field(
+        100, description="The number of items per page. Default is 100, max is 1000."
+    )
+
+
+class SortParams(BaseModel, Generic[T]):
+    """Standard sort parameters for usage in API endpoints. Check the [fastapi docs](https://fastapi.tiangolo.com/tutorial/query-param-models/?h=qu#query-parameters-with-a-pydantic-model) for usage examples.
+    You should inherit from this class when adding additional parameters.
+    Usage:
+    >>> @router.get("", operation_id="getOrders")
+    >>> async def get_orders(
+    >>>     params: Annotated[SortParams[Order], Query()],
+    >>> ) -> PaginatedResponse[Order]:
+    >>>     ...
+    """
+
+    sort_order: Optional[Literal["asc", "desc"]] = Field(
+        None, description="The order to sort by"
+    )
+    sort_by: Optional[str] = Field(None, description="The field to sort by")
+
+    @model_validator(mode="after")
+    def validate_sort(self):
+        # Extract the generic argument type
+        args: tuple = self.__pydantic_generic_metadata__.get("args")
+        if not args or not issubclass(args[0], BaseModel):
+            raise TypeError(
+                "SortParams must be used with a Pydantic BaseModel as a generic parameter"
+            )
+        if self.sort_by:
+            # check if the sort field is valid
+            model: Type[BaseModel] = args[0]
+            if self.sort_by not in model.model_fields:
+                raise ValueError(
+                    f"Invalid field: '{self.sort_by}'. Must be one of: {list(model.model_fields)}"
+                )
+        if self.sort_order and self.sort_order not in ["asc", "desc"]:
+            raise ValueError(
+                f"Invalid order: '{self.sort_order}' — must be one of: ['asc', 'desc']"
+            )
+        if (
+            self.sort_order
+            and self.sort_by is None
+            or self.sort_by
+            and self.sort_order is None
+        ):
+            raise ValueError("sort_order and sort_by must be provided together")
+        return self
+
+
+class FilterParams(BaseModel, Generic[T]):
+    """Standard filter parameters for usage in API endpoints. Check the [fastapi docs](https://fastapi.tiangolo.com/tutorial/query-param-models/?h=qu#query-parameters-with-a-pydantic-model) for usage examples.
+    You should inherit from this class when adding additional parameters.
+    Usage:
+    >>> @router.get("", operation_id="getOrders")
+    >>> async def get_orders(
+    >>>     params: Annotated[FilterParams[Order], Query()],
+    >>> ) -> PaginatedResponse[Order]:
+    >>>     ...
+    """
+
+    filter_by: Optional[str] = Field(None, description="The field to filter by")
+    filter_value: Optional[str] = Field(None, description="The value to filter with")
+    # currently openapi-gen does not support typing.Any in combo with None, so we use str
+    # this is fine since the input is a string anyways from the request and the correct type is enforced by the model validator from the filter_by field
+
+    @model_validator(mode="after")
+    def validate_filter(self):
+        if self.filter_by and not self.filter_value:
+            raise ValueError("filter_by and filter_value must be provided together")
+        if self.filter_by:
+            # Extract the generic argument type
+            args: tuple = self.__pydantic_generic_metadata__.get("args")
+            if not args or not issubclass(args[0], BaseModel):
+                raise TypeError(
+                    "FilterParams must be used with a Pydantic BaseModel as a generic parameter"
+                )
+            # check if the filter field is valid
+            model: Type[BaseModel] = args[0]
+            if self.filter_by not in model.model_fields:
+                raise ValueError(
+                    f"Invalid field: '{self.filter_by}'. Must be one of: {list(model.model_fields)}"
+                )
+            self.filter_value = _enforce_field_type(
+                model, self.filter_by, self.filter_value
+            )
+        return self
+
+
+class SortFilterParams(SortParams[T], FilterParams[T]):
+    """Combines sort and filter parameters. Just a convenience class for when you need to combine sort and filter parameters.
+    You should inherit from this class when adding additional parameters.
+    Usage:
+    >>> @router.get("", operation_id="getOrders")
+    >>> async def get_orders(
+    >>>     params: Annotated[SortFilterParams[Order], Query()],
+    >>> ) -> PaginatedResponse[Order]:
+    >>>     ...
+    """
+
+    @model_validator(mode="after")
+    def validate_sort_filter(self):
+        self.validate_sort()
+        self.validate_filter()
+        return self
+
+
+class PageFilterParams(PaginationParams[T], FilterParams[T]):
+    """Combines pagination and filter parameters. Just a convenience class for when you need to combine pagination and filter parameters.
+    You should inherit from this class when adding additional parameters.
+    Usage:
+    >>> @router.get("", operation_id="getOrders")
+    >>> async def get_orders(
+    >>>     params: Annotated[PageFilterParams[Order], Query()],
+    >>> ) -> PaginatedResponse[Order]:
+    >>>     ...
+    """
+
+    @model_validator(mode="after")
+    def validate_page_filter(self):
+        self.validate_filter()
+        return self
+
+
+class PageSortParams(PaginationParams[T], SortParams[T]):
+    """Combines pagination and sort parameters. Just a convenience class for when you need to combine pagination and sort parameters.
+    You should inherit from this class when adding additional parameters.
+    Usage:
+    >>> @router.get("", operation_id="getOrders")
+    >>> async def get_orders(
+    >>>     params: Annotated[PageSortParams[Order], Query()],
+    >>> ) -> PaginatedResponse[Order]:
+    >>>     ...
+    """
+
+    @model_validator(mode="after")
+    def validate_page_sort(self):
+        self.validate_sort()
+        return self
+
+
+class PageSortFilterParams(
+    PaginationParams[T],
+    SortParams[T],
+    FilterParams[T],
+):
+    """Combines pagination, filter, and sort parameters. Just a convenience class for when you need to combine pagination, filter, and sort parameters.
+    You should inherit from this class when adding additional parameters.
+    Usage:
+    >>> @router.get("", operation_id="getOrders")
+    >>> async def get_orders(
+    >>>     params: Annotated[PageSortFilterParams[Order], Query()],
+    >>> ) -> PaginatedResponse[Order]:
+    >>>     ...
+    """
+
+    @model_validator(mode="after")
+    def validate_filter_combo(self):
+        self.validate_filter()
+        self.validate_sort()
+        return self
+
+
+class HeavyPageSortFilterParams(
+    HeavyPaginationParams[T], FilterParams[T], SortParams[T]
+):
+    """Combines heavy pagination, filter, and sort parameters. Just a convenience class for when you need to combine heavy pagination, filter, and sort parameters.
+    You should inherit from this class when adding additional parameters.
+    Usage:
+    >>> @router.get("", operation_id="getOrders")
+    >>> async def get_orders(
+    >>>     params: Annotated[HeavyPageSortFilterParams[Order], Query()],
+    >>> ) -> PaginatedResponse[Order]:
+    >>>     ...
+    """
+
+    @model_validator(mode="after")
+    def validate_heavy_page_sort_filter(self):
+        self.validate_filter()
+        self.validate_sort()
+        return self
+
+
+def _enforce_field_type(model: Type[BaseModel], field_name: str, value: Any) -> Any:
+    """
+    Coerce or validate `value` to match the type of `field_name` on the given `model`. Should be used after checking that the field is valid.
+
+    :param model: The Pydantic model.
+    :param field_name: The name of the field to match.
+    :param value: The value to validate or coerce.
+
+    :return: The value cast to the expected type.
+
+    :raises: ValueError: If the field doesn't exist or coercion fails.
+    """
+    expected_type = model.model_fields[field_name].annotation
+
+    if isinstance(value, expected_type):
+        return value
+
+    try:
+        return expected_type(value)
+    except Exception:
+        raise ValueError(
+            f"Expected {expected_type} for field {field_name}, got {type(value)}"
+        )

crypticorn_utils/router/admin_router.py

@@ -0,0 +1,117 @@
+"""
+This module contains the admin router for the API.
+It provides endpoints for monitoring the server and getting information about the environment.
+ONLY ALLOW ACCESS TO THIS ROUTER WITH ADMIN SCOPES.
+>>> app.include_router(admin_router, dependencies=[Security(auth_handler.full_auth, scopes=[Scope.READ_ADMIN, Scope.WRITE_ADMIN])])
+"""
+
+import importlib.metadata
+import logging
+import os
+import re
+import threading
+import time
+from typing import Literal
+
+import psutil
+from crypticorn_utils.logging import LogLevel
+from crypticorn_utils.metrics import registry
+from fastapi import APIRouter, Query, Response
+from prometheus_client import CONTENT_TYPE_LATEST, generate_latest
+
+router = APIRouter(tags=["Admin"], prefix="/admin")
+
+START_TIME = time.time()
+
+
+@router.get("/log-level", status_code=200, operation_id="getLogLevel", deprecated=True)
+async def get_logging_level() -> LogLevel:
+    """
+    Get the log level of the server logger. Will be removed in a future release.
+    """
+    return LogLevel.get_name(logging.getLogger().level)
+
+
+@router.get("/uptime", operation_id="getUptime", status_code=200)
+def get_uptime(type: Literal["seconds", "human"] = "seconds") -> str:
+    """Return the server uptime in seconds or human-readable form."""
+    uptime_seconds = int(time.time() - START_TIME)
+    if type == "seconds":
+        return str(uptime_seconds)
+    elif type == "human":
+        return time.strftime("%H:%M:%S", time.gmtime(uptime_seconds))
+
+
+@router.get("/memory", operation_id="getMemoryUsage", status_code=200)
+def get_memory_usage() -> float:
+    """
+    Resident Set Size (RSS) in MB — the actual memory used by the process in RAM.
+    Represents the physical memory footprint. Important for monitoring real usage.
+    """
+    process = psutil.Process(os.getpid())
+    mem_info = process.memory_info()
+    return round(mem_info.rss / (1024 * 1024), 2)
+
+
+@router.get("/threads", operation_id="getThreads", status_code=200)
+def get_threads() -> dict:
+    """Return count and names of active threads."""
+    threads = threading.enumerate()
+    return {
+        "count": len(threads),
+        "threads": [t.name for t in threads],
+    }
+
+
+@router.get("/limits", operation_id="getContainerLimits", status_code=200)
+def get_container_limits() -> dict:
+    """Return container resource limits from cgroup."""
+    limits = {}
+    try:
+        with open("/sys/fs/cgroup/memory/memory.limit_in_bytes") as f:
+            limits["memory_limit_MB"] = int(f.read().strip()) / 1024 / 1024
+    except Exception:
+        limits["memory_limit_MB"] = "N/A"
+
+    try:
+        with open("/sys/fs/cgroup/cpu/cpu.cfs_quota_us") as f1, open(
+            "/sys/fs/cgroup/cpu/cpu.cfs_period_us"
+        ) as f2:
+            quota = int(f1.read().strip())
+            period = int(f2.read().strip())
+            limits["cpu_limit_cores"] = quota / period if quota > 0 else "N/A"
+    except Exception:
+        limits["cpu_limit_cores"] = "N/A"
+
+    return limits
+
+
+@router.get("/dependencies", operation_id="getDependencies", status_code=200)
+def list_installed_packages(
+    include: list[str] = Query(
+        default=None,
+        description="List of regex patterns to match against package names. If not provided, all installed packages will be returned.",
+    )
+) -> dict[str, str]:
+    """Return a list of installed packages and versions.
+
+    The include parameter accepts regex patterns to match against package names.
+    For example:
+    - crypticorn.* will match all packages starting with 'crypticorn'
+    - .*tic.* will match all packages containing 'tic' in their name
+    """
+    packages = {
+        dist.metadata["Name"]: dist.version
+        for dist in importlib.metadata.distributions()
+        if include is None
+        or any(re.match(pattern, dist.metadata["Name"]) for pattern in include)
+    }
+    return dict(sorted(packages.items()))
+
+
+@router.get("/metrics", operation_id="getMetrics")
+def metrics():
+    """
+    Get Prometheus metrics for the application. Returns plain text.
+    """
+    return Response(generate_latest(registry), media_type=CONTENT_TYPE_LATEST)

crypticorn_utils/router/status_router.py

@@ -0,0 +1,36 @@
+"""
+This module contains the status router for the API.
+It provides endpoints for checking the status of the API and get the server's time.
+SHOULD ALLOW ACCESS TO THIS ROUTER WITHOUT AUTH.
+To enable metrics, pass enable_metrics=True and the auth_handler to the router.
+>>> status_router.enable_metrics = True
+>>> status_router.auth_handler = auth_handler
+Then include the router in the FastAPI app.
+>>> app.include_router(status_router)
+"""
+
+from datetime import datetime
+from typing import Literal
+
+from fastapi import APIRouter, Request
+
+router = APIRouter(tags=["Status"], prefix="")
+
+
+@router.get("/", operation_id="ping")
+async def ping(request: Request) -> str:
+    """
+    Returns 'OK' if the API is running.
+    """
+    return "OK"
+
+
+@router.get("/time", operation_id="getTime")
+async def time(type: Literal["iso", "unix"] = "iso") -> str:
+    """
+    Returns the current time in either ISO or Unix timestamp (seconds) format.
+    """
+    if type == "iso":
+        return datetime.now().isoformat()
+    elif type == "unix":
+        return str(int(datetime.now().timestamp()))

crypticorn_utils/utils.py

@@ -0,0 +1,93 @@
+"""General utility functions and helper methods used across the codebase."""
+
+import random
+import string
+import warnings
+from datetime import datetime
+from decimal import Decimal
+from typing import Any, Union
+
+import typing_extensions
+from crypticorn_utils.exceptions import ApiError, ExceptionContent, HTTPException
+from crypticorn_utils.warnings import CrypticornDeprecatedSince25
+
+
+def throw_if_none(
+    value: Any,
+    message: str = "Object not found",
+) -> None:
+    """Throws an FastAPI HTTPException if the value is None. https://docs.python.org/3/library/stdtypes.html#truth-value-testing"""
+    if value is None:
+        raise HTTPException(content=ExceptionContent(error=ApiError.OBJECT_NOT_FOUND, message=message))
+
+
+def throw_if_falsy(
+    value: Any,
+    message: str = "Object not found",
+) -> None:
+    """Throws an FastAPI HTTPException if the value is False. https://docs.python.org/3/library/stdtypes.html#truth-value-testing"""
+    if not value:
+        raise HTTPException(content=ExceptionContent(error=ApiError.OBJECT_NOT_FOUND, message=message))
+
+
+def gen_random_id(length: int = 20) -> str:
+    """Generate a random base62 string (a-zA-Z0-9) of specified length. The max possible combinations is 62^length.
+    Kucoin max 40, bingx max 40"""
+    charset = string.ascii_letters + string.digits
+    return "".join(random.choice(charset) for _ in range(length))
+
+
+@typing_extensions.deprecated(
+    "The `is_equal` method is deprecated; use `math.is_close` instead.", category=None
+)
+def is_equal(
+    a: Union[float, Decimal],
+    b: Union[float, Decimal],
+    rel_tol: float = 1e-9,
+    abs_tol: float = 0.0,
+) -> bool:
+    """
+    Compare two Decimal numbers for approximate equality.
+    """
+    warnings.warn(
+        "The `is_equal` method is deprecated; use `math.is_close` instead.",
+        category=CrypticornDeprecatedSince25,
+    )
+    if not isinstance(a, Decimal):
+        a = Decimal(str(a))
+    if not isinstance(b, Decimal):
+        b = Decimal(str(b))
+
+    # Convert tolerances to Decimal
+    return Decimal(abs(a - b)) <= max(
+        Decimal(str(rel_tol)) * max(abs(a), abs(b)), Decimal(str(abs_tol))
+    )
+
+
+def optional_import(module_name: str, extra_name: str) -> Any:
+    """
+    Tries to import a module. Raises `ImportError` if not found with a message to install the extra dependency.
+    """
+    try:
+        return __import__(module_name)
+    except ImportError as e:
+        raise ImportError(
+            f"Optional dependency '{module_name}' is required for this feature. "
+            f"Install it with: pip install crypticorn[{extra_name}]"
+        ) from e
+
+
+def datetime_to_timestamp(v: Any):
+    """Converts a datetime to a timestamp.
+    Can be used as a pydantic validator.
+    >>> from pydantic import BeforeValidator, BaseModel
+    >>> class MyModel(BaseModel):
+    ...     timestamp: Annotated[int, BeforeValidator(datetime_to_timestamp)]
+    """
+    if isinstance(v, list):
+        return [
+            int(item.timestamp()) if isinstance(item, datetime) else item for item in v
+        ]
+    elif isinstance(v, datetime):
+        return int(v.timestamp())
+    return v

crypticorn_utils/warnings.py

@@ -0,0 +1,79 @@
+"""Crypticorn-specific warnings."""
+
+from __future__ import annotations
+
+from typing import Union
+
+
+class CrypticornDeprecationWarning(DeprecationWarning):
+    """A Crypticorn specific deprecation warning.
+
+    This warning is raised when using deprecated functionality in Crypticorn. It provides information on when the
+    deprecation was introduced and the expected version in which the corresponding functionality will be removed.
+
+    Attributes:
+        message: Description of the warning.
+        since: Crypticorn version in what the deprecation was introduced.
+        expected_removal: Crypticorn version in what the corresponding functionality expected to be removed.
+    """
+
+    message: str
+    since: tuple[int, int]
+    expected_removal: tuple[int, int]
+
+    def __init__(
+        self,
+        message: str,
+        *args: object,
+        since: tuple[int, int],
+        expected_removal: Union[tuple[int, int], None] = None,
+    ) -> None:
+        super().__init__(message, *args)
+        self.message = message.rstrip(".")
+        self.since = since
+        self.expected_removal = (
+            expected_removal if expected_removal is not None else (since[0] + 1, 0)
+        )
+
+    def __str__(self) -> str:
+        message = (
+            f"{self.message}. Deprecated in Crypticorn v{self.since[0]}.{self.since[1]}"
+            f" to be removed in v{self.expected_removal[0]}.{self.expected_removal[1]}."
+        )
+        return message
+
+
+class CrypticornDeprecatedSince25(CrypticornDeprecationWarning):
+    """A specific `CrypticornDeprecationWarning` subclass defining functionality deprecated since Crypticorn 2.5."""
+
+    def __init__(self, message: str, *args: object) -> None:
+        super().__init__(message, *args, since=(2, 5), expected_removal=(3, 0))
+
+
+class CrypticornDeprecatedSince28(CrypticornDeprecationWarning):
+    """A specific `CrypticornDeprecationWarning` subclass defining functionality deprecated since Crypticorn 2.8."""
+
+    def __init__(self, message: str, *args: object) -> None:
+        super().__init__(message, *args, since=(2, 8), expected_removal=(3, 0))
+
+
+class CrypticornDeprecatedSince215(CrypticornDeprecationWarning):
+    """A specific `CrypticornDeprecationWarning` subclass defining functionality deprecated since Crypticorn 2.15."""
+
+    def __init__(self, message: str, *args: object) -> None:
+        super().__init__(message, *args, since=(2, 15), expected_removal=(3, 0))
+
+
+class CrypticornDeprecatedSince217(CrypticornDeprecationWarning):
+    """A specific `CrypticornDeprecationWarning` subclass defining functionality deprecated since Crypticorn 2.17."""
+
+    def __init__(self, message: str, *args: object) -> None:
+        super().__init__(message, *args, since=(2, 17), expected_removal=(3, 0))
+
+
+class CrypticornExperimentalWarning(Warning):
+    """A Crypticorn specific experimental functionality warning.
+
+    This warning is raised when using experimental functionality in Crypticorn.
+    It is raised to warn users that the functionality may change or be removed in future versions of Crypticorn.
+    """