crypticorn-utils 0.1.0rc1__tar.gz → 1.0.0rc1__tar.gz

{crypticorn_utils-0.1.0rc1 → crypticorn_utils-1.0.0rc1}/LICENSE

@@ -12,4 +12,4 @@ Changes to this agreement may be made without notice, and it is the user's respo
 
 If any provision of this license agreement is held to be invalid or unenforceable under applicable law, the remaining provisions will continue in full force and effect. Crypticorn's failure to enforce any provision of this agreement does not constitute a waiver of its right to do so in the future.
 
-This agreement is written in English. In the event of any discrepancy between the English version and any translation, the English version shall prevail.
+This agreement is written in English. In the event of any discrepancy between the English version and any translation, the English version shall prevail.

crypticorn_utils-1.0.0rc1/MANIFEST.in

@@ -0,0 +1,4 @@
+include crypticorn_utils/py.typed
+include README.md
+include LICENSE
+include 

{crypticorn_utils-0.1.0rc1/crypticorn_utils.egg-info → crypticorn_utils-1.0.0rc1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crypticorn_utils
-Version: 0.1.0rc1
+Version: 1.0.0rc1
 Summary: Shared utilities for the Crypticorn APIs
 Author-email: Crypticorn <timon@crypticorn.com>
 License-Expression: MIT
@@ -11,20 +11,17 @@ Classifier: Topic :: Scientific/Engineering
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Typing :: Typed
-Requires-Python: >=3.9
+Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: fastapi<1.0.0,>=0.115.0
 Requires-Dist: click<9.0.0,>=8.0.0
 Requires-Dist: psutil<8.0.0,>=7.0.0
 Requires-Dist: setuptools<81.0.0,>=80.0.0
-Requires-Dist: strenum
 Requires-Dist: prometheus-client<1.0.0,>=0.22.0
 Provides-Extra: dev
 Requires-Dist: build; extra == "dev"
@@ -68,6 +65,24 @@ This module serves as a central place for providing utilities for our python bac
 
 <!-- changelog-insertion -->
 
+## v1.0.0-rc.1 (2025-07-17)
+
+### Build System
+
+- Deployment config for v1 branches
+  ([`b94d9e7`](https://github.com/crypticorn-ai/util-libraries/commit/b94d9e72616e398760993f6ebb1a6fd876a95802))
+
+BREAKING CHANGE: - removed: mixins, openapi and both router modules; CLI; Scope Enum class;
+  `throw_if_none` and `throw_if_falsy`; all deprecation warnings - reworked: exceptions and error
+  modules
+
+- Mark packaage as typed
+  ([`69544a8`](https://github.com/crypticorn-ai/util-libraries/commit/69544a8709f4d55850e107031b82d91c28334b3c))
+
+- Remove support for python versions 3.9 and 3.10
+  ([`80b8543`](https://github.com/crypticorn-ai/util-libraries/commit/80b8543ed5559a0de421aef4e2382193e930751a))
+
+
 ## v0.1.0-rc.1 (2025-06-23)
 
 ### Documentation

{crypticorn_utils-0.1.0rc1 → crypticorn_utils-1.0.0rc1}/README.md

@@ -21,6 +21,24 @@ This module serves as a central place for providing utilities for our python bac
 
 <!-- changelog-insertion -->
 
+## v1.0.0-rc.1 (2025-07-17)
+
+### Build System
+
+- Deployment config for v1 branches
+  ([`b94d9e7`](https://github.com/crypticorn-ai/util-libraries/commit/b94d9e72616e398760993f6ebb1a6fd876a95802))
+
+BREAKING CHANGE: - removed: mixins, openapi and both router modules; CLI; Scope Enum class;
+  `throw_if_none` and `throw_if_falsy`; all deprecation warnings - reworked: exceptions and error
+  modules
+
+- Mark packaage as typed
+  ([`69544a8`](https://github.com/crypticorn-ai/util-libraries/commit/69544a8709f4d55850e107031b82d91c28334b3c))
+
+- Remove support for python versions 3.9 and 3.10
+  ([`80b8543`](https://github.com/crypticorn-ai/util-libraries/commit/80b8543ed5559a0de421aef4e2382193e930751a))
+
+
 ## v0.1.0-rc.1 (2025-06-23)
 
 ### Documentation

crypticorn_utils-1.0.0rc1/crypticorn_utils/__init__.py

@@ -0,0 +1,50 @@
+from crypticorn_utils.auth import AuthHandler
+from crypticorn_utils.decorators import partial_model
+from crypticorn_utils.enums import ApiEnv, BaseUrl, Exchange, MarketType
+from crypticorn_utils.errors import ErrorLevel, ErrorType
+from crypticorn_utils.exceptions import BaseError, ExceptionHandler, ExceptionType
+from crypticorn_utils.logging import configure_logging, disable_logging
+from crypticorn_utils.middleware import add_middleware
+from crypticorn_utils.pagination import (
+    FilterParams,
+    HeavyPageSortFilterParams,
+    HeavyPaginationParams,
+    PageFilterParams,
+    PageSortFilterParams,
+    PageSortParams,
+    PaginatedResponse,
+    PaginationParams,
+    SortFilterParams,
+    SortParams,
+)
+from crypticorn_utils.utils import datetime_to_timestamp, gen_random_id, optional_import
+
+__all__ = [
+    "AuthHandler",
+    "partial_model",
+    "Exchange",
+    "MarketType",
+    "ApiEnv",
+    "BaseUrl",
+    "ErrorType",
+    "ErrorLevel",
+    "BaseError",
+    "ExceptionHandler",
+    "ExceptionType",
+    "configure_logging",
+    "disable_logging",
+    "add_middleware",
+    "PaginatedResponse",
+    "PaginationParams",
+    "HeavyPaginationParams",
+    "SortParams",
+    "FilterParams",
+    "SortFilterParams",
+    "PageFilterParams",
+    "PageSortParams",
+    "PageSortFilterParams",
+    "HeavyPageSortFilterParams",
+    "gen_random_id",
+    "datetime_to_timestamp",
+    "optional_import",
+]

{crypticorn_utils-0.1.0rc1 → crypticorn_utils-1.0.0rc1}/crypticorn_utils/_migration.py

@@ -1,5 +1,6 @@
 # This file is used to check if the crypticorn version is greater than 2.18
 # This is to be compatible with this new utils library
+# otherwise prometheus reqisters metrics twice, resulting in an exception
 
 import importlib.metadata
 from importlib.metadata import PackageNotFoundError
@@ -9,4 +10,4 @@ try:
     parts = crypticorn_version.split(".")
     has_migrated = parts[0] >= "2" and parts[1] > "18"
 except PackageNotFoundError:
-    has_migrated = False
+    has_migrated = True

{crypticorn_utils-0.1.0rc1 → crypticorn_utils-1.0.0rc1}/crypticorn_utils/ansi_colors.py

@@ -1,7 +1,4 @@
-try:
-    from enum import StrEnum
-except ImportError:
-    from strenum import StrEnum
+from enum import StrEnum
 
 
 class AnsiColors(StrEnum):

{crypticorn_utils-0.1.0rc1 → crypticorn_utils-1.0.0rc1}/crypticorn_utils/auth.py

@@ -1,11 +1,17 @@
 import json
+from enum import StrEnum
 from typing import Union
 
 from crypticorn.auth import AuthClient, Configuration, Verify200Response
 from crypticorn.auth.client.exceptions import ApiException
-from crypticorn_utils.enums import Scope, BaseUrl
-from crypticorn_utils.exceptions import ApiError, ExceptionContent, HTTPException
-from fastapi import Depends, Query
+from crypticorn_utils.enums import BaseUrl
+from crypticorn_utils.exceptions import (
+    BaseError,
+    ErrorLevel,
+    ErrorType,
+    ExceptionHandler,
+)
+from fastapi import Depends, HTTPException, Query, status
 from fastapi.security import (
     APIKeyHeader,
     HTTPAuthorizationCredentials,
@@ -16,6 +22,79 @@ from fastapi.security import (
 )
 from typing_extensions import Annotated
 
+
+class AuthErrorCodes(StrEnum):
+    INVALID_API_KEY = "invalid_api_key"
+    EXPIRED_API_KEY = "expired_api_key"
+    INVALID_BEARER = "invalid_bearer"
+    EXPIRED_BEARER = "expired_bearer"
+    INVALID_BASIC_AUTH = "invalid_basic_auth"
+    NO_CREDENTIALS = "no_credentials"
+    INSUFFICIENT_SCOPES = "insufficient_scopes"
+    UNKNOWN_ERROR = "unknown_error"
+
+
+class AuthError(BaseError):
+    INVALID_API_KEY = (
+        AuthErrorCodes.INVALID_API_KEY,
+        ErrorType.USER_ERROR,
+        ErrorLevel.ERROR,
+        status.HTTP_401_UNAUTHORIZED,
+        status.WS_1008_POLICY_VIOLATION,
+    )
+    INVALID_BASIC_AUTH = (
+        AuthErrorCodes.INVALID_BASIC_AUTH,
+        ErrorType.USER_ERROR,
+        ErrorLevel.ERROR,
+        status.HTTP_401_UNAUTHORIZED,
+        status.WS_1008_POLICY_VIOLATION,
+    )
+    INVALID_BEARER = (
+        AuthErrorCodes.INVALID_BEARER,
+        ErrorType.USER_ERROR,
+        ErrorLevel.ERROR,
+        status.HTTP_401_UNAUTHORIZED,
+        status.WS_1008_POLICY_VIOLATION,
+    )
+    EXPIRED_API_KEY = (
+        AuthErrorCodes.EXPIRED_API_KEY,
+        ErrorType.USER_ERROR,
+        ErrorLevel.ERROR,
+        status.HTTP_401_UNAUTHORIZED,
+        status.WS_1008_POLICY_VIOLATION,
+    )
+    EXPIRED_BEARER = (
+        AuthErrorCodes.EXPIRED_BEARER,
+        ErrorType.USER_ERROR,
+        ErrorLevel.ERROR,
+        status.HTTP_401_UNAUTHORIZED,
+        status.WS_1008_POLICY_VIOLATION,
+    )
+    NO_CREDENTIALS = (
+        AuthErrorCodes.NO_CREDENTIALS,
+        ErrorType.USER_ERROR,
+        ErrorLevel.ERROR,
+        status.HTTP_401_UNAUTHORIZED,
+        status.WS_1008_POLICY_VIOLATION,
+    )
+    INSUFFICIENT_SCOPES = (
+        AuthErrorCodes.INSUFFICIENT_SCOPES,
+        ErrorType.USER_ERROR,
+        ErrorLevel.ERROR,
+        status.HTTP_403_FORBIDDEN,
+        status.WS_1008_POLICY_VIOLATION,
+    )
+    UNKNOWN_ERROR = (
+        AuthErrorCodes.UNKNOWN_ERROR,
+        ErrorType.SERVER_ERROR,
+        ErrorLevel.ERROR,
+        status.HTTP_500_INTERNAL_SERVER_ERROR,
+        status.WS_1011_INTERNAL_ERROR,
+    )
+
+
+handler = ExceptionHandler(callback=AuthError.from_identifier)
+
 AUTHENTICATE_HEADER = "WWW-Authenticate"
 BEARER_AUTH_SCHEME = "Bearer"
 APIKEY_AUTH_SCHEME = "X-API-Key"
@@ -80,19 +159,17 @@ class AuthHandler:
         return await self.client.login.verify_basic_auth(basic.username, basic.password)
 
     async def _validate_scopes(
-        self, api_scopes: list[Scope], user_scopes: list[Scope]
-    ) -> bool:
+        self, api_scopes: list[str], user_scopes: list[str]
+    ) -> None:
         """
         Checks if the required scopes are a subset of the user scopes.
         """
         if not set(api_scopes).issubset(user_scopes):
-            raise HTTPException(
-                content=ExceptionContent(
-                    error=ApiError.INSUFFICIENT_SCOPES,
-                    message="Insufficient scopes to access this resource (required: "
-                    + ", ".join(api_scopes)
-                    + ")",
-                ),
+            raise handler.build_exception(
+                AuthErrorCodes.INSUFFICIENT_SCOPES,
+                "Insufficient scopes to access this resource (required: "
+                + ", ".join(api_scopes)
+                + ")",
             )
 
     async def _extract_message(self, e: ApiException) -> str:
@@ -119,33 +196,24 @@ class AuthHandler:
             # Unfortunately, we cannot share the error messages defined in python/crypticorn/common/errors.py with the typescript client
             message = await self._extract_message(e)
             if message == "Invalid API key":
-                error = ApiError.INVALID_API_KEY
+                error = AuthErrorCodes.INVALID_API_KEY
             elif message == "API key expired":
-                error = ApiError.EXPIRED_API_KEY
+                error = AuthErrorCodes.EXPIRED_API_KEY
             elif message == "jwt expired":
-                error = ApiError.EXPIRED_BEARER
+                error = AuthErrorCodes.EXPIRED_BEARER
             elif message == "Invalid basic authentication credentials":
-                error = ApiError.INVALID_BASIC_AUTH
+                error = AuthErrorCodes.INVALID_BASIC_AUTH
             else:
                 message = "Invalid bearer token"
                 error = (
-                    ApiError.INVALID_BEARER
+                    AuthErrorCodes.INVALID_BEARER
                 )  # jwt malformed, jwt not active (https://www.npmjs.com/package/jsonwebtoken#errors--codes)
-            return HTTPException(
-                content=ExceptionContent(
-                    error=error,
-                    message=message,
-                ),
-            )
+            return handler.build_exception(error, message)
+
         elif isinstance(e, HTTPException):
             return e
         else:
-            return HTTPException(
-                content=ExceptionContent(
-                    error=ApiError.UNKNOWN_ERROR,
-                    message=str(e),
-                ),
-            )
+            return handler.build_exception(AuthErrorCodes.UNKNOWN_ERROR, str(e))
 
     async def api_key_auth(
         self,
@@ -162,11 +230,9 @@ class AuthHandler:
                 bearer=None, api_key=api_key, basic=None, sec=sec
             )
         except HTTPException as e:
-            raise HTTPException(
-                content=ExceptionContent(
-                    error=ApiError.from_json(e.detail),
-                    message=e.detail.get("message"),
-                ),
+            raise handler.build_exception(
+                e.detail.get("code"),
+                e.detail.get("message"),
                 headers={AUTHENTICATE_HEADER: APIKEY_AUTH_SCHEME},
             )
 
@@ -188,11 +254,9 @@ class AuthHandler:
                 bearer=bearer, api_key=None, basic=None, sec=sec
             )
         except HTTPException as e:
-            raise HTTPException(
-                content=ExceptionContent(
-                    error=ApiError.from_json(e.detail),
-                    message=e.detail.get("message"),
-                ),
+            raise handler.build_exception(
+                e.detail.get("code"),
+                e.detail.get("message"),
                 headers={AUTHENTICATE_HEADER: BEARER_AUTH_SCHEME},
             )
 
@@ -208,11 +272,9 @@ class AuthHandler:
                 basic=credentials, bearer=None, api_key=None, sec=None
             )
         except HTTPException as e:
-            raise HTTPException(
-                content=ExceptionContent(
-                    error=ApiError.from_json(e.detail),
-                    message=e.detail.get("message"),
-                ),
+            raise handler.build_exception(
+                e.detail.get("code"),
+                e.detail.get("message"),
                 headers={AUTHENTICATE_HEADER: BASIC_AUTH_SCHEME},
             )
 
@@ -235,11 +297,9 @@ class AuthHandler:
                 basic=None, bearer=bearer, api_key=api_key, sec=sec
             )
         except HTTPException as e:
-            raise HTTPException(
-                content=ExceptionContent(
-                    error=ApiError.from_json(e.detail),
-                    message=e.detail.get("message"),
-                ),
+            raise handler.build_exception(
+                e.detail.get("code"),
+                e.detail.get("message"),
                 headers={
                     AUTHENTICATE_HEADER: f"{BEARER_AUTH_SCHEME}, {APIKEY_AUTH_SCHEME}"
                 },
@@ -287,11 +347,9 @@ class AuthHandler:
         if last_error:
             raise last_error
         else:
-            raise HTTPException(
-                content=ExceptionContent(
-                    error=ApiError.NO_CREDENTIALS,
-                    message="No credentials provided. Check the WWW-Authenticate header for the available authentication methods.",
-                ),
+            raise handler.build_exception(
+                AuthErrorCodes.NO_CREDENTIALS,
+                "No credentials provided. Check the WWW-Authenticate header for the available authentication methods.",
                 headers={
                     AUTHENTICATE_HEADER: f"{BEARER_AUTH_SCHEME}, {APIKEY_AUTH_SCHEME}, {BASIC_AUTH_SCHEME}"
                 },

crypticorn_utils-1.0.0rc1/crypticorn_utils/enums.py

@@ -0,0 +1,55 @@
+"""Defines common enumerations used throughout the codebase for type safety and consistency."""
+
+from enum import StrEnum
+
+
+class Exchange(StrEnum):
+    """All exchanges used in the crypticorn ecosystem. Refer to the APIs for support for a specific usecase (data, trading, etc.)."""
+
+    KUCOIN = "kucoin"
+    BINGX = "bingx"
+    BINANCE = "binance"
+    BYBIT = "bybit"
+    HYPERLIQUID = "hyperliquid"
+    BITGET = "bitget"
+    GATEIO = "gateio"
+    BITSTAMP = "bitstamp"
+
+
+class MarketType(StrEnum):
+    """
+    Market types
+    """
+
+    SPOT = "spot"
+    FUTURES = "futures"
+
+
+class ApiEnv(StrEnum):
+    """The environment the API is being used with."""
+
+    PROD = "prod"
+    DEV = "dev"
+    LOCAL = "local"
+    DOCKER = "docker"
+
+
+class BaseUrl(StrEnum):
+    """The base URL to connect to the API."""
+
+    PROD = "https://api.crypticorn.com"
+    DEV = "https://api.crypticorn.dev"
+    LOCAL = "http://localhost"
+    DOCKER = "http://host.docker.internal"
+
+    @classmethod
+    def from_env(cls, env: ApiEnv) -> "BaseUrl":
+        """Load the base URL from the API environment."""
+        if env == ApiEnv.PROD:
+            return cls.PROD
+        elif env == ApiEnv.DEV:
+            return cls.DEV
+        elif env == ApiEnv.LOCAL:
+            return cls.LOCAL
+        elif env == ApiEnv.DOCKER:
+            return cls.DOCKER

crypticorn_utils-1.0.0rc1/crypticorn_utils/errors.py

@@ -0,0 +1,25 @@
+"""Comprehensive error handling system defining various API error types, HTTP exceptions, and error content structures."""
+
+from enum import StrEnum
+
+
+class ErrorType(StrEnum):
+    """Type of the API error."""
+
+    USER_ERROR = "user error"
+    """user error by people using our services"""
+    EXCHANGE_ERROR = "exchange error"
+    """re-tryable error by the exchange or network conditions"""
+    SERVER_ERROR = "server error"
+    """server error that needs a new version rollout for a fix"""
+    NO_ERROR = "no error"
+    """error that does not need to be handled or does not affect the program or is a placeholder."""
+
+
+class ErrorLevel(StrEnum):
+    """Level of the API error."""
+
+    ERROR = "error"
+    INFO = "info"
+    SUCCESS = "success"
+    WARNING = "warning"