shaapi 0.1.0__py3-none-any.whl

shaapi/template/backend/utils/request_parse.py

@@ -0,0 +1,110 @@
+import httpx
+import json 
+
+from asgiref.sync import sync_to_async
+from fastapi import Request
+from user_agents import parse
+from XdbSearchIP.xdbSearcher import XdbSearcher
+
+from backend.common.dataclasses import IpInfo, UserAgentInfo
+from backend.common.log import log
+from backend.core.conf import settings
+from backend.core.path_conf import IP2REGION_XDB
+from backend.database.db_redis import redis_client
+
+
+def get_request_ip(request: Request) -> str:
+    """Get the ip address of the request"""
+    real = request.headers.get('X-Real-IP')
+    if real:
+        ip = real
+    else:
+        forwarded = request.headers.get('X-Forwarded-For')
+        if forwarded:
+            ip = forwarded.split(',')[0]
+        else:
+            ip = request.client.host
+    if ip == 'testclient':
+        ip = '127.0.0.1'
+    return ip
+
+
+async def get_location_online(ip: str, user_agent: str) -> dict | None:
+    """
+    Obtain ip address attributes online, no guarantee of availability, higher accuracy
+
+    :param ip:
+    :param user_agent:
+    :return:
+    """
+    async with httpx.AsyncClient(timeout=3) as client:
+        ip_api_url = f'http://ip-api.com/json/{ip}?lang=fr-FR'
+        headers = {'User-Agent': user_agent}
+        try:
+            response = await client.get(ip_api_url, headers=headers)
+            if response.status_code == 200:
+                return response.json()
+        except Exception as e:
+            log.error(f'Failed to obtain ip address attributes online, error message:{e}')
+            return None
+
+
+@sync_to_async
+def get_location_offline(ip: str) -> dict | None:
+    """
+    Get ip address generically offline, can't guarantee accuracy, 100% available
+
+    :param ip:
+    :return:
+    """
+    try:
+        cb = XdbSearcher.loadContentFromFile(dbfile=IP2REGION_XDB)
+        searcher = XdbSearcher(contentBuff=cb)
+        data = searcher.search(ip)
+        searcher.close()
+        data = data.split('|')
+        return {
+            'country': data[0] if data[0] != '0' else None,
+            'regionName': data[2] if data[2] != '0' else None,
+            'city': data[3] if data[3] != '0' else None,
+        }
+    except Exception as e:
+        log.error(f'Failed to obtain ip address generics offline, error message:{e}')
+        return None
+
+
+async def parse_ip_info(request: Request) -> IpInfo:
+    country, region, city = None, None, None
+    ip = get_request_ip(request)
+    location = await redis_client.get(f'{settings.IP_LOCATION_REDIS_PREFIX}:{ip}')
+    if location:
+        location = json.loads(location)
+        country = location.get("country")
+        region = location.get("region")
+        city = location.get("city")
+        return IpInfo(ip=ip, country=country, region=region, city=city)
+    if settings.IP_LOCATION_PARSE == 'online':
+        location_info = await get_location_online(ip, request.headers.get('User-Agent'))
+    elif settings.IP_LOCATION_PARSE == 'offline':
+        location_info = await get_location_offline(ip)
+    else:
+        location_info = None
+    if location_info:
+        country = location_info.get('country')
+        region = location_info.get('regionName')
+        city = location_info.get('city')
+        await redis_client.set(
+            f'{settings.IP_LOCATION_REDIS_PREFIX}:{ip}',
+            json.dumps({"country": country, "region": region, "city": city}),
+            ex=settings.IP_LOCATION_EXPIRE_SECONDS,
+        )
+    return IpInfo(ip=ip, country=country, region=region, city=city)
+
+
+def parse_user_agent_info(request: Request) -> UserAgentInfo:
+    user_agent = request.headers.get('User-Agent')
+    _user_agent = parse(user_agent)
+    os = _user_agent.get_os()
+    browser = _user_agent.get_browser()
+    device = _user_agent.get_device()
+    return UserAgentInfo(user_agent=user_agent, device=device, os=os, browser=browser)

shaapi/template/backend/utils/serializers.py

@@ -0,0 +1,75 @@
+from decimal import Decimal
+from typing import Any, Sequence, TypeVar
+
+from fastapi.encoders import decimal_encoder
+from msgspec import json
+from sqlalchemy import Row, RowMapping
+from sqlalchemy.orm import ColumnProperty, SynonymProperty, class_mapper
+from starlette.responses import JSONResponse
+
+RowData = Row | RowMapping | Any
+
+R = TypeVar('R', bound=RowData)
+
+
+def select_columns_serialize(row: R) -> dict:
+    """
+    Serialize SQLAlchemy select table columns, does not contain relational columns
+
+    :param row:
+    :return:
+    """
+    result = {}
+    for column in row.__table__.columns.keys():
+        v = getattr(row, column)
+        if isinstance(v, Decimal):
+            v = decimal_encoder(v)
+        result[column] = v
+    return result
+
+
+def select_list_serialize(row: Sequence[R]) -> list:
+    """
+    Serialize SQLAlchemy select list
+
+    :param row:
+    :return:
+    """
+    result = [select_columns_serialize(_) for _ in row]
+    return result
+
+
+def select_as_dict(row: R, use_alias: bool = False) -> dict:
+    """
+    Converting SQLAlchemy select to dict, which can contain relational data,
+    depends on the properties of the select object itself
+
+    If set use_alias is True, the column name will be returned as alias,
+    If alias doesn't exist in columns, we don't recommend setting it to True
+
+    :param row:
+    :param use_alias:
+    :return:
+    """
+    if not use_alias:
+        result = row.__dict__
+        if '_sa_instance_state' in result:
+            del result['_sa_instance_state']
+            return result
+    else:
+        result = {}
+        mapper = class_mapper(row.__class__)
+        for prop in mapper.iterate_properties:
+            if isinstance(prop, (ColumnProperty, SynonymProperty)):
+                key = prop.key
+                result[key] = getattr(row, key)
+        return result
+
+
+class MsgSpecJSONResponse(JSONResponse):
+    """
+    JSON response using the high-performance msgspec library to serialize data to JSON.
+    """
+
+    def render(self, content: Any) -> bytes:
+        return json.encode(content)

shaapi/template/backend/utils/timezone.py

@@ -0,0 +1,51 @@
+import zoneinfo
+
+from datetime import datetime
+from datetime import timezone as datetime_timezone
+
+from backend.core.conf import settings
+
+
+class TimeZone:
+    def __init__(self, tz: str = settings.DATETIME_TIMEZONE):
+        self.tz_info = zoneinfo.ZoneInfo(tz)
+
+    def now(self) -> datetime:
+        """
+        Get time zone time
+
+        :return:
+        """
+        return datetime.now(self.tz_info)
+
+    def f_datetime(self, dt: datetime) -> datetime:
+        """
+        datetime Time to Time Zone Time
+
+        :param dt:
+        :return:
+        """
+        return dt.astimezone(self.tz_info)
+
+    def f_str(self, date_str: str, format_str: str = settings.DATETIME_FORMAT) -> datetime:
+        """
+        Time string to time zone time
+
+        :param date_str:
+        :param format_str:
+        :return:
+        """
+        return datetime.strptime(date_str, format_str).replace(tzinfo=self.tz_info)
+
+    @staticmethod
+    def f_utc(dt: datetime) -> datetime:
+        """
+        Time Zone Time to UTC (GMT) Time Zone
+
+        :param dt:
+        :return:
+        """
+        return dt.astimezone(datetime_timezone.utc)
+
+
+timezone = TimeZone()

shaapi/template/backend/utils/trace_id.py

@@ -0,0 +1,7 @@
+from fastapi import Request
+
+from backend.core.conf import settings
+
+
+def get_request_trace_id(request: Request) -> str:
+    return request.headers.get(settings.TRACE_ID_REQUEST_HEADER_KEY) or '-'

shaapi/template/backend/utils/translator.py

@@ -0,0 +1,28 @@
+import importlib
+from typing import Any, Dict
+
+
+class Translator:
+    _instances: Dict[str, 'Translator'] = {}
+
+    def __new__(cls, lang: str) -> 'Translator':
+        if lang not in cls._instances:
+            cls._instances[lang] = super(Translator, cls).__new__(cls)
+        return cls._instances[lang]
+
+    def __init__(self, lang: str):
+        self.lang = lang
+
+    def t(self, key: str, **kwargs: Dict[str, Any]) -> str:
+        file_key, *translation_keys = key.split('.')
+
+        locale_module = importlib.import_module(f'backend.lang.{self.lang}.{file_key}')
+
+        translation = locale_module.locale
+        for translation_key in translation_keys:
+            translation = translation.get(translation_key, None)
+            if translation is None:
+                return f'Key {key} not found in {self.lang} locale'
+        if kwargs.keys():
+            translation = translation.format(**kwargs)
+        return translation

shaapi/template/devops/scripts/deploy.sh

@@ -0,0 +1,7 @@
+ssh -o StrictHostKeyChecking=no "$VPS_USER@$VPS_IP_ADDRESS" << ENDSSH
+    cd /app
+    export $(cat .env | xargs)
+    docker login -u $CI_REGISTRY_USER -p $CI_JOB_TOKEN $CI_REGISTRY
+    docker pull $API_IMAGE
+    docker-compose -f docker-compose.yml up --build -d
+ENDSSH

shaapi/template/devops/scripts/setup_env.sh

@@ -0,0 +1,62 @@
+echo CI_JOB_TOKEN=$CI_JOB_TOKEN  >> .env
+echo CI_REGISTRY=$CI_REGISTRY  >> .env
+echo CI_REGISTRY_USER=$CI_REGISTRY_USER  >> .env
+
+echo VPS_IP_ADDRESS=$VPS_IP_ADDRESS >> .env
+echo VPS_USER=$VPS_USER >> .env
+echo API_IMAGE=$IMAGE:api  >> .env
+
+
+echo ENVIRONMENT=$ENVIRONMENT >> .env
+echo TITLE=$TITLE >> .env
+echo CLIENT_ROOT_PATH=$CLIENT_ROOT_PATH >> .env
+echo ADMIN_ROOT_PATH=$ADMIN_ROOT_PATH >> .env
+echo CLIENT_URL=$CLIENT_URL >> .env
+echo API_BASE_URL=$API_BASE_URL >> .env
+echo API_URL=$API_URL >> .env
+echo ACCESS_TOKEN_EXPIRE_MINUTES=$ACCESS_TOKEN_EXPIRE_MINUTES >> .env
+# POSTGRES
+
+echo POSTGRES_HOST=$POSTGRES_HOST >> .env
+echo POSTGRES_PORT=$POSTGRES_PORT >> .env
+echo POSTGRES_USER=$POSTGRES_USER >> .env
+echo POSTGRES_PASSWORD=$POSTGRES_PASSWORD >> .env
+# Redis
+echo REDIS_HOST=$REDIS_HOST >> .env
+echo REDIS_PORT=$REDIS_PORT >> .env
+echo REDIS_PASSWORD=$REDIS_PASSWORD >> .env
+echo REDIS_DATABASE=$REDIS_DATABASE >> .env
+# Token
+echo TOKEN_SECRET_KEY=$TOKEN_SECRET_KEY >> .env
+# Opera Log
+echo OPERA_LOG_ENCRYPT_SECRET_KEY=$OPERA_LOG_ENCRYPT_SECRET_KEY >> .env
+# Admin
+# OAuth2
+echo OAUTH2_GITHUB_CLIENT_ID=$OAUTH2_GITHUB_CLIENT_ID >> .env
+echo OAUTH2_GITHUB_CLIENT_SECRET=$OAUTH2_GITHUB_CLIENT_SECRET >> .env
+echo OAUTH2_LINUX_DO_CLIENT_ID=$OAUTH2_LINUX_DO_CLIENT_ID >> .env
+echo OAUTH2_LINUX_DO_CLIENT_SECRET=$OAUTH2_LINUX_DO_CLIENT_SECRET >> .env
+# Task
+# Celery
+echo CELERY_BROKER_REDIS_DATABASE=$CELERY_BROKER_REDIS_DATABASE >> .env
+echo CELERY_BACKEND_REDIS_DATABASE=$CELERY_BACKEND_REDIS_DATABASE >> .env
+# Rabbitmq
+echo RABBITMQ_HOST=$RABBITMQ_HOST >> .env
+echo RABBITMQ_PORT=$RABBITMQ_PORT >> .env
+echo RABBITMQ_USERNAME=$RABBITMQ_USERNAME >> .env
+echo RABBITMQ_PASSWORD=$RABBITMQ_PASSWORD >> .env
+# Minio
+echo MINIO_ENDPOINT=$MINIO_ENDPOINT >> .env
+echo MINIO_PORT=$MINIO_PORT >> .env
+echo MINIO_ACCESS_KEY=$MINIO_ACCESS_KEY >> .env
+echo MINIO_SECRET_KEY=$MINIO_SECRET_KEY >> .env
+echo MINIO_BUCKET_NAME=$MINIO_BUCKET_NAME >> .env
+echo MINIO_CLOUD_URL=$MINIO_CLOUD_URL >> .env
+
+echo SMTP_TLS=$SMTP_TLS  >> .env
+echo SMTP_PORT=$SMTP_PORT  >> .env
+echo SMTP_HOST=$SMTP_HOST  >> .env
+echo SMTP_USER=$SMTP_USER  >> .env
+echo EMAILS_FROM_EMAIL=$EMAILS_FROM_EMAIL  >> .env
+echo EMAILS_FROM_NAME=$EMAILS_FROM_NAME  >> .env
+echo SMTP_PASSWORD=$SMTP_PASSWORD  >> .env

shaapi/template/docker-compose.monitoring.yml

@@ -0,0 +1,63 @@
+# Opt-in observability stack. Enable with: ./docker-run.sh up --monitoring
+# Adds Prometheus (metrics), Tempo (traces), Loki (logs) and Grafana (UI),
+# and rebuilds the API image with the `monitoring` extra + observability on.
+services:
+  api:
+    build:
+      args:
+        EXTRAS: "--extra monitoring"
+    environment:
+      - OBSERVABILITY_ENABLED=true
+      - OTLP_GRPC_ENDPOINT=shaapi_tempo:4317
+
+  shaapi_prometheus:
+    image: prom/prometheus:v2.51.2
+    container_name: shaapi_prometheus
+    ports:
+      - "9090:9090"
+    volumes:
+      - ./etc/prometheus:/workspace
+    command:
+      - --config.file=/workspace/prometheus.yml
+      - --enable-feature=exemplar-storage
+    networks:
+      - shaapi
+
+  shaapi_tempo:
+    image: grafana/tempo:2.4.1
+    container_name: shaapi_tempo
+    command: ["--target=all", "--storage.trace.backend=local", "--storage.trace.local.path=/var/tempo", "--auth.enabled=false"]
+    ports:
+      - "4317:4317"
+      - "4318:4318"
+    networks:
+      - shaapi
+
+  shaapi_loki:
+    image: grafana/loki:3.0.0
+    container_name: shaapi_loki
+    command: -config.file=/etc/loki/local-config.yaml
+    ports:
+      - "3100:3100"
+    networks:
+      - shaapi
+
+  shaapi_grafana:
+    image: grafana/grafana:10.4.2
+    container_name: shaapi_grafana
+    ports:
+      - "3000:3000"
+    environment:
+      - GF_AUTH_ANONYMOUS_ENABLED=true
+      - GF_AUTH_ANONYMOUS_ORG_ROLE=Admin
+      - GF_AUTH_DISABLE_LOGIN_FORM=true
+    volumes:
+      - ./etc/grafana/:/etc/grafana/provisioning/datasources
+      - ./etc/dashboards.yaml:/etc/grafana/provisioning/dashboards/dashboards.yaml
+      - ./etc/dashboards:/etc/grafana/dashboards
+    depends_on:
+      - shaapi_prometheus
+      - shaapi_tempo
+      - shaapi_loki
+    networks:
+      - shaapi

shaapi/template/docker-compose.override.yml

@@ -0,0 +1,12 @@
+# Development overrides — automatically applied by `docker compose up`.
+# Bind-mounts the source so code changes hot-reload (uvicorn --reload) WITHOUT
+# rebuilding the image. The image is only rebuilt when dependencies change.
+#
+# For production, run the base file only (no mount, baked-in code):
+#   docker compose -f docker-compose.yml up -d
+# and set ENVIRONMENT=prod in your .env.
+services:
+  api:
+    volumes:
+      # Live source. The venv lives at /opt/venv, so it is not shadowed.
+      - .:/app

shaapi/template/docker-compose.yml

@@ -0,0 +1,90 @@
+services:
+  api:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    image: shaapi:latest
+    container_name: shaapi_api
+    restart: unless-stopped
+    ports:
+      - "8000:8000"
+    env_file:
+      - .env
+    environment:
+      # Point the app at the compose service names (overrides .env localhost)
+      - POSTGRES_HOST=shaapi_postgres
+      - REDIS_HOST=shaapi_redis
+      - MINIO_ENDPOINT=shaapi_minio:9000
+    depends_on:
+      postgres:
+        condition: service_healthy
+      redis:
+        condition: service_healthy
+      minio:
+        condition: service_started
+    networks:
+      - shaapi
+
+  postgres:
+    image: postgres:16-alpine
+    container_name: shaapi_postgres
+    restart: unless-stopped
+    environment:
+      - POSTGRES_USER=${POSTGRES_USER:-postgres}
+      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD:-postgres}
+      - POSTGRES_DB=${POSTGRES_DATABASE:-shaapi}
+    volumes:
+      - shaapi_postgres:/var/lib/postgresql/data
+    ports:
+      - "${POSTGRES_PORT:-5432}:5432"
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-postgres} -d ${POSTGRES_DATABASE:-shaapi}"]
+      interval: 5s
+      timeout: 5s
+      retries: 10
+    networks:
+      - shaapi
+
+  redis:
+    image: redis:7-alpine
+    container_name: shaapi_redis
+    restart: unless-stopped
+    volumes:
+      - shaapi_redis:/data
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 5s
+      timeout: 5s
+      retries: 10
+    networks:
+      - shaapi
+
+  minio:
+    image: minio/minio:latest
+    container_name: shaapi_minio
+    restart: unless-stopped
+    command: server /data --console-address ":9001"
+    environment:
+      - MINIO_ROOT_USER=${MINIO_ACCESS_KEY:-minioadmin}
+      - MINIO_ROOT_PASSWORD=${MINIO_SECRET_KEY:-minioadmin}
+    volumes:
+      - shaapi_minio:/data
+    ports:
+      - "9000:9000"
+      - "9001:9001"
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:9000/minio/health/live"]
+      interval: 30s
+      timeout: 20s
+      retries: 3
+    networks:
+      - shaapi
+
+volumes:
+  shaapi_postgres:
+  shaapi_redis:
+  shaapi_minio:
+
+networks:
+  shaapi:
+    driver: bridge

shaapi/template/docker-run.sh

@@ -0,0 +1,99 @@
+#!/bin/bash
+# Manage the shaapi Docker stack.
+#
+# Usage: ./docker-run.sh [command] [--monitoring] [--prod]
+#
+# Commands:
+#   up           Start all containers (default)
+#   down         Stop all containers
+#   build        (Re)build the API image
+#   logs         Tail logs from all services
+#   api-logs     Tail API logs only
+#   restart      Restart all containers
+#   restart-api  Restart only the API container
+#   dev          Start deps in background + API in foreground (live logs)
+#   shell        Open a shell inside the API container
+#   db           psql into Postgres
+#   redis        redis-cli into Redis
+#   migrate      Apply database migrations (alembic upgrade head)
+#   makemigrations [msg]  Generate a new migration from model changes
+#   ps           Show container status
+#
+# Options:
+#   --monitoring  Include the Prometheus/Grafana/Tempo/Loki stack
+#   --prod        Production mode: no source bind-mount, serve the baked image
+set -e
+
+cd "$(dirname "$0")"
+
+# Pick a compose command (v2 plugin preferred)
+if docker compose version >/dev/null 2>&1; then
+  DC="docker compose"
+elif command -v docker-compose >/dev/null 2>&1; then
+  DC="docker-compose"
+else
+  echo "❌ Docker Compose not found. Install Docker Desktop or the compose plugin."
+  exit 1
+fi
+
+# Create .env from template on first run
+if [ ! -f .env ]; then
+  echo "ℹ️  No .env found — creating one from .env.template"
+  cp .env.template .env
+fi
+
+# Parse positional command + flags
+MONITORING=false
+PROD=false
+POSITIONAL=()
+for arg in "$@"; do
+  case "$arg" in
+    --monitoring) MONITORING=true ;;
+    --prod)       PROD=true ;;
+    *)            POSITIONAL+=("$arg") ;;
+  esac
+done
+COMMAND="${POSITIONAL[0]:-up}"
+
+# Compose file composition
+FILES="-f docker-compose.yml"
+if [ "$PROD" = false ]; then
+  FILES="$FILES -f docker-compose.override.yml"   # dev: bind-mount + reload
+fi
+if [ "$MONITORING" = true ]; then
+  FILES="$FILES -f docker-compose.monitoring.yml"
+  echo "🔍 Monitoring enabled — Grafana: http://localhost:3000  Prometheus: http://localhost:9090"
+fi
+DC="$DC $FILES"
+
+case "$COMMAND" in
+  up)
+    echo "Starting shaapi..."
+    $DC up -d --build
+    echo "✅ API: http://localhost:8000  |  Swagger: http://localhost:8000/admin/api/v1/docs"
+    ;;
+  down)        $DC down ;;
+  build)       $DC build ;;
+  logs)        $DC logs -f ;;
+  api-logs)    $DC logs -f api ;;
+  restart)     $DC restart ;;
+  restart-api) $DC restart api ;;
+  dev)
+    $DC up -d postgres redis minio
+    $DC up --build api
+    ;;
+  shell)       $DC exec api bash ;;
+  db)          $DC exec postgres psql -U "${POSTGRES_USER:-postgres}" -d "${POSTGRES_DATABASE:-shaapi}" ;;
+  redis)       $DC exec redis redis-cli ;;
+  migrate)     $DC exec api bash -c "cd backend && alembic upgrade head" ;;
+  makemigrations)
+    MSG="${POSITIONAL[1]:-auto}"
+    $DC exec api bash -c "cd backend && alembic revision --autogenerate -m '$MSG'"
+    ;;
+  ps)          $DC ps ;;
+  *)
+    echo "Unknown command: $COMMAND"
+    echo "Run: up | down | build | logs | api-logs | restart | restart-api | dev | shell | db | redis | migrate | makemigrations | ps   [--monitoring] [--prod]"
+    exit 1
+    ;;
+esac