crypticorn 2.8.0rc8__py3-none-any.whl → 2.8.0rc9__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (47) hide show
  1. crypticorn/__init__.py +4 -0
  2. crypticorn/common/__init__.py +2 -0
  3. crypticorn/common/ansi_colors.py +2 -1
  4. crypticorn/common/auth.py +2 -2
  5. crypticorn/common/enums.py +2 -0
  6. crypticorn/common/errors.py +8 -5
  7. crypticorn/common/exceptions.py +24 -20
  8. crypticorn/common/logging.py +11 -13
  9. crypticorn/common/middleware.py +2 -1
  10. crypticorn/common/mixins.py +10 -3
  11. crypticorn/common/openapi.py +11 -0
  12. crypticorn/common/pagination.py +2 -0
  13. crypticorn/common/router/admin_router.py +3 -3
  14. crypticorn/common/router/status_router.py +9 -2
  15. crypticorn/common/scopes.py +3 -3
  16. crypticorn/common/urls.py +9 -0
  17. crypticorn/common/utils.py +16 -8
  18. crypticorn/common/warnings.py +63 -0
  19. crypticorn/hive/utils.py +1 -2
  20. crypticorn/metrics/client/__init__.py +11 -0
  21. crypticorn/metrics/client/api/__init__.py +2 -0
  22. crypticorn/metrics/client/api/admin_api.py +1452 -0
  23. crypticorn/metrics/client/api/exchanges_api.py +51 -40
  24. crypticorn/metrics/client/api/indicators_api.py +49 -32
  25. crypticorn/metrics/client/api/logs_api.py +7 -7
  26. crypticorn/metrics/client/api/marketcap_api.py +28 -25
  27. crypticorn/metrics/client/api/markets_api.py +50 -278
  28. crypticorn/metrics/client/api/quote_currencies_api.py +289 -0
  29. crypticorn/metrics/client/api/status_api.py +4 -231
  30. crypticorn/metrics/client/api/tokens_api.py +241 -37
  31. crypticorn/metrics/client/models/__init__.py +9 -0
  32. crypticorn/metrics/client/models/api_error_identifier.py +115 -0
  33. crypticorn/metrics/client/models/api_error_level.py +37 -0
  34. crypticorn/metrics/client/models/api_error_type.py +37 -0
  35. crypticorn/metrics/client/models/exception_detail.py +6 -3
  36. crypticorn/metrics/client/models/exchange_mapping.py +121 -0
  37. crypticorn/metrics/client/models/internal_exchange.py +39 -0
  38. crypticorn/metrics/client/models/log_level.py +38 -0
  39. crypticorn/metrics/client/models/market_type.py +35 -0
  40. crypticorn/metrics/client/models/marketcap_ranking.py +87 -0
  41. crypticorn/metrics/client/models/ohlcv.py +113 -0
  42. crypticorn/metrics/main.py +14 -2
  43. {crypticorn-2.8.0rc8.dist-info → crypticorn-2.8.0rc9.dist-info}/METADATA +3 -2
  44. {crypticorn-2.8.0rc8.dist-info → crypticorn-2.8.0rc9.dist-info}/RECORD +47 -34
  45. {crypticorn-2.8.0rc8.dist-info → crypticorn-2.8.0rc9.dist-info}/WHEEL +0 -0
  46. {crypticorn-2.8.0rc8.dist-info → crypticorn-2.8.0rc9.dist-info}/entry_points.txt +0 -0
  47. {crypticorn-2.8.0rc8.dist-info → crypticorn-2.8.0rc9.dist-info}/top_level.txt +0 -0
crypticorn/__init__.py CHANGED
@@ -6,9 +6,13 @@ We adhere to [Semantic Versioning](https://semver.org/).
6
6
  You can find the full Changelog [below](#changelog).
7
7
  """
8
8
 
9
+ import warnings
10
+ import logging
9
11
  from crypticorn.common.logging import configure_logging
10
12
 
13
+ warnings.filterwarnings("default", "", DeprecationWarning)
11
14
  configure_logging()
15
+ logging.captureWarnings(True)
12
16
 
13
17
  from crypticorn.client import ApiClient
14
18
 
@@ -11,5 +11,7 @@ from crypticorn.common.pagination import *
11
11
  from crypticorn.common.logging import *
12
12
  from crypticorn.common.ansi_colors import *
13
13
  from crypticorn.common.middleware import *
14
+ from crypticorn.common.warnings import *
15
+ from crypticorn.common.openapi import *
14
16
  from crypticorn.common.router.status_router import router as status_router
15
17
  from crypticorn.common.router.admin_router import router as admin_router
@@ -1,8 +1,9 @@
1
1
  from enum import StrEnum
2
- from typing import TYPE_CHECKING
3
2
 
4
3
 
5
4
  class AnsiColors(StrEnum):
5
+ """Provides a collection of ANSI color codes for terminal text formatting, including regular, bright, and bold text colors. Useful for creating colorful and readable console output."""
6
+
6
7
  # Regular Text Colors
7
8
  BLACK = "\033[30m" # black
8
9
  RED = "\033[31m" # red
crypticorn/common/auth.py CHANGED
@@ -38,8 +38,8 @@ class AuthHandler:
38
38
  """
39
39
  Middleware for verifying API requests. Verifies the validity of the authentication token, scopes, etc.
40
40
 
41
- @param base_url: The base URL of the API.
42
- @param api_version: The version of the API.
41
+ :param base_url: The base URL of the API.
42
+ :param api_version: The version of the API.
43
43
  """
44
44
 
45
45
  def __init__(
@@ -1,3 +1,5 @@
1
+ """Defines common enumerations used throughout the codebase for type safety and consistency."""
2
+
1
3
  from enum import StrEnum
2
4
  from crypticorn.common.mixins import ValidateEnumMixin, ExcludeEnumMixin
3
5
 
@@ -1,10 +1,12 @@
1
+ """Comprehensive error handling system defining various API error types, HTTP exceptions, and error content structures."""
2
+
1
3
  from enum import Enum, StrEnum
2
4
  from fastapi import status
3
5
  from crypticorn.common.mixins import ExcludeEnumMixin, ApiErrorFallback
4
6
 
5
7
 
6
8
  class ApiErrorType(ExcludeEnumMixin, StrEnum):
7
- """Type of API error"""
9
+ """Type of the API error."""
8
10
 
9
11
  USER_ERROR = "user error"
10
12
  """user error by people using our services"""
@@ -17,7 +19,7 @@ class ApiErrorType(ExcludeEnumMixin, StrEnum):
17
19
 
18
20
 
19
21
  class ApiErrorIdentifier(ExcludeEnumMixin, StrEnum):
20
- """API error identifiers"""
22
+ """Unique identifier of the API error."""
21
23
 
22
24
  ALLOCATION_BELOW_EXPOSURE = "allocation_below_current_exposure"
23
25
  ALLOCATION_BELOW_MINIMUM = "allocation_below_min_amount"
@@ -103,7 +105,7 @@ class ApiErrorIdentifier(ExcludeEnumMixin, StrEnum):
103
105
 
104
106
 
105
107
  class ApiErrorLevel(ExcludeEnumMixin, StrEnum):
106
- """API error levels"""
108
+ """Level of the API error."""
107
109
 
108
110
  ERROR = "error"
109
111
  INFO = "info"
@@ -112,7 +114,8 @@ class ApiErrorLevel(ExcludeEnumMixin, StrEnum):
112
114
 
113
115
 
114
116
  class ApiError(ExcludeEnumMixin, Enum, metaclass=ApiErrorFallback):
115
- """API error codes. Fallback to UNKNOWN_ERROR for error codes not yet published to PyPI."""
117
+ # Fallback to UNKNOWN_ERROR for error codes not yet published to PyPI.
118
+ """Crypticorn API error enumeration."""
116
119
 
117
120
  ALLOCATION_BELOW_EXPOSURE = (
118
121
  ApiErrorIdentifier.ALLOCATION_BELOW_EXPOSURE,
@@ -518,7 +521,7 @@ class ApiError(ExcludeEnumMixin, Enum, metaclass=ApiErrorFallback):
518
521
 
519
522
 
520
523
  class StatusCodeMapper:
521
- """Map API errors to HTTP status codes."""
524
+ """Mapping of API errors to HTTP/Websocket status codes."""
522
525
 
523
526
  _mapping = {
524
527
  # Authentication/Authorization
@@ -1,4 +1,4 @@
1
- from typing import Optional, Dict, Any, Literal
1
+ from typing import Optional, Dict, Any
2
2
  from enum import StrEnum
3
3
  from pydantic import BaseModel, Field
4
4
  from fastapi import HTTPException as FastAPIHTTPException, Request, FastAPI
@@ -7,16 +7,19 @@ from fastapi.responses import JSONResponse
7
7
  from crypticorn.common import ApiError, ApiErrorIdentifier, ApiErrorType, ApiErrorLevel
8
8
  import logging
9
9
  import json
10
- logger = logging.getLogger(__name__)
11
10
 
11
+ _logger = logging.getLogger("crypticorn")
12
+
13
+
14
+ class _ExceptionType(StrEnum):
15
+ """The protocol the exception is called from"""
12
16
 
13
- class ExceptionType(StrEnum):
14
17
  HTTP = "http"
15
18
  WEBSOCKET = "websocket"
16
19
 
17
20
 
18
21
  class ExceptionDetail(BaseModel):
19
- """This is the detail of the exception. It is used to enrich the exception with additional information by unwrapping the ApiError into its components."""
22
+ """Exception details returned to the client."""
20
23
 
21
24
  message: Optional[str] = Field(None, description="An additional error message")
22
25
  code: ApiErrorIdentifier = Field(..., description="The unique error code")
@@ -27,14 +30,14 @@ class ExceptionDetail(BaseModel):
27
30
 
28
31
 
29
32
  class ExceptionContent(BaseModel):
30
- """This is the detail of the exception. Pass an ApiError to the constructor and an optional human readable message."""
33
+ """Exception content used when raising an exception."""
31
34
 
32
35
  error: ApiError = Field(..., description="The unique error code")
33
36
  message: Optional[str] = Field(None, description="An additional error message")
34
37
  details: Any = Field(None, description="Additional details about the error")
35
38
 
36
39
  def enrich(
37
- self, _type: Optional[ExceptionType] = ExceptionType.HTTP
40
+ self, _type: Optional[_ExceptionType] = _ExceptionType.HTTP
38
41
  ) -> ExceptionDetail:
39
42
  return ExceptionDetail(
40
43
  message=self.message,
@@ -43,7 +46,7 @@ class ExceptionContent(BaseModel):
43
46
  level=self.error.level,
44
47
  status_code=(
45
48
  self.error.http_code
46
- if _type == ExceptionType.HTTP
49
+ if _type == _ExceptionType.HTTP
47
50
  else self.error.websocket_code
48
51
  ),
49
52
  details=self.details,
@@ -53,14 +56,14 @@ class ExceptionContent(BaseModel):
53
56
  class HTTPException(FastAPIHTTPException):
54
57
  """A custom HTTP exception wrapper around FastAPI's HTTPException.
55
58
  It allows for a more structured way to handle errors, with a message and an error code. The status code is being derived from the detail's error.
56
- The ApiError class is the source of truth for everything. If the error is not yet implemented, there are fallbacks to avoid errors while testing.
59
+ The ApiError class is the source of truth. If the error is not yet implemented, there are fallbacks in place.
57
60
  """
58
61
 
59
62
  def __init__(
60
63
  self,
61
64
  content: ExceptionContent,
62
65
  headers: Optional[Dict[str, str]] = None,
63
- _type: Optional[ExceptionType] = ExceptionType.HTTP,
66
+ _type: Optional[_ExceptionType] = _ExceptionType.HTTP,
64
67
  ):
65
68
  self.content = content
66
69
  self.headers = headers
@@ -81,11 +84,11 @@ class WebSocketException(HTTPException):
81
84
  def __init__(
82
85
  self, content: ExceptionContent, headers: Optional[Dict[str, str]] = None
83
86
  ):
84
- super().__init__(content, headers, _type=ExceptionType.WEBSOCKET)
87
+ super().__init__(content, headers, _type=_ExceptionType.WEBSOCKET)
85
88
 
86
89
  @classmethod
87
90
  def from_http_exception(cls, http_exception: HTTPException):
88
- """This is a helper method to convert an HTTPException to a WebSocketException."""
91
+ """Helper method to convert an HTTPException to a WebSocketException."""
89
92
  return WebSocketException(
90
93
  content=http_exception.content,
91
94
  headers=http_exception.headers,
@@ -93,46 +96,47 @@ class WebSocketException(HTTPException):
93
96
 
94
97
 
95
98
  async def general_handler(request: Request, exc: Exception) -> JSONResponse:
96
- """This is the default exception handler for all exceptions."""
99
+ """Default exception handler for all exceptions."""
97
100
  body = ExceptionContent(message=str(exc), error=ApiError.UNKNOWN_ERROR)
98
101
  res = JSONResponse(
99
102
  status_code=body.enrich().status_code,
100
103
  content=HTTPException(content=body).detail,
101
104
  )
102
- logger.error(f"Response validation error: {json.loads(res.__dict__.get('body'))}")
105
+ _logger.error(f"Response validation error: {json.loads(res.__dict__.get('body'))}")
103
106
  return res
104
107
 
105
108
 
106
109
  async def request_validation_handler(
107
110
  request: Request, exc: RequestValidationError
108
111
  ) -> JSONResponse:
109
- """This is the exception handler for all request validation errors."""
112
+ """Exception handler for all request validation errors."""
110
113
  body = ExceptionContent(message=str(exc), error=ApiError.INVALID_DATA_REQUEST)
111
114
  res = JSONResponse(
112
115
  status_code=body.enrich().status_code,
113
116
  content=HTTPException(content=body).detail,
114
117
  )
115
- logger.error(f"Response validation error: {json.loads(res.__dict__.get('body'))}")
118
+ _logger.error(f"Response validation error: {json.loads(res.__dict__.get('body'))}")
116
119
  return res
117
120
 
118
121
 
119
122
  async def response_validation_handler(
120
123
  request: Request, exc: ResponseValidationError
121
124
  ) -> JSONResponse:
122
- """This is the exception handler for all response validation errors."""
125
+ """Exception handler for all response validation errors."""
123
126
  body = ExceptionContent(message=str(exc), error=ApiError.INVALID_DATA_RESPONSE)
124
127
  res = JSONResponse(
125
128
  status_code=body.enrich().status_code,
126
129
  content=HTTPException(content=body).detail,
127
130
  )
128
- logger.error(f"Response validation error: {json.loads(res.__dict__.get('body'))}")
131
+ _logger.error(f"Response validation error: {json.loads(res.__dict__.get('body'))}")
129
132
  return res
130
133
 
131
134
 
132
135
  async def http_handler(request: Request, exc: HTTPException) -> JSONResponse:
133
- """This is the exception handler for HTTPExceptions. It unwraps the HTTPException and returns the detail in a flat JSON response."""
134
- logger.error(f"HTTP error: {exc.detail}")
135
- return JSONResponse(status_code=exc.status_code, content=exc.detail)
136
+ """Exception handler for HTTPExceptions. It unwraps the HTTPException and returns the detail in a flat JSON response."""
137
+ res = JSONResponse(status_code=exc.status_code, content=exc.detail)
138
+ _logger.error(f"HTTP error: {json.loads(res.__dict__.get('body'))}")
139
+ return res
136
140
 
137
141
 
138
142
  def register_exception_handlers(app: FastAPI):
@@ -1,18 +1,14 @@
1
1
  from __future__ import annotations
2
2
 
3
- # shared_logger.py
4
3
  import logging
5
4
  import sys
6
- from contextvars import ContextVar
7
- from contextlib import asynccontextmanager
8
- import json
9
- from pydantic import BaseModel
10
5
  from enum import StrEnum
11
6
  from crypticorn.common.mixins import ValidateEnumMixin
12
7
  from crypticorn.common.ansi_colors import AnsiColors as C
13
8
  from datetime import datetime
14
9
  import os
15
-
10
+
11
+
16
12
  class LogLevel(ValidateEnumMixin, StrEnum):
17
13
  DEBUG = "DEBUG"
18
14
  INFO = "INFO"
@@ -22,6 +18,7 @@ class LogLevel(ValidateEnumMixin, StrEnum):
22
18
 
23
19
  @classmethod
24
20
  def get_color(cls, level: str) -> str:
21
+ """Get the ansi color based on the log level."""
25
22
  if level == cls.DEBUG:
26
23
  return C.GREEN_BRIGHT
27
24
  elif level == cls.INFO:
@@ -37,10 +34,12 @@ class LogLevel(ValidateEnumMixin, StrEnum):
37
34
 
38
35
  @staticmethod
39
36
  def get_level(level: "LogLevel") -> int:
37
+ """Get the integer value from a log level name."""
40
38
  return logging._nameToLevel.get(level, logging.INFO)
41
39
 
42
40
  @staticmethod
43
41
  def get_name(level: int) -> "LogLevel":
42
+ """Get the level name from the integer value of a log level."""
44
43
  return LogLevel(logging._levelToName.get(level, "INFO"))
45
44
 
46
45
 
@@ -50,11 +49,10 @@ _LOGFORMAT = (
50
49
  f"%(levelcolor)s%(levelname)s{C.RESET} - "
51
50
  f"%(message)s"
52
51
  )
53
- _PLAIN_LOGFORMAT = "%(asctime)s - " "%(name)s - " "%(levelname)s - " "%(message)s"
54
52
  _DATEFMT = "%Y-%m-%d %H:%M:%S.%f:"
55
53
 
56
54
 
57
- class CustomFormatter(logging.Formatter):
55
+ class _CustomFormatter(logging.Formatter):
58
56
  def __init__(self, *args, **kwargs):
59
57
  super().__init__(*args, **kwargs)
60
58
 
@@ -80,8 +78,8 @@ def configure_logging(
80
78
  ) -> None:
81
79
  """Configures the logging for the application.
82
80
  Run this function as early as possible in the application (for example using the `lifespan` parameter in FastAPI).
83
- Then use can use the default `logging.getLogger(__name__)` method to get the logger.
84
- :param name: The name of the logger. If not provided, the root logger will be used. Use a name if use multiple loggers in the same application.
81
+ Then use can use the default `logging.getLogger(__name__)` method to get the logger (or <name> if you set the name parameter).
82
+ :param name: The name of the logger. If not provided, the root logger will be used. Use a name if you use multiple loggers in the same application.
85
83
  :param fmt: The format of the log message.
86
84
  :param datefmt: The date format of the log message.
87
85
  :param stdout_level: The level of the log message to be printed to the console.
@@ -99,7 +97,7 @@ def configure_logging(
99
97
  # Configure stdout handler
100
98
  stdout_handler = logging.StreamHandler(sys.stdout)
101
99
  stdout_handler.setLevel(stdout_level)
102
- stdout_handler.setFormatter(CustomFormatter(fmt=fmt, datefmt=datefmt))
100
+ stdout_handler.setFormatter(_CustomFormatter(fmt=fmt, datefmt=datefmt))
103
101
  for filter in filters:
104
102
  stdout_handler.addFilter(filter)
105
103
  logger.addHandler(stdout_handler)
@@ -111,11 +109,11 @@ def configure_logging(
111
109
  log_file, maxBytes=10 * 1024 * 1024, backupCount=5
112
110
  )
113
111
  file_handler.setLevel(file_level)
114
- file_handler.setFormatter(CustomFormatter(fmt=fmt, datefmt=datefmt))
112
+ file_handler.setFormatter(_CustomFormatter(fmt=fmt, datefmt=datefmt))
115
113
  for filter in filters:
116
114
  file_handler.addFilter(filter)
117
115
  logger.addHandler(file_handler)
118
-
116
+
119
117
  if name:
120
118
  logger.propagate = False
121
119
 
@@ -1,7 +1,7 @@
1
1
  from fastapi import FastAPI
2
2
  from fastapi.middleware.cors import CORSMiddleware
3
3
  from crypticorn.common.logging import configure_logging
4
- import logging
4
+ from contextlib import asynccontextmanager
5
5
 
6
6
 
7
7
  def add_cors_middleware(app: "FastAPI"):
@@ -18,6 +18,7 @@ def add_cors_middleware(app: "FastAPI"):
18
18
  )
19
19
 
20
20
 
21
+ @asynccontextmanager
21
22
  async def default_lifespan(app: FastAPI):
22
23
  """Default lifespan for the applications.
23
24
  This is used to configure the logging for the application.
@@ -1,7 +1,9 @@
1
1
  from enum import EnumMeta
2
2
  import logging
3
+ import warnings
4
+ from crypticorn.common.warnings import CrypticornDeprecatedSince28
3
5
 
4
- logger = logging.getLogger("uvicorn")
6
+ _logger = logging.getLogger("crypticorn")
5
7
 
6
8
 
7
9
  class ValidateEnumMixin:
@@ -35,7 +37,12 @@ class ValidateEnumMixin:
35
37
 
36
38
  # This Mixin will be removed in a future version. And has no effect from now on
37
39
  class ExcludeEnumMixin:
38
- """Mixin to exclude enum from OpenAPI schema. We use this to avoid duplicating enums when generating client code from the openapi spec."""
40
+ """(deprecated) Mixin to exclude enum from OpenAPI schema. We use this to avoid duplicating enums when generating client code from the openapi spec."""
41
+
42
+ warnings.warn(
43
+ "The `ExcludeEnumMixin` class is deprecated. Should be removed from enums inheriting this class.",
44
+ category=CrypticornDeprecatedSince28,
45
+ )
39
46
 
40
47
  @classmethod
41
48
  def __get_pydantic_json_schema__(cls, core_schema, handler):
@@ -51,7 +58,7 @@ class ApiErrorFallback(EnumMeta):
51
58
  # Let Pydantic/internal stuff pass silently ! fragile
52
59
  if name.startswith("__"):
53
60
  raise AttributeError(name)
54
- logger.warning(
61
+ _logger.warning(
55
62
  f"Unknown enum member '{name}' - update crypticorn package or check for typos"
56
63
  )
57
64
  return cls.UNKNOWN_ERROR
@@ -0,0 +1,11 @@
1
+ default_tags = [
2
+ {
3
+ "name": "Status",
4
+ "description": "These endpoints contain status operations.",
5
+ },
6
+ {
7
+ "name": "Admin",
8
+ "description": "These endpoints contain debugging and monitoring operations. They require admin scopes.",
9
+ }
10
+ ]
11
+
@@ -1,3 +1,5 @@
1
+ """Utilities for handling paginated API responses and cursor-based pagination."""
2
+
1
3
  from typing import Generic, Type, TypeVar, List, Optional, Literal
2
4
  from pydantic import BaseModel, Field, model_validator
3
5
 
@@ -20,10 +20,10 @@ router = APIRouter(tags=["Admin"], prefix="/admin")
20
20
  START_TIME = time.time()
21
21
 
22
22
 
23
- @router.get("/log-level", status_code=200, operation_id="getLogLevel")
23
+ @router.get("/log-level", status_code=200, operation_id="getLogLevel", deprecated=True)
24
24
  async def get_logging_level() -> LogLevel:
25
25
  """
26
- Get the log level of the server logger.
26
+ Get the log level of the server logger. Will be removed in a future release.
27
27
  """
28
28
  return LogLevel.get_name(logging.getLogger().level)
29
29
 
@@ -39,7 +39,7 @@ def get_uptime(type: Literal["seconds", "human"] = "seconds") -> str:
39
39
 
40
40
 
41
41
  @router.get("/memory", operation_id="getMemoryUsage", status_code=200)
42
- def get_memory_usage() -> int:
42
+ def get_memory_usage() -> float:
43
43
  """
44
44
  Resident Set Size (RSS) in MB — the actual memory used by the process in RAM.
45
45
  Represents the physical memory footprint. Important for monitoring real usage.
@@ -1,12 +1,19 @@
1
+ """
2
+ This module contains the status router for the API.
3
+ It provides endpoints for checking the status of the API and get the server's time.
4
+ SHOULD ALLOW ACCESS TO THIS ROUTER WITHOUT.
5
+ >>> app.include_router(status_router)
6
+ """
7
+
1
8
  from datetime import datetime
2
9
  from typing import Literal
3
- from fastapi import APIRouter
10
+ from fastapi import APIRouter, Request
4
11
 
5
12
  router = APIRouter(tags=["Status"], prefix="")
6
13
 
7
14
 
8
15
  @router.get("/", operation_id="ping")
9
- async def ping() -> str:
16
+ async def ping(request: Request) -> dict:
10
17
  """
11
18
  Returns 'OK' if the API is running.
12
19
  """
@@ -54,7 +54,7 @@ class Scope(StrEnum):
54
54
 
55
55
  @classmethod
56
56
  def admin_scopes(cls) -> list["Scope"]:
57
- """Scopes that are only available to admins"""
57
+ """Scopes that are only available to admins."""
58
58
  return [
59
59
  cls.WRITE_TRADE_STRATEGIES,
60
60
  cls.WRITE_PAY_PRODUCTS,
@@ -64,14 +64,14 @@ class Scope(StrEnum):
64
64
 
65
65
  @classmethod
66
66
  def internal_scopes(cls) -> list["Scope"]:
67
- """Scopes that are only available to internal services"""
67
+ """Scopes that are only available to internal services."""
68
68
  return [
69
69
  cls.WRITE_TRADE_ACTIONS,
70
70
  ]
71
71
 
72
72
  @classmethod
73
73
  def purchaseable_scopes(cls) -> list["Scope"]:
74
- """Scopes that can be purchased"""
74
+ """Scopes that can be purchased."""
75
75
  return [
76
76
  cls.READ_PREDICTIONS,
77
77
  ]
crypticorn/common/urls.py CHANGED
@@ -3,6 +3,8 @@ from crypticorn.common.enums import ValidateEnumMixin
3
3
 
4
4
 
5
5
  class ApiEnv(StrEnum):
6
+ """The environment the API is being used with."""
7
+
6
8
  PROD = "prod"
7
9
  DEV = "dev"
8
10
  LOCAL = "local"
@@ -10,6 +12,8 @@ class ApiEnv(StrEnum):
10
12
 
11
13
 
12
14
  class BaseUrl(StrEnum):
15
+ """The base URL to connect to the API."""
16
+
13
17
  PROD = "https://api.crypticorn.com"
14
18
  DEV = "https://api.crypticorn.dev"
15
19
  LOCAL = "http://localhost"
@@ -17,6 +21,7 @@ class BaseUrl(StrEnum):
17
21
 
18
22
  @classmethod
19
23
  def from_env(cls, env: ApiEnv) -> "BaseUrl":
24
+ """Load the base URL from the API environment."""
20
25
  if env == ApiEnv.PROD:
21
26
  return cls.PROD
22
27
  elif env == ApiEnv.DEV:
@@ -28,10 +33,14 @@ class BaseUrl(StrEnum):
28
33
 
29
34
 
30
35
  class ApiVersion(StrEnum):
36
+ """Versions to use for the microservice APIs."""
37
+
31
38
  V1 = "v1"
32
39
 
33
40
 
34
41
  class Service(ValidateEnumMixin, StrEnum):
42
+ """The microservices available to connect to through the API"""
43
+
35
44
  HIVE = "hive"
36
45
  KLINES = "klines"
37
46
  PAY = "pay"
@@ -1,11 +1,14 @@
1
- from typing import Any, Union
1
+ """General utility functions and helper methods used across the codebase."""
2
+
3
+ from typing import Any
2
4
  from decimal import Decimal
3
5
  import string
4
6
  import random
5
- from fastapi import status
6
- from typing_extensions import deprecated
7
+ import typing_extensions
8
+ import warnings
7
9
 
8
- from crypticorn.common import ApiError, HTTPException, ExceptionContent
10
+ from crypticorn.common.exceptions import ApiError, HTTPException, ExceptionContent
11
+ from crypticorn.common.warnings import CrypticornDeprecatedSince25
9
12
 
10
13
 
11
14
  def throw_if_none(
@@ -33,7 +36,9 @@ def gen_random_id(length: int = 20) -> str:
33
36
  return "".join(random.choice(charset) for _ in range(length))
34
37
 
35
38
 
36
- @deprecated("Use math.isclose instead. Will be removed in a future version.")
39
+ @typing_extensions.deprecated(
40
+ "The `is_equal` method is deprecated; use `math.is_close` instead.", category=None
41
+ )
37
42
  def is_equal(
38
43
  a: float | Decimal,
39
44
  b: float | Decimal,
@@ -43,6 +48,10 @@ def is_equal(
43
48
  """
44
49
  Compare two Decimal numbers for approximate equality.
45
50
  """
51
+ warnings.warn(
52
+ "The `is_equal` method is deprecated; use `math.is_close` instead.",
53
+ category=CrypticornDeprecatedSince25,
54
+ )
46
55
  if not isinstance(a, Decimal):
47
56
  a = Decimal(str(a))
48
57
  if not isinstance(b, Decimal):
@@ -56,13 +65,12 @@ def is_equal(
56
65
 
57
66
  def optional_import(module_name: str, extra_name: str) -> Any:
58
67
  """
59
- Import a module optionally.
68
+ Tries to import a module. Raises `ImportError` if not found with a message to install the extra dependency.
60
69
  """
61
70
  try:
62
71
  return __import__(module_name)
63
72
  except ImportError as e:
64
- extra = f"[{extra_name}]"
65
73
  raise ImportError(
66
74
  f"Optional dependency '{module_name}' is required for this feature. "
67
- f"Install it with: pip install crypticorn{extra}"
75
+ f"Install it with: pip install crypticorn[{extra_name}]"
68
76
  ) from e
@@ -0,0 +1,63 @@
1
+ """Crypticorn-specific warnings."""
2
+
3
+ from __future__ import annotations
4
+
5
+
6
+ class CrypticornDeprecationWarning(DeprecationWarning):
7
+ """A Crypticorn specific deprecation warning.
8
+
9
+ This warning is raised when using deprecated functionality in Crypticorn. It provides information on when the
10
+ deprecation was introduced and the expected version in which the corresponding functionality will be removed.
11
+
12
+ Attributes:
13
+ message: Description of the warning.
14
+ since: Crypticorn version in what the deprecation was introduced.
15
+ expected_removal: Crypticorn version in what the corresponding functionality expected to be removed.
16
+ """
17
+
18
+ message: str
19
+ since: tuple[int, int]
20
+ expected_removal: tuple[int, int]
21
+
22
+ def __init__(
23
+ self,
24
+ message: str,
25
+ *args: object,
26
+ since: tuple[int, int],
27
+ expected_removal: tuple[int, int] | None = None,
28
+ ) -> None:
29
+ super().__init__(message, *args)
30
+ self.message = message.rstrip(".")
31
+ self.since = since
32
+ self.expected_removal = (
33
+ expected_removal if expected_removal is not None else (since[0] + 1, 0)
34
+ )
35
+
36
+ def __str__(self) -> str:
37
+ message = (
38
+ f"{self.message}. Deprecated in Crypticorn v{self.since[0]}.{self.since[1]}"
39
+ f" to be removed in v{self.expected_removal[0]}.{self.expected_removal[1]}."
40
+ )
41
+ return message
42
+
43
+
44
+ class CrypticornDeprecatedSince25(CrypticornDeprecationWarning):
45
+ """A specific `CrypticornDeprecationWarning` subclass defining functionality deprecated since Crypticorn 2.5."""
46
+
47
+ def __init__(self, message: str, *args: object) -> None:
48
+ super().__init__(message, *args, since=(2, 5), expected_removal=(3, 0))
49
+
50
+
51
+ class CrypticornDeprecatedSince28(CrypticornDeprecationWarning):
52
+ """A specific `CrypticornDeprecationWarning` subclass defining functionality deprecated since Crypticorn 2.8."""
53
+
54
+ def __init__(self, message: str, *args: object) -> None:
55
+ super().__init__(message, *args, since=(2, 8), expected_removal=(3, 0))
56
+
57
+
58
+ class CrypticornExperimentalWarning(Warning):
59
+ """A Crypticorn specific experimental functionality warning.
60
+
61
+ This warning is raised when using experimental functionality in Crypticorn.
62
+ It is raised to warn users that the functionality may change or be removed in future versions of Crypticorn.
63
+ """
crypticorn/hive/utils.py CHANGED
@@ -3,8 +3,7 @@ import os
3
3
  import tqdm
4
4
  import logging
5
5
 
6
- logger = logging.getLogger(__name__)
7
- logger.setLevel(logging.INFO)
6
+ logger = logging.getLogger("crypticorn")
8
7
 
9
8
 
10
9
  async def download_file(