gengineapi 0.1.0__py3-none-any.whl

gengineapi/__init__.py

@@ -0,0 +1,43 @@
+"""
+G-Engine API Client - Асинхронный модульный клиент для взаимодействия с API G-Engine.
+
+Предоставляет удобный интерфейс для работы с платежами, финансами, 
+пользователями и другими ресурсами API G-Engine.
+"""
+
+from .client import GEngineClient
+from .config import GEngineConfig
+from .exceptions import (
+    ApiAuthError,
+    ApiConnectionError,
+    ApiError,
+    ApiForbiddenError,
+    ApiParsingError,
+    ApiResourceNotFoundError,
+    ApiServerError,
+    ApiServiceUnavailableError,
+    ApiTimeoutError,
+    ApiValidationError,
+)
+from .http import AsyncHttpClient
+
+__version__ = "1.0.0"
+__all__ = [
+    # Основной клиент
+    'GEngineClient',
+    # Конфигурация
+    'GEngineConfig',
+    # HTTP клиент
+    'AsyncHttpClient',
+    # Исключения
+    'ApiError',
+    'ApiConnectionError',
+    'ApiTimeoutError',
+    'ApiAuthError',
+    'ApiForbiddenError',
+    'ApiValidationError',
+    'ApiResourceNotFoundError',
+    'ApiServerError',
+    'ApiServiceUnavailableError',
+    'ApiParsingError',
+]

gengineapi/client.py

@@ -0,0 +1,121 @@
+"""
+Основной класс клиента API G-Engine.
+
+Предоставляет интерфейс для взаимодействия со всеми модулями API
+и управления соединением.
+"""
+import logging
+from typing import Optional
+
+from .http import AsyncHttpClient
+from .modules import (
+    AuthModule,
+    CurrenciesModule,
+    FinancesModule,
+    PaymentsModule,
+    TransactionsModule,
+    UsersModule,
+)
+
+
+class GEngineClient:
+    """
+    Клиент для API G-Engine.
+    
+    Предоставляет доступ ко всем модулям API через единый интерфейс
+    и управляет жизненным циклом HTTP-соединения.
+    """
+    
+    def __init__(
+        self,
+        base_url: str,
+        jwt_token: Optional[str] = None,
+        timeout: int = 30,
+        max_retries: int = 3,
+        logger: Optional[logging.Logger] = None,
+        proxy: Optional[str] = None,
+    ) -> None:
+        """
+        Инициализирует клиент API G-Engine.
+        
+        Args:
+            base_url: Базовый URL для API
+            jwt_token: JWT токен для аутентификации (если уже есть)
+            timeout: Таймаут для запросов в секундах (по умолчанию 30)
+            max_retries: Максимальное количество повторных попыток (по умолчанию 3)
+            logger: Логгер для записи информации (опционально)
+            proxy: Прокси для запросов в формате 'socks5://user:pass@host:port' (опционально)
+        """
+        self.logger = logger or logging.getLogger(__name__)
+        
+        if jwt_token:
+            self.logger.info("Клиент инициализирован с существующим JWT токеном")
+        
+        if proxy:
+            self.logger.info(f"Клиент будет использовать прокси: {proxy}")
+        
+        # Инициализация HTTP-клиента
+        self.http_client = AsyncHttpClient(
+            base_url=base_url,
+            jwt_token=jwt_token,
+            timeout=timeout,
+            max_retries=max_retries,
+            logger=self.logger,
+            proxy=proxy,
+        )
+        
+        # Инициализация модулей API
+        self.auth = AuthModule(http_client=self.http_client, logger=self.logger)
+        self.payments = PaymentsModule(http_client=self.http_client, logger=self.logger)
+        self.finances = FinancesModule(http_client=self.http_client, logger=self.logger)
+        self.users = UsersModule(http_client=self.http_client, logger=self.logger)
+        self.transactions = TransactionsModule(http_client=self.http_client, logger=self.logger)
+        self.currencies = CurrenciesModule(http_client=self.http_client, logger=self.logger)
+    
+    async def close(self) -> None:
+        """
+        Закрывает соединение с API.
+        
+        Должен быть вызван при завершении работы с клиентом.
+        """
+        await self.http_client.close()
+        self.logger.info("Соединение с API закрыто")
+    
+    async def __aenter__(self) -> "GEngineClient":
+        """
+        Поддержка контекстного менеджера (async with).
+        
+        Returns:
+            GEngineClient: Экземпляр клиента API
+        """
+        return self
+    
+    async def __aexit__(self, exc_type, exc_val, exc_tb) -> None:
+        """
+        Закрывает соединение при выходе из контекстного менеджера.
+        """
+        await self.close()
+    
+    def update_token(self, jwt_token: str) -> None:
+        """
+        Обновляет JWT токен для аутентификации.
+        
+        Args:
+            jwt_token: Новый JWT токен
+        """
+        self.http_client.update_token(jwt_token)
+        self.logger.info("JWT токен обновлен")
+        
+    def update_proxy(self, proxy: Optional[str] = None) -> None:
+        """
+        Обновляет настройки прокси.
+        
+        Args:
+            proxy: Новый прокси в формате 'socks5://user:pass@host:port' или None для отключения прокси
+        """
+        if hasattr(self.http_client, 'update_proxy'):
+            self.http_client.update_proxy(proxy)
+            if proxy:
+                self.logger.info(f"Прокси обновлен: {proxy}")
+            else:
+                self.logger.info("Прокси отключен")

gengineapi/config.py

@@ -0,0 +1,242 @@
+"""
+Модуль конфигурации для клиента G-Engine API.
+
+Предоставляет класс для централизованной настройки параметров клиента
+и возможность повторного использования клиента без необходимости
+каждый раз указывать параметры.
+"""
+import os
+import logging
+import json
+from pathlib import Path
+from typing import Optional, Dict, Any, ClassVar
+
+from .client import GEngineClient
+
+
+class GEngineConfig:
+    """
+    Класс-конфигурация для G-Engine клиента.
+    
+    Позволяет настроить параметры клиента один раз и затем использовать
+    их для создания экземпляров клиента без повторного указания параметров.
+    
+    Attributes:
+        base_url: Базовый URL для API
+        jwt_token: JWT токен для аутентификации
+        timeout: Таймаут для запросов в секундах
+        max_retries: Максимальное количество повторных попыток
+        logger: Логгер для записи информации
+        proxy: Прокси для запросов (например, 'socks5://user:pass@host:port')
+        
+    Class Attributes:
+        _instance: Глобальный экземпляр клиента (для повторного использования)
+    """
+    # Настройки по умолчанию
+    base_url: ClassVar[str] = "https://api.example.com/api/v2"
+    jwt_token: ClassVar[Optional[str]] = None
+    timeout: ClassVar[int] = 30
+    max_retries: ClassVar[int] = 3
+    logger: ClassVar[Optional[logging.Logger]] = None
+    proxy: ClassVar[Optional[str]] = None
+    
+    # Глобальный экземпляр клиента
+    _instance: ClassVar[Optional[GEngineClient]] = None
+    
+    @classmethod
+    def setup(cls, 
+              base_url: Optional[str] = None, 
+              jwt_token: Optional[str] = None, 
+              timeout: Optional[int] = None, 
+              max_retries: Optional[int] = None,
+              logger: Optional[logging.Logger] = None,
+              proxy: Optional[str] = None) -> None:
+        """
+        Настраивает параметры клиента по умолчанию.
+        
+        Args:
+            base_url: Базовый URL для API (опционально)
+            jwt_token: JWT токен для аутентификации (опционально)
+            timeout: Таймаут для запросов в секундах (опционально)
+            max_retries: Максимальное количество повторных попыток (опционально)
+            logger: Логгер для записи информации (опционально)
+            proxy: Прокси для запросов в формате 'socks5://user:pass@host:port' (опционально)
+        """
+        if base_url:
+            cls.base_url = base_url
+        if jwt_token:
+            cls.jwt_token = jwt_token
+        if timeout:
+            cls.timeout = timeout
+        if max_retries:
+            cls.max_retries = max_retries
+        if logger:
+            cls.logger = logger
+        if proxy is not None:  # Проверяем None, чтобы можно было передать пустую строку для отключения прокси
+            cls.proxy = proxy
+        
+        # Если есть активный глобальный клиент, закрываем его
+        if cls._instance:
+            import asyncio
+            try:
+                # Пытаемся закрыть клиент синхронно, если мы в событийном цикле
+                asyncio.get_event_loop().create_task(cls.reset())
+            except RuntimeError:
+                # Если мы не в событийном цикле, просто отмечаем инстанс как None
+                # Реальное закрытие произойдет при следующем использовании
+                cls._instance = None
+    
+    @classmethod
+    def load_from_env(cls) -> None:
+        """
+        Загружает настройки из переменных окружения.
+        
+        Ищет следующие переменные:
+            - GENGINE_BASE_URL: Базовый URL для API
+            - GENGINE_TOKEN: JWT токен для аутентификации
+            - GENGINE_TIMEOUT: Таймаут для запросов в секундах
+            - GENGINE_MAX_RETRIES: Максимальное количество повторных попыток
+            - GENGINE_PROXY: Прокси для запросов
+        """
+        base_url = os.environ.get("GENGINE_BASE_URL")
+        jwt_token = os.environ.get("GENGINE_TOKEN")
+        timeout_str = os.environ.get("GENGINE_TIMEOUT")
+        max_retries_str = os.environ.get("GENGINE_MAX_RETRIES")
+        proxy = os.environ.get("GENGINE_PROXY")
+        
+        # Преобразуем строковые значения в числа, если они есть
+        timeout = int(timeout_str) if timeout_str and timeout_str.isdigit() else None
+        max_retries = int(max_retries_str) if max_retries_str and max_retries_str.isdigit() else None
+        
+        cls.setup(
+            base_url=base_url,
+            jwt_token=jwt_token,
+            timeout=timeout,
+            max_retries=max_retries,
+            proxy=proxy,
+        )
+    
+    @classmethod
+    def load_from_file(cls, file_path: str) -> None:
+        """
+        Загружает настройки из JSON-файла.
+        
+        Args:
+            file_path: Путь к файлу настроек
+            
+        Raises:
+            FileNotFoundError: Если файл не существует
+            json.JSONDecodeError: Если файл содержит некорректный JSON
+        """
+        path = Path(file_path)
+        if not path.exists():
+            raise FileNotFoundError(f"Файл конфигурации не найден: {file_path}")
+        
+        with open(path, "r") as f:
+            config = json.load(f)
+        
+        cls.setup(
+            base_url=config.get("base_url"),
+            jwt_token=config.get("jwt_token"),
+            timeout=config.get("timeout"),
+            max_retries=config.get("max_retries"),
+            proxy=config.get("proxy"),
+        )
+    
+    @classmethod
+    def save_to_file(cls, file_path: str) -> None:
+        """
+        Сохраняет текущие настройки в JSON-файл.
+        
+        Args:
+            file_path: Путь к файлу для сохранения настроек
+        """
+        config = {
+            "base_url": cls.base_url,
+            "jwt_token": cls.jwt_token,
+            "timeout": cls.timeout,
+            "max_retries": cls.max_retries,
+            "proxy": cls.proxy,
+        }
+        
+        with open(file_path, "w") as f:
+            json.dump(config, f, indent=2)
+    
+    @classmethod
+    def get_client_kwargs(cls) -> Dict[str, Any]:
+        """
+        Возвращает словарь с параметрами для создания клиента.
+        
+        Returns:
+            Dict[str, Any]: Словарь с параметрами клиента
+        """
+        return {
+            "base_url": cls.base_url,
+            "jwt_token": cls.jwt_token,
+            "timeout": cls.timeout,
+            "max_retries": cls.max_retries,
+            "logger": cls.logger,
+            "proxy": cls.proxy,
+        }
+    
+    @classmethod
+    def create_client(cls) -> GEngineClient:
+        """
+        Создает новый экземпляр клиента с текущими настройками.
+        
+        Returns:
+            GEngineClient: Новый экземпляр клиента
+        """
+        return GEngineClient(**cls.get_client_kwargs())
+    
+    @classmethod
+    async def get_client(cls) -> GEngineClient:
+        """
+        Возвращает глобальный экземпляр клиента или создает новый,
+        если глобальный экземпляр не существует.
+        
+        Returns:
+            GEngineClient: Экземпляр клиента
+        """
+        if cls._instance is None:
+            cls._instance = cls.create_client()
+        return cls._instance
+    
+    @classmethod
+    async def reset(cls) -> None:
+        """
+        Закрывает глобальный экземпляр клиента, если он существует.
+        """
+        if cls._instance:
+            await cls._instance.close()
+            cls._instance = None
+    
+    @classmethod
+    async def update_token(cls, jwt_token: str) -> None:
+        """
+        Обновляет JWT токен в настройках и в глобальном экземпляре клиента.
+        
+        Args:
+            jwt_token: Новый JWT токен
+        """
+        cls.jwt_token = jwt_token
+        if cls._instance:
+            cls._instance.update_token(jwt_token)
+            
+    @classmethod
+    async def update_proxy(cls, proxy: Optional[str] = None) -> None:
+        """
+        Обновляет настройки прокси в конфигурации и в глобальном экземпляре клиента.
+        
+        Args:
+            proxy: Новый прокси в формате 'socks5://user:pass@host:port' или None для отключения прокси
+        """
+        cls.proxy = proxy
+        if cls._instance:
+            # Если клиент поддерживает обновление прокси
+            if hasattr(cls._instance.http_client, 'update_proxy'):
+                cls._instance.http_client.update_proxy(proxy)
+            else:
+                # Иначе пересоздаем клиент
+                await cls.reset()
+                cls._instance = cls.create_client()

gengineapi/exceptions.py

@@ -0,0 +1,125 @@
+"""
+Модуль для обработки исключений API клиента G-Engine.
+
+Содержит иерархию исключений для различных типов ошибок,
+которые могут возникнуть при взаимодействии с API.
+"""
+from typing import Any, Dict, Optional, Union
+
+
+class ApiError(Exception):
+    """Базовое исключение для всех ошибок API."""
+    
+    def __init__(
+        self,
+        message: str,
+        status_code: Optional[int] = None,
+        response_data: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """
+        Инициализация базового исключения API.
+        
+        Args:
+            message: Сообщение об ошибке
+            status_code: HTTP-код ответа
+            response_data: Данные из ответа API
+        """
+        self.message = message
+        self.status_code = status_code
+        self.response_data = response_data or {}
+        super().__init__(self.message)
+    
+    def __str__(self) -> str:
+        """Строковое представление исключения."""
+        parts = [self.message]
+        if self.status_code:
+            parts.append(f"Status code: {self.status_code}")
+        if self.response_data:
+            parts.append(f"Response data: {self.response_data}")
+        return " | ".join(parts)
+
+
+# Ошибки соединения
+class ApiConnectionError(ApiError):
+    """Исключение при ошибках соединения с API."""
+    pass
+
+
+class ApiTimeoutError(ApiConnectionError):
+    """Исключение при превышении времени ожидания ответа от API."""
+    pass
+
+
+# Ошибки авторизации
+class ApiAuthError(ApiError):
+    """Исключение при ошибках авторизации."""
+    pass
+
+
+class ApiForbiddenError(ApiAuthError):
+    """Исключение при отсутствии доступа к ресурсу."""
+    pass
+
+
+# Ошибки валидации
+class ApiValidationError(ApiError):
+    """Исключение при ошибках валидации запроса."""
+    pass
+
+
+# Ошибки ресурсов
+class ApiResourceNotFoundError(ApiError):
+    """Исключение при запросе несуществующего ресурса."""
+    pass
+
+
+# Серверные ошибки
+class ApiServerError(ApiError):
+    """Исключение при ошибках на стороне сервера."""
+    pass
+
+
+class ApiServiceUnavailableError(ApiServerError):
+    """Исключение при недоступности сервиса."""
+    pass
+
+
+# Ошибки парсинга
+class ApiParsingError(ApiError):
+    """Исключение при ошибках парсинга ответа API."""
+    pass
+
+
+def create_api_error(
+    status_code: int, 
+    message: str = None, 
+    response_data: Optional[Dict[str, Any]] = None
+) -> ApiError:
+    """
+    Фабрика для создания соответствующего исключения по коду статуса HTTP.
+    
+    Args:
+        status_code: HTTP-код ответа
+        message: Сообщение об ошибке (опционально)
+        response_data: Данные из ответа API (опционально)
+    
+    Returns:
+        ApiError: Соответствующее исключение
+    """
+    default_message = f"API вернул ошибку со статусом {status_code}"
+    message = message or default_message
+    
+    error_classes = {
+        400: ApiValidationError,
+        401: ApiAuthError,
+        403: ApiForbiddenError,
+        404: ApiResourceNotFoundError,
+        408: ApiTimeoutError,
+        500: ApiServerError,
+        502: ApiServerError,
+        503: ApiServiceUnavailableError,
+        504: ApiTimeoutError,
+    }
+    
+    error_class = error_classes.get(status_code, ApiError)
+    return error_class(message=message, status_code=status_code, response_data=response_data)