fastlib-py 0.2.4__tar.gz → 0.2.6__tar.gz

{fastlib_py-0.2.4 → fastlib_py-0.2.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastlib-py
-Version: 0.2.4
+Version: 0.2.6
 Summary: Fastlib, high performance, easy to use, fast to code, ready for production
 Author-email: tyvekZhang <tyvekzhang@gmail.com>
 Maintainer-email: tyvekZhang <tyvekzhang@gmail.com>

{fastlib_py-0.2.4 → fastlib_py-0.2.6}/fastlib/__init__.py

@@ -5,10 +5,12 @@ from .config import ConfigManager as ConfigManager
 from .constant import constant as constant
 from .logging import LogConfig as LogConfig
 from .logging import Logger as Logger
+from .openapi import register_offline_openapi as register_offline_openapi
 
 __all__ = [
     "ConfigManager",
     "Logger",
     "LogConfig",
     "constant",
+    "register_offline_openapi",
 ]

fastlib_py-0.2.6/fastlib/config/base.py

@@ -0,0 +1,8 @@
+# SPDX-License-Identifier: MIT
+"""Base configuration classes."""
+
+
+class BaseConfig:
+    """Base class for all configuration classes."""
+
+    pass

fastlib_py-0.2.6/fastlib/config/database_config.py

@@ -0,0 +1,72 @@
+# SPDX-License-Identifier: MIT
+"""Database configuration for the application."""
+
+import os
+from dataclasses import dataclass, field
+
+import fastlib.config.utils as config_util
+from fastlib.config.base import BaseConfig
+
+
+@dataclass
+class DatabaseConfig(BaseConfig):
+    """
+    Database configuration for the application.
+
+    Attributes:
+        dialect: The database dialect (e.g., mysql, postgresql, sqlite).
+        url: The database connection URL. Overrides environment variable DATABASE_URL.
+        pool_size: The number of connections to keep in the pool. Default: 10.
+        max_overflow: The maximum number of connections beyond pool_size. Default: 20.
+        pool_recycle: Connection recycle time in seconds. Default: 3600 (1 hour).
+        pool_pre_ping: Whether to test connections for liveness. Default: True.
+        echo_sql: Whether to log SQL statements. Default: False.
+        enable_redis: Whether to enable Redis cache. Default: False.
+        cache_host: Redis host address. Default: localhost.
+        cache_port: Redis port number. Default: 6379.
+        cache_pass: Redis password. Default: empty.
+        cache_db_num: Redis database number. Default: 0.
+    """
+
+    # Database configuration
+    dialect: str = field(default_factory=lambda: config_util.get_db_dialect() or "")
+    url: str = field(default_factory=lambda: DatabaseConfig._get_default_db_url())
+    pool_size: int = 10
+    max_overflow: int = 20
+    pool_recycle: int = 3600
+    pool_pre_ping: bool = True
+    echo_sql: bool = False
+
+    # Redis/cache configuration
+    enable_redis: bool = False
+    cache_host: str = "localhost"
+    cache_port: int = 6379
+    cache_pass: str = field(default_factory=lambda: os.getenv("REDIS_PASSWORD", ""))
+    cache_db_num: int = 0
+
+    def __post_init__(self) -> None:
+        """Post-initialization processing."""
+        # Handle dialect default
+        if not self.dialect.strip():
+            self.dialect = config_util.get_db_dialect()
+
+        # Handle URL priority: environment variable > parameter > default
+        env_db_url = os.getenv("DB_URL")
+        if env_db_url:
+            self.url = env_db_url
+        elif not self.url.strip():
+            self.url = self._get_default_db_url()
+
+        # Handle Redis password from environment
+        env_redis_pass = os.getenv("REDIS_PASSWORD")
+        if env_redis_pass is not None:
+            self.cache_pass = env_redis_pass
+
+    @staticmethod
+    def _get_default_db_url() -> str:
+        """Get default database URL based on dialect."""
+        dialect = config_util.get_db_dialect()
+        if dialect == "sqlite" or dialect is None:
+            return config_util.get_sqlite_db_path()
+        else:
+            return config_util.get_db_url()

fastlib_py-0.2.6/fastlib/config/security_config.py

@@ -0,0 +1,95 @@
+# SPDX-License-Identifier: MIT
+"""Security configuration for the application."""
+
+import os
+from dataclasses import dataclass, field
+from typing import ClassVar
+
+from fastlib.config.base import BaseConfig
+
+
+@dataclass
+class SecurityConfig(BaseConfig):
+    """
+    Security configuration for the application.
+
+    Attributes:
+        enable: Whether to enable security features. Default: True.
+        algorithm: The encryption algorithm used for token generation. Default: HS256.
+        secret_key: The secret key used for signing the tokens. Default: placeholder.
+        access_token_expire_minutes: Minutes until access token expires. Default: 30.
+        refresh_token_expire_minutes: Minutes until refresh token expires. Default: 10080 (7 days).
+        enable_swagger: Whether to enable swagger UI. Default: False.
+        white_list_routes: Comma-separated routes accessible without authentication.
+                         Default: API docs and health endpoints.
+        backend_cors_origins: Comma-separated list of allowed CORS origins.
+                             Default: Local development addresses.
+        black_ip_list: Comma-separated list of blocked IP addresses. Default: empty.
+    """
+
+    enable: bool = True
+    algorithm: str = "HS256"
+    secret_key: str = field(
+        default_factory=lambda: os.getenv(
+            "SECRET_KEY", "your-secret-key-change-in-production"
+        )
+    )
+    access_token_expire_minutes: int = 30
+    refresh_token_expire_minutes: int = 60 * 24 * 7  # 7 days
+    enable_swagger: bool = False
+    white_list_routes: str = "/api/v1/probe/liveness, /api/v1/user/register, /api/v1/auth:signInWithEmailAndPassword"
+    backend_cors_origins: str = (
+        "http://127.0.0.1:8000, http://localhost:8000, http://localhost"
+    )
+    black_ip_list: str = ""
+
+    # Class-level constants for better organization
+    _DEFAULT_WHITE_LIST_ROUTES: ClassVar[str] = (
+        "/api/v1/probe/liveness, /api/v1/user/register, /api/v1/auth:signInWithEmailAndPassword"
+    )
+    _DEFAULT_CORS_ORIGINS: ClassVar[str] = (
+        "http://127.0.0.1:8000, http://localhost:8000, http://localhost"
+    )
+
+    def __post_init__(self) -> None:
+        """Post-initialization processing."""
+        # Ensure secret_key uses environment variable if available
+        env_secret_key = os.getenv("SECRET_KEY")
+        if env_secret_key is not None:
+            self.secret_key = env_secret_key
+
+    @property
+    def white_list_routes_list(self) -> list[str]:
+        """Returns white list routes as a list."""
+        return [
+            route.strip()
+            for route in self.white_list_routes.split(",")
+            if route.strip()
+        ]
+
+    @property
+    def backend_cors_origins_list(self) -> list[str]:
+        """Returns CORS origins as a list."""
+        return [
+            origin.strip()
+            for origin in self.backend_cors_origins.split(",")
+            if origin.strip()
+        ]
+
+    @property
+    def black_ip_list_list(self) -> list[str]:
+        """Returns blacklisted IPs as a list."""
+        return [ip.strip() for ip in self.black_ip_list.split(",") if ip.strip()]
+
+    def __str__(self) -> str:
+        """
+        Returns a string representation of the security configuration.
+
+        Returns:
+            A string representation of the SecurityConfig instance.
+        """
+        # Hide secret key in string representation for security
+        safe_dict = self.__dict__.copy()
+        if "secret_key" in safe_dict:
+            safe_dict["secret_key"] = "***" if safe_dict["secret_key"] else ""
+        return f"{self.__class__.__name__}({safe_dict})"

fastlib_py-0.2.6/fastlib/config/server_config.py

@@ -0,0 +1,48 @@
+# SPDX-License-Identifier: MIT
+"""Server configuration for the application."""
+
+from dataclasses import dataclass, field
+from typing import ClassVar
+
+from fastlib.config.base import BaseConfig
+from fastlib.config.utils import ProjectInfo
+
+
+@dataclass
+class ServerConfig(BaseConfig):
+    """
+    Server configuration for the application.
+
+    Attributes:
+        host: The server host address.
+        port: The server port number.
+        name: The server name.
+        version: The server version.
+        app_desc: The server description.
+        api_prefix: The API prefix for routes.
+        debug: Whether to enable debug mode.
+        workers: The number of worker processes.
+        enable_rate_limit: Whether to enable rate limiting.
+        global_default_limits: Global rate limit setting.
+    """
+
+    _project_config: ClassVar[ProjectInfo] = ProjectInfo.from_pyproject()
+
+    host: str = "127.0.0.1"
+    port: int = 18888
+    name: str = field(default_factory=lambda: ServerConfig._get_default_name())
+    version: str = field(default_factory=lambda: ServerConfig._project_config.version)
+    app_desc: str = field(
+        default_factory=lambda: ServerConfig._project_config.description
+    )
+    api_prefix: str = "/api"
+    debug: bool = False
+    workers: int = 1
+    enable_rate_limit: bool = False
+    global_default_limits: str = "10/second"
+
+    @classmethod
+    def _get_default_name(cls) -> str:
+        """Get the default server name from project config."""
+        name = cls._project_config.name
+        return name[0].upper() + name[1:] if name else "Server"

{fastlib_py-0.2.4 → fastlib_py-0.2.6}/fastlib/config/utils.py

@@ -8,7 +8,7 @@ from urllib.parse import urlparse
 
 from loguru import logger
 
-from fastlib.enums.base import DBTypeEnum
+from fastlib.enums import DBTypeEnum
 from fastlib.utils import file_util
 
 try:

fastlib_py-0.2.6/fastlib/contextvars.py

@@ -0,0 +1,58 @@
+# SPDX-License-Identifier: MIT
+"""Context variable for storing current user authentication context.
+
+This module provides a thread-local and async-safe way to store and access
+the current authenticated user's ID throughout the request lifecycle.
+"""
+
+from contextvars import ContextVar
+from typing import Any, Optional
+
+from loguru import logger
+
+# Type aliases for better readability
+UserID = Optional[int]
+
+# Context variable declaration
+_current_user_id: ContextVar[UserID] = ContextVar("current_user_id", default=None)
+
+
+def set_current_user(user_id: int) -> Any:
+    """Set the current user ID in context.
+
+    Args:
+        user_id: The authenticated user's ID (must be positive integer)
+
+    Returns:
+        Token that can be used to reset the context
+
+    Raises:
+        ValueError: If user_id is not a positive integer
+    """
+    if not isinstance(user_id, int) or user_id <= 0:
+        raise ValueError("user_id must be a positive integer")
+
+    logger.debug("Setting current user context: user_id=%s", user_id)
+    return _current_user_id.set(user_id)
+
+
+def get_current_user() -> UserID:
+    """Get the current user ID from context.
+
+    Returns:
+        The current user ID or None if not set
+    """
+    user_id = _current_user_id.get()
+    if user_id is None:
+        logger.warning("Attempted to get current user ID but context is not set")
+    return user_id
+
+
+def clear_current_user(token: Any) -> None:
+    """Reset the current user context.
+
+    Args:
+        token: The token returned by set_current_user
+    """
+    _current_user_id.reset(token)
+    logger.debug("Cleared current user context")

fastlib_py-0.2.6/fastlib/exception/__init__.py

@@ -0,0 +1,6 @@
+"""Exception handling."""
+
+from .base import BaseException, ErrorDetail
+from .exception_manager import register_exception_handlers
+
+__all__ = [BaseException, ErrorDetail, register_exception_handlers]

{fastlib_py-0.2.4 → fastlib_py-0.2.6}/fastlib/exception/base.py

@@ -1,20 +1,20 @@
 # SPDX-License-Identifier: MIT
 """Base exception class for the application."""
 
+from http import HTTPStatus
 from typing import Any, Optional
 
 from pydantic import BaseModel
 
 
 class ErrorDetail(BaseModel):
-    """Base class for error code.
-    """
+    """Error detail."""
 
     code: int
     message: str
 
 
-class HTTPException(Exception):
+class BaseException(Exception):
     """
     Base exception class for all custom exception in the application.
 
@@ -46,3 +46,17 @@ class HTTPException(Exception):
     def __post_init__(self):
         if self.message is None:
             self.message = self.code.message
+
+
+class SystemErrorCode:
+    """System-related error codes."""
+
+    INTERNAL_ERROR = ErrorDetail(
+        code=HTTPStatus.INTERNAL_SERVER_ERROR.value, message="Internal server error"
+    )
+
+
+class SystemException(BaseException):
+    code: SystemErrorCode
+    message: Optional[str] = None
+    details: Optional[Any] = None

{fastlib_py-0.2.4 → fastlib_py-0.2.6}/fastlib/exception/exception_handler.py

@@ -16,7 +16,7 @@ from pydantic_core._pydantic_core import ValidationError  # noqa
 from starlette.exceptions import HTTPException as StarletteHTTPException
 
 from fastlib import ConfigManager
-from fastlib.exception import HTTPException
+from fastlib.exception import BaseException
 
 
 async def extract_request_data(request: Request) -> dict[str, Any]:
@@ -163,7 +163,7 @@ def is_auth_errors_code(error_code: int):
     return False
 
 
-async def custom_exception_handler(request: Request, exc: HTTPException):
+async def custom_exception_handler(request: Request, exc: BaseException):
     """
     Handler for custom HTTPException.
     """
@@ -240,7 +240,6 @@ async def custom_http_exception_handler(request: Request, exc: StarletteHTTPExce
     return await http_exception_handler(request, exc)
 
 
-# 修改为：
 async def jwt_exception_handler(request: Request):
     """
     Handler for JWT-related exceptions.

{fastlib_py-0.2.4 → fastlib_py-0.2.6}/fastlib/exception/exception_manager.py

@@ -8,7 +8,7 @@ from pydantic_core._pydantic_core import ValidationError  # noqa
 from starlette.exceptions import HTTPException as StarletteHTTPException
 
 from fastlib.exception import exception_handler
-from fastlib.exception.base import HTTPException
+from fastlib.exception.base import BaseException
 
 
 def register_exception_handlers(app: FastAPI) -> None:
@@ -20,7 +20,7 @@ def register_exception_handlers(app: FastAPI) -> None:
         ValidationError, exception_handler.validation_exception_handler
     )
 
-    app.add_exception_handler(HTTPException, exception_handler.custom_exception_handler)
+    app.add_exception_handler(BaseException, exception_handler.custom_exception_handler)
 
     app.add_exception_handler(
         StarletteHTTPException, exception_handler.custom_http_exception_handler

fastlib_py-0.2.6/fastlib/i18n/__init__.py

@@ -0,0 +1 @@
+# SPDX-License-Identifier: MIT

{fastlib_py-0.2.4 → fastlib_py-0.2.6}/fastlib/i18n/manager.py

@@ -56,11 +56,6 @@ class I18nContext:
             _language_context.reset(self._token)
 
 
-def with_language(language: Language) -> I18nContext:
-    """Helper to create context manager"""
-    return I18nContext(language)
-
-
 def _language_context_decorator(
     language: Language, is_async: bool = False
 ) -> Callable[[F], F]:
@@ -97,3 +92,8 @@ def async_language_context(
 ) -> Callable[[Callable[..., Awaitable[Any]]], Callable[..., Awaitable[Any]]]:
     """Decorator: run an async function within a language context"""
     return _language_context_decorator(language, is_async=True)
+
+
+def i18n_context(language: Language) -> I18nContext:
+    """Helper to create context manager"""
+    return I18nContext(language)

{fastlib_py-0.2.4 → fastlib_py-0.2.6}/fastlib/logging/__init__.py

@@ -1,4 +1,7 @@
-"""Logging module"""
+# SPDX-License-Identifier: MIT
+"""
+Logging module
+"""
 
 from .config import LogConfig
 from .handlers import Logger

fastlib_py-0.2.6/fastlib/logging/config.py

@@ -0,0 +1,102 @@
+# SPDX-License-Identifier: MIT
+"""
+Log configuration and logging utility for the application.
+"""
+
+from pathlib import Path
+from typing import Literal, Optional
+
+from fastlib.config.base import BaseConfig
+from fastlib.config.manager import config_class
+from fastlib.config.utils import ProjectInfo
+
+LogLevel = Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]
+
+
+@config_class("log")
+class LogConfig(BaseConfig):
+    """Configuration for logging settings."""
+
+    def __init__(
+        self,
+        log_dir: str = "/var/log",
+        app_name: str = None,
+        log_level: LogLevel = "INFO",
+        log_rotation: str = "1 day",
+        log_retention: str = "90 days",
+        enable_console_log: bool = True,
+        enable_json_logs: bool = False,
+        error_log_rotation: str = "1 day",
+        error_log_retention: str = "90 days",
+        enable_async: bool = True,
+        max_file_size: Optional[str] = "10 MB",
+        time_format: str = "YYYY-MM-DD",
+        **kwargs,
+    ):
+        """
+        Initialize LogConfig with logging settings.
+
+        Args:
+            log_dir: Directory where log files will be stored
+            app_name: Name of the application for log file naming
+            log_level: Minimum log level to record
+            log_rotation: How often to rotate log files
+            log_retention: How long to keep log files
+            enable_console_log: Whether to output logs to console
+            enable_json_logs: Whether to use JSON format for logs
+            error_log_rotation: How often to rotate error log files
+            error_log_retention: How long to keep error log files
+            enable_async: Whether to use asynchronous logging
+            max_file_size: Maximum size for log files before rotation
+            time_format: Format string for timestamps in log file names
+            **kwargs: Additional keyword arguments for base class
+        """
+        # Set app_name default if not provided
+        if app_name is None:
+            app_name = ProjectInfo.from_pyproject().name
+
+        # Initialize instance attributes directly
+        self.log_dir = log_dir
+        self.app_name = app_name
+        self.log_level = log_level
+        self.log_rotation = log_rotation
+        self.log_retention = log_retention
+        self.enable_console_log = enable_console_log
+        self.enable_json_logs = enable_json_logs
+        self.error_log_rotation = error_log_rotation
+        self.error_log_retention = error_log_retention
+        self.enable_async = enable_async
+        self.max_file_size = max_file_size
+        self.time_format = time_format
+
+        # Handle any additional kwargs for base class
+        if kwargs:
+            # If base class needs special handling, you can add it here
+            # For now, we'll set them as instance attributes
+            for key, value in kwargs.items():
+                setattr(self, key, value)
+
+    @property
+    def default_format(self) -> str:
+        """Default log format string."""
+        return "{time:YYYY-MM-DD HH:mm:ss.SSS} | {level: <8} | {name}:{function}:{line} | {message}"
+
+    @property
+    def log_file_pattern(self) -> str:
+        """Returns the main log file pattern with timestamp."""
+        return f"{{time:{self.time_format}}}_{self.app_name}.log"
+
+    @property
+    def error_log_file_pattern(self) -> str:
+        """Returns the error log file pattern with timestamp."""
+        return f"{{time:{self.time_format}}}_error_{self.app_name}.log"
+
+    @property
+    def log_file_path(self) -> Path:
+        """Returns the full path for the main log file."""
+        return Path(self.log_dir) / self.log_file_pattern
+
+    @property
+    def error_log_file_path(self) -> Path:
+        """Returns the full path for the error log file."""
+        return Path(self.log_dir) / self.error_log_file_pattern