balabs-kit 0.0.3__py3-none-any.whl

bakit/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.0.3"

bakit/sanic/__init__.py

@@ -0,0 +1,3 @@
+from .app import create_base_app
+
+__all__ = ["create_base_app"]

bakit/sanic/app.py

@@ -0,0 +1,53 @@
+from pathlib import Path
+
+from orjson import dumps
+from sanic import Sanic
+from sanic.response import text
+from sanic_ext import Extend
+from tortoise.contrib.sanic import register_tortoise
+
+from bakit import settings
+from bakit.sanic.listeners import setup_cache_listener, setup_sentry_listener
+from bakit.sanic.middlewares import cache_middleware_request, cache_middleware_response
+from bakit.settings import APP_NAME, LOGGING_CONFIG, TORTOISE_ORM
+from bakit.utils.metrics import view_metrics
+
+STATIC_DIR = Path(__file__).resolve().parent / "static"
+
+
+def create_base_app(app_name=APP_NAME, log_config=LOGGING_CONFIG, is_testing=False):
+    app = Sanic(app_name, strict_slashes=True, log_config=log_config, dumps=dumps)
+    app.config.FALLBACK_ERROR_FORMAT = "json"
+
+    app.config.CACHE_MIDDLEWARE_ENABLED = settings.CACHE_MIDDLEWARE_ENABLED
+
+    app.config.CORS_ORIGINS = settings.CORS_ORIGINS
+    app.config.CORS_METHODS = settings.CORS_METHODS
+
+    Extend(app)
+
+    app.static("/favicon.ico", STATIC_DIR / "favicon.png")
+
+    # listeners
+    app.register_listener(setup_cache_listener, "before_server_start")
+    app.register_listener(setup_sentry_listener, "before_server_start")
+
+    # middleware
+    app.register_middleware(cache_middleware_request, "request")
+    app.register_middleware(cache_middleware_response, "response")
+
+    # /ping/ endpoint is needed for load balancer health checks. Do not remove
+    @app.route("/ping/", methods=["GET"])
+    @view_metrics()
+    async def health(request):
+        return text("pong", status=200)
+
+    # Setup Tortoise ORM
+    if not is_testing:
+        register_tortoise(
+            app,
+            config=TORTOISE_ORM,
+            generate_schemas=False,
+        )
+
+    return app

bakit/sanic/decorators.py

@@ -0,0 +1,17 @@
+def no_cache(handler):
+    """
+    Mark a view (function or class-based) as non-cacheable.
+
+    When applied to:
+      • Function views — the decorated function will never be cached.
+      • Class-based views (HTTPMethodView subclasses) — all HTTP methods
+        on the view will bypass the cache middleware.
+
+    The cache middleware checks for this marker and skips both reading from
+    and writing to the cache for any matching route.
+
+    Use this decorator when a route must always produce fresh output or when
+    caching would cause incorrect behavior.
+    """
+    handler.disable_cache = True
+    return handler

bakit/sanic/listeners.py

@@ -0,0 +1,42 @@
+import logging
+
+import sentry_sdk
+from aiocache import caches
+from sentry_sdk.integrations.asyncio import AsyncioIntegration
+from sentry_sdk.integrations.logging import LoggingIntegration
+
+from bakit import settings
+
+log = logging.getLogger(__name__)
+
+
+async def setup_cache_listener(app):
+    if not app.config.CACHE_MIDDLEWARE_ENABLED:
+        log.debug("Caching disabled")
+        app.ctx.cache = None
+        return
+
+    caches.set_config(
+        {
+            "default": {
+                "cache": "aiocache.RedisCache",
+                "endpoint": settings.REDIS_HOST,
+                "port": settings.REDIS_PORT,
+                "db": settings.REDIS_DB,
+                "timeout": 3,
+                "serializer": {"class": "aiocache.serializers.PickleSerializer"},
+            }
+        }
+    )
+    app.ctx.cache = caches.get("default")
+
+
+async def setup_sentry_listener(_):
+    if not settings.SENTRY_DSN:
+        return
+
+    sentry_sdk.init(
+        dsn=settings.SENTRY_DSN,
+        send_default_pii=True,
+        integrations=[AsyncioIntegration(), LoggingIntegration(event_level="WARNING")],
+    )

bakit/sanic/middlewares.py

@@ -0,0 +1,98 @@
+import hashlib
+
+from sanic import response
+
+from bakit import settings
+
+
+def _build_cache_key(request):
+    """
+    Redis-safe cache key.
+
+    Uses SHA-256 of method + path + query so we avoid unsafe chars and
+    overlong keys while still being deterministic.
+    """
+    raw = "|".join(
+        [
+            request.method or "",
+            request.path or "",
+            request.query_string or "",
+        ]
+    )
+
+    digest = hashlib.sha256(raw.encode("utf-8")).hexdigest()
+    return f"sanic-cache:{digest}"
+
+
+def _is_no_cache(request):
+    handler = getattr(request.route, "handler", None)
+    if handler is None:
+        return False
+
+    # Function views
+    if getattr(handler, "disable_cache", False):
+        return True
+
+    # Class-based views: handler.view_class is the HTTPMethodView subclass
+    view_class = getattr(handler, "view_class", None)
+    if view_class is not None and getattr(view_class, "disable_cache", False):  # noqa: SIM103
+        return True
+    return False
+
+
+async def cache_middleware_request(request):
+    app = request.app
+    if not app.config.CACHE_MIDDLEWARE_ENABLED:
+        return
+
+    if request.method != "GET" or not getattr(request, "route", None):
+        return
+
+    # Skip if decorated with @no_cache
+    if _is_no_cache(request):
+        return
+
+    key = _build_cache_key(request)
+    cache = app.ctx.cache
+
+    cached = await cache.get(key)
+    if cached is not None:
+        # mark that this request is served from cache
+        request.ctx.response_from_cache = True
+        return response.raw(
+            cached["body"],
+            status=cached["status"],
+            headers=cached["headers"],
+            content_type=cached["content_type"],
+        )
+
+
+async def cache_middleware_response(request, response):
+    # If response came from cache, do nothing
+    if getattr(request.ctx, "response_from_cache", False):
+        return
+
+    app = request.app
+    if not app.config.CACHE_MIDDLEWARE_ENABLED:
+        return
+
+    if request.method != "GET" or not getattr(request, "route", None):
+        return
+
+    # Skip if decorated with @no_cache
+    if _is_no_cache(request):
+        return
+
+    if response.status != 200:
+        return
+
+    key = _build_cache_key(request)
+    cache = app.ctx.cache
+
+    payload = {
+        "body": response.body,  # bytes
+        "status": response.status,
+        "headers": list(response.headers.items()),
+        "content_type": response.content_type,
+    }
+    await cache.set(key, payload, ttl=settings.CACHE_MIDDLEWARE_SECONDS)

bakit/sanic/views.py

@@ -0,0 +1,348 @@
+import math
+import re
+from datetime import UTC, date, datetime, timedelta
+from decimal import Decimal
+
+from sanic import response
+from sanic.views import HTTPMethodView
+
+from bakit.utils.db import fetch_all_sql, fetch_one_sql
+from bakit.utils.metrics import view_metrics_context
+
+
+def serialize(obj):
+    """Recursively serialize objects for JSON serialization.
+    Currently handles datetime, date and Decimal objects.
+    """
+    if isinstance(obj, datetime | date):
+        return obj.isoformat()
+    elif isinstance(obj, Decimal):
+        # Avoid returning scientific notation for 0 values ("0E-18" -> "0")
+        if obj.is_zero():
+            return "0"
+        return str(obj)
+    elif isinstance(obj, dict):
+        return {key: serialize(value) for key, value in obj.items()}
+    elif isinstance(obj, list):
+        return [serialize(item) for item in obj]
+    else:
+        return obj
+
+
+class BadRequestError(Exception):
+    """Custom exception for bad request errors with status code 400."""
+
+    def __init__(self, message="Bad request", status_code=400):
+        self.message = message
+        self.status_code = status_code
+        super().__init__(self.message)
+
+
+def route(bp, path):
+    """Custom decorator to register class-based views with routes."""
+
+    if not path.startswith("/"):
+        raise ValueError(f"Route path must start with '/': {path!r}")
+
+    if path != "/" and not path.endswith("/"):
+        raise ValueError(f"Route path must end with '/': {path!r}")
+
+    def decorator(cls):
+        bp.add_route(cls.as_view(), path)
+        return cls
+
+    return decorator
+
+
+class Response:
+    """Structured response class for API endpoints."""
+
+    def __init__(self, data, status=200, message=None):
+        self.data = data
+        self.status = status
+        self.message = message
+
+    def to_dict(self):
+        # Serialize datetime objects in data only
+        serialized_data = serialize(self.data)
+
+        result = {
+            "data": serialized_data,
+            "status": self.status,
+            "success": 200 <= self.status < 300,
+        }
+
+        if self.message:
+            result["message"] = self.message
+
+        return result
+
+
+class DaysAgoMixin:
+    days_ago = None
+    days_ago_default = 30
+    days_ago_required = False
+    days_ago_options = [1, 7, 30, 90, 365, 9999]
+    days_ago_dt = None
+    days_ago_date = None
+
+    def _handle_days_ago(self, request):
+        days_ago = request.args.get("days_ago", self.days_ago_default)
+        if days_ago == "null" or days_ago is None or days_ago == "None":
+            days_ago = self.days_ago_default
+        if days_ago:
+            try:
+                self.days_ago = int(days_ago)
+                self.days_ago_dt = datetime.now(UTC) - timedelta(days=self.days_ago)
+                self.days_ago_date = datetime.now(UTC).date() - timedelta(
+                    days=self.days_ago
+                )
+            except (TypeError, ValueError):
+                raise ValueError("Wrong value for days_ago") from None
+
+            if self.days_ago_options and self.days_ago not in self.days_ago_options:
+                raise ValueError("Wrong value for days_ago") from None
+        elif self.days_ago_required:
+            raise ValueError("days_ago is a required param") from None
+
+
+class APIView(DaysAgoMixin, HTTPMethodView):
+    async def dispatch_request(self, request, *args, **kwargs):
+        self._handle_days_ago(request)
+        handler = getattr(self, request.method.lower(), None)
+
+        if not handler:
+            return response.json(
+                {"message": "Method not allowed", "status": 405, "success": False},
+                status=405,
+            )
+
+        try:
+            result = await handler(request, *args, **kwargs)
+            if isinstance(result, Response):
+                return response.json(result.to_dict(), status=result.status)
+
+            if isinstance(result, tuple):
+                data, status = result
+                if isinstance(data, dict | list):
+                    result = Response(data=data, status=status)
+                    return response.json(result.to_dict(), status=result.status)
+                return response.text(str(data), status=status)
+
+            if isinstance(result, dict | list):
+                raise TypeError(
+                    "APIView handler must return a Response object or a (data, status) "
+                    "tuple, not a raw dict or list."
+                )
+
+            return result
+        except BadRequestError as e:
+            return response.json(
+                {"message": e.message, "status": e.status_code, "success": False},
+                status=e.status_code,
+            )
+
+
+class PaginatedAPIView(APIView):
+    allowed_filters = ()
+    sortable_fields = ()
+    default_sort = ""
+    include_count = True
+
+    def get_allowed_filters(self):
+        return self.allowed_filters
+
+    def get_sortable_fields(self):
+        return self.sortable_fields
+
+    def get_base_query(self):
+        raise NotImplementedError
+
+    def get_count_query(self):
+        return None
+
+    def get_filters(self, request, values=None):
+        filters = []
+        if values is None:
+            values = {}
+
+        for filter_item in self.get_allowed_filters():
+            # Handle both simple field names and custom filter clauses
+            if (
+                "=" in filter_item
+                or ">" in filter_item
+                or "<" in filter_item
+                or "!=" in filter_item
+                or "LIKE" in filter_item.upper()
+                or "ILIKE" in filter_item.upper()
+            ):
+                # Custom filter clause with %(name)s pattern
+                filter_clause = filter_item
+                param_match = re.search(r"%\(([^)]+)\)s", filter_clause)
+                if param_match:
+                    param_name = param_match.group(1)
+                    if param_name in request.args:
+                        filters.append(filter_clause)
+                        if isinstance(request.args[param_name], list):
+                            values[param_name] = request.args[param_name][0]
+                        else:
+                            values[param_name] = request.args[param_name]
+                    if param_name in request.match_info:
+                        filters.append(filter_clause)
+                        values[param_name] = request.match_info[param_name]
+            else:
+                # Simple field name - default to equality
+                field_name = filter_item
+                # Extract the parameter name from the field
+                # (e.g., "a.network" -> "network")
+                param_name = field_name.split(".")[-1]
+                if param_name in request.args:
+                    filter_clause = f"{field_name} = %({param_name})s"
+                    filters.append(filter_clause)
+                    if isinstance(request.args[param_name], list):
+                        values[param_name] = request.args[param_name][0]
+                    else:
+                        values[param_name] = request.args[param_name]
+
+        return filters, values
+
+    def get_sorting(self, request):
+        sort_param = request.args.get("sort")
+        if not sort_param and not self.default_sort:
+            return ""
+
+        sort_param = sort_param or self.default_sort
+
+        allowed = self.get_sortable_fields()
+        sort_parts = []
+
+        for field in sort_param.split(","):
+            direction = "ASC"
+            if field.startswith("-"):
+                field = field[1:]
+                direction = "DESC"
+
+            for allowed_field in allowed:
+                if allowed_field.endswith(f".{field}") or allowed_field == field:
+                    sort_parts.append(f"{allowed_field} {direction}")
+                    break
+
+        parts = f" ORDER BY {', '.join(sort_parts)}" if sort_parts else ""
+        return f"{parts} NULLS LAST" if parts else ""
+
+    async def paginate(self, request):
+        # Validate page parameter
+        page_param = request.args.get("page", "1")
+        try:
+            page = int(page_param)
+            if page < 1:
+                raise BadRequestError("Page must be a positive integer")
+        except ValueError as e:
+            raise BadRequestError("Page must be a valid integer") from e
+
+        # Validate limit parameter
+        limit_param = request.args.get("limit", "20")
+        try:
+            limit = int(limit_param)
+            if limit < 1:
+                raise BadRequestError("Limit must be a positive integer")
+        except ValueError as e:
+            raise BadRequestError("Limit must be a valid integer") from e
+
+        if limit > 1000:
+            raise BadRequestError("Limit must be <= 1000")
+
+        offset = (page - 1) * limit
+
+        # Check if count is requested (default to True for backward compatibility)
+        include_count = self.include_count
+        if include_count is True:
+            include_count = request.args.get("count", "true").lower() == "true"
+
+        base_sql, values = self.get_base_query()
+        count_sql = self.get_count_query()
+
+        filters, filter_values = self.get_filters(request)
+
+        values.update(filter_values)
+
+        filter_clause = f" WHERE {' AND '.join(filters)}" if filters else ""
+        sort_clause = self.get_sorting(request)
+
+        final_query = (
+            f"{base_sql}{filter_clause}{sort_clause} LIMIT {limit} OFFSET {offset}"
+        )
+
+        rows = await fetch_all_sql(final_query, values)
+
+        # Initialize pagination metadata
+        pagination = {
+            "page": page,
+            "limit": limit,
+            "total": None,
+            "pages": None,
+            "next": None,
+            "previous": None,
+        }
+
+        # Only run count query if requested
+        if include_count:
+            if count_sql:
+                final_count = f"{count_sql}{filter_clause}"
+            else:
+                # Wrap the filtered base query for counting
+                final_count = (
+                    f"SELECT COUNT(*) as count FROM ({base_sql}{filter_clause}) AS sub"
+                )
+
+            total_result = await fetch_one_sql(final_count, values)
+            total = total_result["count"] if total_result else 0
+
+            pagination.update(
+                {
+                    "total": total,
+                    "pages": math.ceil(total / limit),
+                }
+            )
+
+        # Add previous/next links
+        base_url = request.url.split("?")[0]
+        query_params = dict(request.args)
+
+        # Convert list values to single values for URL generation
+        clean_params = {}
+        for k, v in query_params.items():
+            if isinstance(v, list):
+                clean_params[k] = v[0] if v else ""
+            else:
+                clean_params[k] = v
+
+        def build_url(page_num):
+            """Helper function to build pagination URLs"""
+            params = clean_params.copy()
+            params["page"] = page_num
+            return f"{base_url}?{'&'.join(f'{k}={v}' for k, v in params.items())}"
+
+        # Previous page link
+        if page > 1:
+            pagination["previous"] = build_url(page - 1)
+
+        # Next page link (only if we have count info or if we got a full page of
+        # results)
+        if include_count:
+            if page < pagination.get("pages", 0):
+                pagination["next"] = build_url(page + 1)
+        else:
+            # If no count, check if we got a full page of results to determine
+            # if there's a next page
+            if len(rows) == limit:
+                pagination["next"] = build_url(page + 1)
+
+        return {
+            "results": rows,
+            "pagination": pagination,
+        }
+
+    async def get(self, request, *args, **kwargs):
+        with view_metrics_context(self.__class__.__name__):
+            return await self.paginate(request), 200

bakit/settings.py

@@ -0,0 +1,103 @@
+import re
+import sys
+
+from environs import Env
+
+env = Env()
+
+APP_NAME = env("APP_NAME")
+
+CORS_ORIGINS = [
+    re.compile(r"^http://(localhost|127\.0\.0\.1):\d+$"),
+    re.compile(r"^https://(\S+\.)?vercel\.app$"),
+    re.compile(r"^https://(\S+\.)?blockanalitica\.com$"),
+]
+CORS_METHODS = ["GET", "POST", "PUT", "DELETE", "OPTIONS"]
+
+
+TORTOISE_ORM = {
+    "connections": {
+        "default": env("APP_DB_URL"),
+    },
+    "apps": {
+        "core": {
+            "models": [],
+            "default_connection": "default",
+        },
+    },
+}
+
+
+SENTRY_DSN = env("SENTRY_DSN", "")
+
+STATSD_HOST = env("STATSD_HOST", "")
+STATSD_PORT = env("STATSD_PORT", default=8125)
+STATSD_PREFIX = env("STATSD_PREFIX", default=APP_NAME)
+
+REDIS_HOST = env("REDIS_HOST", "")
+REDIS_PORT = env.int("REDIS_PORT", 6379)
+REDIS_DB = env.int("REDIS_DB", 2)
+
+CACHE_MIDDLEWARE_SECONDS = 5
+CACHE_MIDDLEWARE_ENABLED = env.bool("CACHE_MIDDLEWARE_ENABLED", False)
+
+APP_LOG_LEVEL = env("APP_LOG_LEVEL", default="INFO")
+TORTOISE_LOG_LEVEL = env("TORTOISE_LOG_LEVEL", default="WARNING")
+DEFAULT_LOG_LEVEL = env("DEFAULT_LOG_LEVEL", default="WARNING")
+ARQ_LOG_LEVEL = env("ARQ_LOG_LEVEL", default="INFO")
+CHAIN_HARVESTER_LOG_LEVEL = env("CHAIN_HARVESTER_LOG_LEVEL", default="WARNING")
+
+LOGGING_CONFIG = {
+    "version": 1,
+    "disable_existing_loggers": False,
+    "formatters": {
+        "default": {
+            "format": (
+                "[%(asctime)s] %(name)s {%(module)s:%(lineno)d} "
+                "PID=%(process)d [%(levelname)s] - %(message)s"
+            ),
+        },
+    },
+    "handlers": {
+        "console": {
+            "level": "DEBUG",
+            "class": "logging.StreamHandler",
+            "stream": sys.stdout,
+            "formatter": "default",
+        },
+    },
+    "loggers": {
+        "bakit": {
+            "propagate": True,
+            "level": APP_LOG_LEVEL,
+        },
+        "core": {
+            "propagate": True,
+            "level": APP_LOG_LEVEL,
+        },
+        "tortoise": {
+            "propagate": True,
+            "level": TORTOISE_LOG_LEVEL,
+        },
+        "tortoise.db_client": {
+            "propagate": True,
+            "level": TORTOISE_LOG_LEVEL,
+        },
+        "arq": {
+            "propagate": True,
+            "level": ARQ_LOG_LEVEL,
+        },
+        "arq.worker": {
+            "propagate": True,
+            "level": ARQ_LOG_LEVEL,
+        },
+        "chain_harvester": {
+            "propagate": True,
+            "level": CHAIN_HARVESTER_LOG_LEVEL,
+        },
+        "": {
+            "level": DEFAULT_LOG_LEVEL,
+            "handlers": ["console"],
+        },
+    },
+}

bakit/shell.py

@@ -0,0 +1,33 @@
+# ruff: noqa: T100
+import asyncio
+import os
+
+from IPython.terminal.embed import InteractiveShellEmbed
+from tortoise import Tortoise
+
+
+def start_ipython_shell(orm_config, extra_ns=None, banner=None):
+    """
+    Async shell helper:
+    - initializes Tortoise with orm_config
+    - starts IPython if available (with top-level await support)
+    - falls back to stdlib interactive shell otherwise
+    - always closes DB connections when done
+    """
+    asyncio.run(Tortoise.init(config=orm_config))
+
+    if banner is None:
+        banner = "Tortoise shell. If IPython is installed, top-level await should work."
+
+    ns = {
+        "Tortoise": Tortoise,
+        "os": os,
+    }
+    if extra_ns:
+        ns.update(extra_ns)
+
+    try:
+        shell = InteractiveShellEmbed(banner2=banner)
+        shell(local_ns=ns, global_ns=ns)
+    finally:
+        asyncio.run(Tortoise.close_connections())

bakit/utils/db.py

@@ -0,0 +1,51 @@
+import logging
+from contextlib import asynccontextmanager
+
+from tortoise.connection import connections
+
+log = logging.getLogger(__name__)
+
+
+def _convert_named_placeholders(sql, sql_vars):
+    sql_vars = sql_vars or []
+    if isinstance(sql_vars, dict):
+        # Convert named placeholders (%(key)s) to $1, $2, ...
+        param_count = 1
+        for key in sql_vars:
+            sql = sql.replace(f"%({key})s", f"${param_count}")
+            param_count += 1
+        sql_vars = list(sql_vars.values())
+    return sql, sql_vars
+
+
+async def fetch_one_sql(sql, sql_vars=None, db_alias="default"):
+    sql, sql_vars = _convert_named_placeholders(sql, sql_vars)
+    conn = connections.get(db_alias)
+    rows = await conn.execute_query_dict(sql, sql_vars)
+    return rows[0] if rows else {}
+
+
+async def fetch_all_sql(sql, sql_vars=None, db_alias="default"):
+    sql, sql_vars = _convert_named_placeholders(sql, sql_vars)
+    conn = connections.get(db_alias)
+    rows = await conn.execute_query_dict(sql, sql_vars)
+    return rows
+
+
+@asynccontextmanager
+async def streaming_fetch_all_sql(
+    sql, sql_vars=None, db_alias="default", prefetch=2000
+):
+    """
+    Example usage:
+        async with streaming_fetch_all_sql(sql) as cursor:
+            async for record in cursor:
+                print(record)
+    """
+    sql_vars = sql_vars or []
+    sql, sql_vars = _convert_named_placeholders(sql, sql_vars)
+    db_client = connections.get(db_alias)
+
+    async with db_client.acquire_connection() as con, con.transaction():
+        cursor = con.cursor(sql, *sql_vars, prefetch=prefetch)
+        yield cursor

bakit/utils/metrics.py

@@ -0,0 +1,263 @@
+from contextlib import contextmanager
+from functools import wraps
+
+import statsd
+
+from bakit import settings
+
+statsd_client = statsd.StatsClient(
+    settings.STATSD_HOST,
+    settings.STATSD_PORT,
+    settings.STATSD_PREFIX,
+)
+
+
+def multinetworktimerd(key):
+    """
+    Decorator function to set up a timer around a function call.
+    This is a function only decorator!
+
+    Example:
+    >>> import time
+    >>> @metrics.multinetworktimerd('eventprocessor.sync')
+    >>> def sync(self):
+    ...     time.sleep(1)
+
+    When running:
+    `EventProcessor(self.network, self.to_block).sync()
+    it will generate the following key:
+    - base.eventprocessor.sync
+    - ethereum.eventprocessor.sync
+    """
+
+    def decorator(func):
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            if not key:
+                raise Exception("Using an empty key name")
+
+            network = None
+            # Access the class instance (`self`) if the method is an instance method.
+            cls = args[0] if args else None
+            if cls:
+                network = getattr(cls, "network", None)
+
+            if not network:
+                raise AttributeError(
+                    f"The decorated method '{func.__name__}' must have a 'network' "
+                    "attribute. Ensure the class or instance has a 'network' property "
+                    "defined."
+                )
+
+            with timer(f"{network}.{key}"):
+                return func(*args, **kwargs)
+
+        return wrapper
+
+    return decorator
+
+
+def timerd(key):
+    """
+    Decorator function to set up a timer around a function call.
+    This is a function only decorator!
+
+    Example:
+    >>> import time
+    >>> @metrics.timerd('time_sleep_key')
+    >>> def timed_function():
+    ...     time.sleep(1)
+    """
+
+    def decorator(func):
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            if not key:
+                raise Exception("Using an empty key name")
+            with timer(key):
+                return func(*args, **kwargs)
+
+        return wrapper
+
+    return decorator
+
+
+@contextmanager
+def timer(key):
+    """Metrics wrapper for Statsd Timer Object
+
+    >>> import time
+    >>> with metrics.timer('unique_key'):
+    ...     time.sleep(1)
+    """
+    statsd_timer = statsd_client.timer(str(key))
+    statsd_timer.start()
+    try:
+        yield
+    finally:
+        statsd_timer.stop()
+
+
+def raw_timer(key, value):
+    """Send a timing directly to Graphite, without need to call start() and stop().
+
+    :keyword value: The time in seconds, it must be an int or a float
+
+    >>> # Got a timing from frontend!
+    >>> metrics.raw_timer('unique_key', 31.3)
+    """
+
+    # Validating "value" to be an int or a float
+    if not isinstance(value, int | float):
+        return None
+
+    return statsd_client.timing(str(key), value)
+
+
+def increment(key, delta=1, subname=None):
+    """Increment the counter identified with `key` and `subname` with `delta`
+
+    >>> # After a user logs in....
+    >>> metrics.increment('auth.successful_login', 1)
+
+        :keyword delta: The delta to add to the counter, default is 1
+        :keyword subname: The subname to report the data to (appended to the
+            client name). Like "hits", or "sales".
+    """
+    name = f"counters.{key}"
+    if subname:
+        name += f".{subname}"
+
+    return statsd_client.incr(name, delta)
+
+
+def decrement(key, delta=1, subname=None):
+    """Decrement the counter identified with `key` and `subname` with `delta`
+
+    >>> # Users that log out...
+    >>> metrics.decrement('auth.connected_users', 1)
+
+        :keyword delta: The delta to substract from the counter, default is 1
+        :keyword subname: The subname to report the data to (appended to the
+            client name)
+    """
+
+    name = f"counters.{key}"
+    if subname:
+        name += f".{subname}"
+
+    return statsd_client.decr(name, delta)
+
+
+def gauge(key, value=1, subname=None):
+    """Set the value of the gauge identified with `key` and `subname` with `value`
+
+    :keyword value: The value to set the gauge at, default is 1
+    :keyword subname: The subname to report the data to (appended to the
+        client name)
+    """
+
+    name = key
+    if subname:
+        name += f".{subname}"
+
+    # We never use the relative changes behaviour so attempt to always make it do the
+    # set value behaviour instead.
+    if value < 0:
+        statsd_client.gauge(name, 0)
+    return statsd_client.gauge(name, value)
+
+
+def function_long_name(func, extra=None):
+    if extra:
+        return ".".join([func.__module__, func.__name__, extra])
+    else:
+        return ".".join([func.__module__, func.__name__])
+
+
+def auto_named_statsd_timer(function_to_decorate):
+    call_name = function_long_name(function_to_decorate, "call")
+
+    @wraps(function_to_decorate)
+    def incr_and_call(*args, **kwargs):
+        statsd_client.incr(call_name)
+        return function_to_decorate(*args, **kwargs)
+
+    timer_name = function_long_name(function_to_decorate, "time")
+    named_decorator = statsd_client.timer(timer_name)
+
+    return named_decorator(incr_and_call)
+
+
+@contextmanager
+def view_metrics_context(endpoint_name=None, instance=None):
+    """
+    Context manager for view methods to measure hit count and response time.
+
+    Args:
+        endpoint_name: Optional custom name for the endpoint. If not provided,
+                       uses the instance's class name and current context.
+        instance: The instance (self) to get class name from.
+
+    Example:
+        async def get(self, request):
+            with view_metrics_context(instance=self):
+                # Your code here
+                return Response({"data": result})
+
+        with view_metrics_context("custom_endpoint"):
+            # Your code here
+            pass
+    """
+    if endpoint_name:
+        metric_base = f"views.{endpoint_name}"
+    else:
+        if instance:
+            cls_name = instance.__class__.__name__
+            metric_base = f"views.{cls_name}.context"
+        else:
+            metric_base = "views.unknown.context"
+
+    statsd_client.incr(f"{metric_base}.hits")
+
+    with statsd_client.timer(f"{metric_base}.response_time"):
+        yield
+
+
+def view_metrics(endpoint_name=None):
+    """
+    Decorator for view methods to measure hit count and response time.
+
+    Args:
+        endpoint_name: Optional custom name for the endpoint. If not provided,
+                       uses the class name and method name.
+
+    Example:
+        @view_metrics()
+        async def get(self, request):
+            ...
+
+        @view_metrics("custom_endpoint")
+        async def post(self, request):
+            ...
+    """
+
+    def decorator(func):
+        @wraps(func)
+        async def wrapper(*args, **kwargs):
+            if endpoint_name:
+                metric_base = f"views.{endpoint_name}"
+            else:
+                cls_name = args[0].__class__.__name__ if args else "unknown"
+                method_name = func.__name__
+                metric_base = f"views.{cls_name}.{method_name}"
+
+            statsd_client.incr(f"{metric_base}.hits")
+
+            # Time the function execution
+            with statsd_client.timer(f"{metric_base}.response_time"):
+                return await func(*args, **kwargs)
+
+        return wrapper
+
+    return decorator

bakit/utils/sql_helpers.py

@@ -0,0 +1,55 @@
+def generate_kpi_card_changes(column_name, usd_change=False, percentage_change=False):
+    """
+    Generate SQL template for calculating KPI changes and percentage changes.
+
+    Generates SQL snippets that calculate:
+    - Current value
+    - Absolute change (current - previous)
+    - Percentage change (if percentage_change is True)
+    - USD changes (if usd_change is True), also generates the same calculations for USD
+      values.
+
+    Args:
+        column_name (str): Name of the column to generate changes for
+        usd_change (bool, optional): Whether to include USD calculations. Defaults to
+                                     False.
+        percentage_change (bool, optional): Whether to include percentage change
+                                            calculations. Defaults to False.
+
+    Returns:
+        str: SQL template string with calculations for changes and percentage changes
+
+    Example:
+        >>> generate_kpi_card_changes('total_supply')
+        # Returns SQL template for total_supply and total_supply_usd changes
+    """
+
+    template = f"""
+        , c.{column_name}
+        , c.{column_name} - COALESCE(p.{column_name}, 0) AS {column_name}_change
+    """
+
+    if percentage_change:
+        template += f"""
+            , (
+                (c.{column_name} - COALESCE(p.{column_name}, 0))
+                / COALESCE(NULLIF(p.{column_name}, 0), NULLIF(c.{column_name}, 0))
+            ) AS {column_name}_change_percentage
+        """
+
+    if usd_change:
+        template += f"""
+            , c.{column_name}_usd
+            , c.{column_name}_usd - COALESCE(p.{column_name}_usd, 0)
+                AS {column_name}_usd_change
+        """
+        if percentage_change:
+            template += f"""
+                , (
+                    (c.{column_name}_usd - COALESCE(p.{column_name}_usd, 0))
+                    / COALESCE(NULLIF(p.{column_name}_usd, 0), NULLIF(
+                        c.{column_name}_usd, 0))
+                ) AS {column_name}_usd_change_percentage
+            """
+
+    return template

balabs_kit-0.0.3.dist-info/METADATA

@@ -0,0 +1,30 @@
+Metadata-Version: 2.4
+Name: balabs-kit
+Version: 0.0.3
+Author-email: tsifrer <3967564+tsifrer@users.noreply.github.com>
+License-Expression: Apache-2.0
+Requires-Python: >=3.13
+Requires-Dist: aiocache[redis]>=0.12.3
+Requires-Dist: asyncclick>=8.3.0.7
+Requires-Dist: asyncpg>=0.31.0
+Requires-Dist: environs>=14.5.0
+Requires-Dist: ipython>=9.8.0
+Requires-Dist: nest-asyncio>=1.6.0
+Requires-Dist: orjson>=3.11.5
+Requires-Dist: sentry-sdk>=2.47.0
+Requires-Dist: statsd>=4.0.1
+Requires-Dist: tortoise-orm>=0.25.1
+Requires-Dist: uvloop>=0.22.1
+Provides-Extra: arq
+Requires-Dist: arq<1.0.0,>=0.26.3; extra == 'arq'
+Requires-Dist: tortoise-plastron>=0.1.1; extra == 'arq'
+Provides-Extra: sanic
+Requires-Dist: sanic-ext>=24.12.0; extra == 'sanic'
+Requires-Dist: sanic>=25.3.0; extra == 'sanic'
+Description-Content-Type: text/markdown
+
+# BA Kit
+
+## bakit dependency installation for local development and testing
+
+`uv sync --all-extras --dev`

balabs_kit-0.0.3.dist-info/RECORD

@@ -0,0 +1,18 @@
+bakit/__init__.py,sha256=4GZKi13lDTD25YBkGakhZyEQZWTER_OWQMNPoH_UM2c,22
+bakit/settings.py,sha256=AusdP9EtOBDBuNvcK3gieKyKTD_f6lAz44-AQxvR73s,2612
+bakit/shell.py,sha256=jW7cnGbJc60sOmA_jgnCWKaE9Pm6QOvoYtTsPQVuma4,889
+bakit/sanic/__init__.py,sha256=wxdGII3_XK2gmES3h5Kt28CVgND-kWvfam-e3IK3IhU,64
+bakit/sanic/app.py,sha256=M6vF1480Ya9Xon-9YbWJCluyrIAQoQga_SrDo2814NM,1737
+bakit/sanic/decorators.py,sha256=R4qyynBiB6BGoFzoCOYxtqGyjQ-VWY83A7T62XMXNmo,630
+bakit/sanic/listeners.py,sha256=U828FErgb4IzTPswrOtHiaBSmudkIhcbBESj4LN3CA8,1111
+bakit/sanic/middlewares.py,sha256=yNuZ_8JzdzJsEEv8adA8DZwMgfARpKIGbXhNRFrcolw,2536
+bakit/sanic/views.py,sha256=0V2rqVZ6zrCkodNvu0AH4VYUn1RHiLYJMTdiX3rLKWM,11934
+bakit/sanic/static/favicon.ico,sha256=O053tj32xBSw6b3qd7LjQe0-PoJ0oxrHvPX7pbz6csE,15406
+bakit/sanic/static/favicon.png,sha256=QBRACJH47kTn6J42ta2r-tY4eQBLer2vqDGxF4ZPJi4,223
+bakit/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+bakit/utils/db.py,sha256=xknEFED-kZisn4sPZP7IlSk1-5-0LaGGtUXqqdoFfSw,1601
+bakit/utils/metrics.py,sha256=osCYEllEHe7aPxJBNvdRO-O7UaRuIMyxWfm_W0FNPgQ,7306
+bakit/utils/sql_helpers.py,sha256=JhgA7WPZQb-LFfjW_fXYRnc2yS0p-kxGzSNaX9cSULE,2046
+balabs_kit-0.0.3.dist-info/METADATA,sha256=XCjrGlkS6qTsv4chWeyxG_hfrIAqzOlnNa5P_xcVUcg,930
+balabs_kit-0.0.3.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+balabs_kit-0.0.3.dist-info/RECORD,,

balabs_kit-0.0.3.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any