dwyeapi 0.4.0__tar.gz

dwyeapi-0.4.0/PKG-INFO

@@ -0,0 +1,23 @@
+Metadata-Version: 2.4
+Name: dwyeapi
+Version: 0.4.0
+Summary: Lightweight FastAPI infrastructure — exceptions, database, config, security, cache, pagination, logger
+License: MIT
+Requires-Python: >=3.11
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: sqlalchemy[asyncio]>=2.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pydantic-settings>=2.0.0
+Requires-Dist: python-jose[cryptography]>=3.3.0
+Requires-Dist: bcrypt>=4.0.0
+Requires-Dist: redis>=5.0.0
+Requires-Dist: loguru>=0.7.3
+Provides-Extra: tasks
+Requires-Dist: arq>=0.26.0; extra == "tasks"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.24.0; extra == "dev"
+Requires-Dist: httpx>=0.27.0; extra == "dev"
+Requires-Dist: aiosqlite>=0.20.0; extra == "dev"
+Requires-Dist: ruff>=0.6.0; extra == "dev"
+Requires-Dist: arq>=0.26.0; extra == "dev"

dwyeapi-0.4.0/README.md

@@ -0,0 +1,21 @@
+# dwyeapi
+
+Lightweight FastAPI infrastructure package for shared use across projects.
+
+## Install
+
+```bash
+pip install dwyeapi
+```
+
+## Modules
+
+- `config` — BaseSettings with required fields (database_url, redis_url, secret_key)
+- `exceptions` — AppError hierarchy + FastAPI exception handlers
+- `database` — Async SQLAlchemy engine/session factory + Base + TimestampMixin
+- `dependencies` — `get_db()` FastAPI dependency
+- `security` — JWT create/verify + bcrypt hash/verify (stateless)
+- `cache` — Async Redis connection manager
+- `response` — Unified API response helpers
+- `pagination` — PaginationParams + paginate helper
+- `logger` — Loguru-based logger with daily + size rotation and stdlib interception

dwyeapi-0.4.0/pyproject.toml

@@ -0,0 +1,53 @@
+[project]
+name = "dwyeapi"
+version = "0.4.0"
+description = "Lightweight FastAPI infrastructure — exceptions, database, config, security, cache, pagination, logger"
+requires-python = ">=3.11"
+license = {text = "MIT"}
+dependencies = [
+    "fastapi>=0.100.0",
+    "sqlalchemy[asyncio]>=2.0.0",
+    "pydantic>=2.0.0",
+    "pydantic-settings>=2.0.0",
+    "python-jose[cryptography]>=3.3.0",
+    "bcrypt>=4.0.0",
+    "redis>=5.0.0",
+    "loguru>=0.7.3",
+]
+
+[project.optional-dependencies]
+tasks = [
+    "arq>=0.26.0",
+]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.24.0",
+    "httpx>=0.27.0",
+    "aiosqlite>=0.20.0",
+    "ruff>=0.6.0",
+    "arq>=0.26.0",
+]
+
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 120
+
+[tool.ruff.lint]
+select = ["E", "W", "F", "I", "N", "UP", "B", "SIM", "RUF"]
+
+[tool.ruff.lint.per-file-ignores]
+"src/dwyeapi/tasks/router.py" = ["B008"]
+"src/dwyeapi/tasks/worker.py" = ["RUF012"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["dwyeapi"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

dwyeapi-0.4.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

dwyeapi-0.4.0/src/dwyeapi/__init__.py

@@ -0,0 +1,20 @@
+"""dwyeapi — Lightweight FastAPI infrastructure.
+
+Modules:
+    config        — BaseSettings with required fields
+    exceptions    — AppError hierarchy + FastAPI exception handlers
+    database      — Async SQLAlchemy engine/session factory + Base + TimestampMixin
+    dependencies  — get_db() FastAPI dependency factory
+    security      — JWT + bcrypt helpers (stateless)
+    cache         — Async Redis connection manager
+    response      — Unified API response helpers
+    pagination    — PaginationParams + paginate helper
+    logger        — Loguru-based logger with daily+size rotation and stdlib interception
+    tasks         — Async task processing system (ARQ-based, install with [tasks] extra)
+    masking       — PII data masking utilities
+"""
+
+from . import logger
+
+__all__ = ["logger"]
+__version__ = "0.4.0"

dwyeapi-0.4.0/src/dwyeapi/cache.py

@@ -0,0 +1,30 @@
+"""Async Redis connection manager."""
+
+import redis.asyncio as aioredis
+
+_redis_url: str | None = None
+_redis: aioredis.Redis | None = None
+
+
+def configure(redis_url: str) -> None:
+    """Set the Redis connection URL."""
+    global _redis_url
+    _redis_url = redis_url
+
+
+async def get_redis() -> aioredis.Redis:
+    """Get or create the shared async Redis connection."""
+    if _redis_url is None:
+        raise RuntimeError("dwyeapi.cache not configured — call cache.configure(redis_url) first")
+    global _redis
+    if _redis is None:
+        _redis = aioredis.from_url(_redis_url, decode_responses=True)
+    return _redis
+
+
+async def close_redis() -> None:
+    """Close the Redis connection. Safe to call even if not connected."""
+    global _redis
+    if _redis is not None:
+        await _redis.close()
+        _redis = None

dwyeapi-0.4.0/src/dwyeapi/config.py

@@ -0,0 +1,39 @@
+"""Base Pydantic Settings class for FastAPI projects."""
+
+from pydantic import Field
+from pydantic_settings import BaseSettings as PydanticBaseSettings
+from pydantic_settings import SettingsConfigDict
+
+
+class BaseSettings(PydanticBaseSettings):
+    """Base settings — subclass and add project-specific fields."""
+
+    database_url: str
+    redis_url: str
+    secret_key: str
+    jwt_algorithm: str = "HS256"
+    access_token_expire_minutes: int = 30
+    debug: bool = False
+    allowed_origins: list[str] = Field(default_factory=list)
+
+    # Task module settings (task_ prefix)
+    task_max_jobs: int = 5
+    task_job_timeout: int = 3600
+    task_failure_ttl: int = 86400
+
+    # Logger module settings (log_ prefix)
+    log_level: str = "INFO"
+    log_dir: str | None = None
+    log_filename: str = "app"
+    log_max_bytes: int = 100 * 1024 * 1024
+    log_retention: str = "30 days"
+    log_console: bool = True
+    log_serialize: bool = False
+    log_intercept_stdlib: bool = True
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        env_nested_delimiter="__",
+        extra="ignore",
+    )

dwyeapi-0.4.0/src/dwyeapi/database.py

@@ -0,0 +1,42 @@
+"""Async SQLAlchemy engine and session factory, declarative Base, and TimestampMixin."""
+
+from datetime import datetime
+
+from sqlalchemy import func
+from sqlalchemy.ext.asyncio import AsyncEngine, AsyncSession, async_sessionmaker, create_async_engine
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+
+
+class Base(DeclarativeBase):
+    """Declarative base class for all ORM models."""
+
+    pass
+
+
+class TimestampMixin:
+    """Mixin that adds created_at and updated_at columns."""
+
+    created_at: Mapped[datetime] = mapped_column(server_default=func.now())
+    updated_at: Mapped[datetime] = mapped_column(server_default=func.now(), onupdate=func.now())
+
+
+def create_async_engine_factory(
+    database_url: str,
+    pool_size: int = 5,
+    max_overflow: int = 10,
+    echo: bool = False,
+) -> AsyncEngine:
+    """Create an async SQLAlchemy engine."""
+    if database_url.startswith("sqlite"):
+        return create_async_engine(database_url, echo=echo)
+    return create_async_engine(
+        database_url,
+        pool_size=pool_size,
+        max_overflow=max_overflow,
+        echo=echo,
+    )
+
+
+def create_session_factory(engine: AsyncEngine) -> async_sessionmaker[AsyncSession]:
+    """Create an async session factory bound to the given engine."""
+    return async_sessionmaker(engine, expire_on_commit=False)

dwyeapi-0.4.0/src/dwyeapi/dependencies.py

@@ -0,0 +1,16 @@
+"""FastAPI dependency factories."""
+
+from collections.abc import AsyncGenerator
+
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
+
+
+def create_get_db(session_factory: async_sessionmaker[AsyncSession]):
+    """Create a get_db FastAPI dependency bound to a session factory."""
+
+    async def get_db() -> AsyncGenerator[AsyncSession]:
+        """Yield a database session, automatically closed after the request."""
+        async with session_factory() as session:
+            yield session
+
+    return get_db

dwyeapi-0.4.0/src/dwyeapi/dt.py

@@ -0,0 +1,52 @@
+"""全局时间工具 — 所有日期操作的唯一入口。
+
+业务时间统一 Asia/Shanghai，JWT 等协议场景提供 UTC 方法。
+禁止在业务代码中直接使用 datetime.now()，统一通过本模块访问。
+
+Usage::
+
+    from dwyeapi import dt
+
+    dt.now()          # naive datetime, 中国时间, 用于数据库
+    dt.now_str()      # "2026-04-06 14:30:00"
+    dt.today()        # date(2026, 4, 6)
+    dt.timestamp()    # Unix 时间戳（秒）
+    dt.utc_now()      # aware datetime, UTC, 用于 JWT
+"""
+
+from datetime import date, datetime, timedelta
+from zoneinfo import ZoneInfo
+
+TZ = ZoneInfo("Asia/Shanghai")
+UTC = ZoneInfo("UTC")
+
+
+# ── 业务时间（Asia/Shanghai） ──────────────────────────────────────────
+
+
+def now() -> datetime:
+    """当前中国时间（naive，用于数据库存储）。"""
+    return datetime.now(TZ).replace(tzinfo=None)
+
+
+def now_str(fmt: str = "%Y-%m-%d %H:%M:%S") -> str:
+    """格式化的当前中国时间字符串。"""
+    return datetime.now(TZ).strftime(fmt)
+
+
+def today() -> date:
+    """当前中国日期。"""
+    return datetime.now(TZ).date()
+
+
+def timestamp() -> float:
+    """当前 Unix 时间戳（秒）。"""
+    return datetime.now(TZ).timestamp()
+
+
+# ── UTC（JWT 等协议场景） ──────────────────────────────────────────────
+
+
+def utc_now() -> datetime:
+    """当前 UTC 时间（aware，用于 JWT exp 等协议字段）。"""
+    return datetime.now(UTC)

dwyeapi-0.4.0/src/dwyeapi/exceptions.py

@@ -0,0 +1,75 @@
+"""AppError exception hierarchy and FastAPI exception handler registration."""
+
+from fastapi import FastAPI, Request, status
+from fastapi.responses import JSONResponse
+
+
+class AppError(Exception):
+    """Base class for all application-level errors."""
+
+    def __init__(self, message: str, code: str = "UNKNOWN_ERROR") -> None:
+        self.message = message
+        self.code = code
+
+
+class NotFoundError(AppError):
+    """Resource not found."""
+
+    def __init__(self, resource: str) -> None:
+        super().__init__(message=f"{resource}不存在", code="NOT_FOUND")
+
+
+class BusinessError(AppError):
+    """Business rule validation failure."""
+
+    pass
+
+
+class PermissionDeniedError(AppError):
+    """Insufficient permissions."""
+
+    def __init__(self) -> None:
+        super().__init__(message="权限不足", code="PERMISSION_DENIED")
+
+
+class AuthenticationError(AppError):
+    """Authentication failed or missing."""
+
+    def __init__(self) -> None:
+        super().__init__(message="认证失败", code="AUTHENTICATION_FAILED")
+
+
+def register_exception_handlers(app: FastAPI) -> None:
+    """Register exception-to-HTTP-response handlers on a FastAPI app."""
+
+    @app.exception_handler(NotFoundError)
+    async def not_found_handler(request: Request, exc: NotFoundError) -> JSONResponse:
+        """Handle NotFoundError → 404."""
+        return JSONResponse(
+            status_code=status.HTTP_404_NOT_FOUND,
+            content={"code": exc.code, "message": exc.message},
+        )
+
+    @app.exception_handler(BusinessError)
+    async def business_error_handler(request: Request, exc: BusinessError) -> JSONResponse:
+        """Handle BusinessError → 422."""
+        return JSONResponse(
+            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            content={"code": exc.code, "message": exc.message},
+        )
+
+    @app.exception_handler(PermissionDeniedError)
+    async def permission_denied_handler(request: Request, exc: PermissionDeniedError) -> JSONResponse:
+        """Handle PermissionDeniedError → 403."""
+        return JSONResponse(
+            status_code=status.HTTP_403_FORBIDDEN,
+            content={"code": exc.code, "message": exc.message},
+        )
+
+    @app.exception_handler(AuthenticationError)
+    async def auth_error_handler(request: Request, exc: AuthenticationError) -> JSONResponse:
+        """Handle AuthenticationError → 401."""
+        return JSONResponse(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            content={"code": exc.code, "message": exc.message},
+        )

dwyeapi-0.4.0/src/dwyeapi/logger.py

@@ -0,0 +1,205 @@
+"""Loguru-based global logger with daily + size rotation and stdlib interception.
+
+Exposes a single lifecycle API (``configure``/``get_logger``/``close``) that mirrors
+the pattern used by ``cache.py``. A typical application calls ``configure`` once at
+startup (from ``lifespan``) and ``close`` once at shutdown.
+
+Features:
+    * Colored console output (stderr).
+    * File output with daily rollover (``{filename}_YYYY-MM-DD.log``) and a
+      configurable per-file size ceiling — whichever triggers first.
+    * Old log retention (default 30 days) with automatic cleanup.
+    * Optional JSON serialization for log aggregators.
+    * Optional interception of the standard ``logging`` module so libraries like
+      uvicorn, SQLAlchemy and third-party packages route through the same sinks.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import inspect
+import logging
+import sys
+from datetime import date, datetime
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from loguru import logger as _logger
+
+if TYPE_CHECKING:
+    from loguru import Logger, Record
+
+
+_DEFAULT_CONSOLE_FORMAT = (
+    "<green>{time:YYYY-MM-DD HH:mm:ss.SSS}</green> | "
+    "<level>{level: <8}</level> | "
+    "<cyan>{extra[module]}</cyan> - <level>{message}</level>"
+)
+_DEFAULT_FILE_FORMAT = (
+    "{time:YYYY-MM-DD HH:mm:ss.SSS} | {level: <8} | {extra[module]} | {name}:{function}:{line} - {message}"
+)
+_DEFAULT_EXTRA: dict[str, Any] = {"module": "-"}
+
+
+_handler_ids: list[int] = []
+_intercept_state: dict[str, list[logging.Handler]] = {}
+
+
+class _InterceptHandler(logging.Handler):
+    """Route standard ``logging`` records into the loguru sink chain."""
+
+    def emit(self, record: logging.LogRecord) -> None:
+        """Forward a stdlib record to loguru preserving level, exception and frame depth."""
+        try:
+            level: str | int = _logger.level(record.levelname).name
+        except ValueError:
+            level = record.levelno
+
+        frame = inspect.currentframe()
+        depth = 0
+        while frame and (depth == 0 or frame.f_code.co_filename == logging.__file__):
+            frame = frame.f_back
+            depth += 1
+
+        _logger.opt(depth=depth, exception=record.exc_info).log(level, record.getMessage())
+
+
+def _make_rotator(max_bytes: int) -> Any:
+    """Build a loguru ``rotation`` callable that rolls on date change or size cap.
+
+    Args:
+        max_bytes: Maximum bytes per file before a new file is created.
+
+    Returns:
+        A function matching the loguru ``rotation`` callable signature.
+    """
+    state: dict[str, date | None] = {"date": None}
+
+    def _rotate(message: Record, file: Any) -> bool:
+        today = datetime.now().date()
+        if state["date"] is None:
+            state["date"] = today
+            return False
+        if today != state["date"]:
+            state["date"] = today
+            return True
+        return file.tell() + len(str(message)) > max_bytes
+
+    return _rotate
+
+
+def configure(
+    *,
+    level: str = "INFO",
+    log_dir: str | Path | None = None,
+    filename: str = "app",
+    max_bytes: int = 100 * 1024 * 1024,
+    retention: str | int = "30 days",
+    console: bool = True,
+    console_format: str | None = None,
+    file_format: str | None = None,
+    serialize: bool = False,
+    enqueue: bool = True,
+    intercept_stdlib: bool = True,
+    intercept_loggers: list[str] | None = None,
+) -> None:
+    """Configure the global logger. Call once at application startup.
+
+    Args:
+        level: Minimum log level (``DEBUG``/``INFO``/``WARNING``/``ERROR``/``CRITICAL``).
+        log_dir: Directory for log files. ``None`` disables file output.
+        filename: Base filename; final files look like ``{filename}_YYYY-MM-DD.log``.
+        max_bytes: Per-file size cap before rotation (default 100 MB).
+        retention: Loguru retention spec (``"30 days"``, ``"1 week"``, int count, ...).
+        console: Whether to write colored logs to stderr.
+        console_format: Override for the console format string.
+        file_format: Override for the file format string.
+        serialize: Emit JSON lines to the file sink for log aggregators.
+        enqueue: Write asynchronously via a queue — non-blocking and multi-process safe.
+        intercept_stdlib: Route stdlib ``logging`` records through loguru.
+        intercept_loggers: When intercepting, scope to these logger name prefixes
+            (e.g. ``["uvicorn", "sqlalchemy"]``). ``None`` means root (catch-all).
+    """
+    close()
+
+    _logger.configure(extra=_DEFAULT_EXTRA)
+
+    if console:
+        handler_id = _logger.add(
+            sys.stderr,
+            level=level,
+            format=console_format or _DEFAULT_CONSOLE_FORMAT,
+            colorize=True,
+            enqueue=enqueue,
+            backtrace=True,
+            diagnose=False,
+        )
+        _handler_ids.append(handler_id)
+
+    if log_dir is not None:
+        log_path = Path(log_dir)
+        log_path.mkdir(parents=True, exist_ok=True)
+
+        file_sink = str(log_path / f"{filename}_{{time:YYYY-MM-DD}}.log")
+        handler_id = _logger.add(
+            file_sink,
+            level=level,
+            format=file_format or _DEFAULT_FILE_FORMAT,
+            rotation=_make_rotator(max_bytes),
+            retention=retention,
+            encoding="utf-8",
+            enqueue=enqueue,
+            serialize=serialize,
+            backtrace=True,
+            diagnose=False,
+        )
+        _handler_ids.append(handler_id)
+
+    if intercept_stdlib:
+        _install_stdlib_intercept(level, intercept_loggers)
+
+
+def _install_stdlib_intercept(level: str, targets: list[str] | None) -> None:
+    """Replace handlers on stdlib loggers with ``_InterceptHandler``, remembering originals."""
+    handler = _InterceptHandler()
+    roots = targets or [""]
+
+    for name in roots:
+        stdlib_logger = logging.getLogger(name) if name else logging.root
+        _intercept_state[name] = list(stdlib_logger.handlers)
+        stdlib_logger.handlers = [handler]
+        stdlib_logger.setLevel(level)
+        stdlib_logger.propagate = False
+
+
+def get_logger(name: str | None = None) -> Logger:
+    """Return the shared logger, optionally bound to a module name.
+
+    Args:
+        name: Logical module name recorded in the ``module`` extra field.
+
+    Returns:
+        A loguru ``Logger`` proxy. If ``configure`` has not been called yet,
+        returns the raw default logger (stderr at DEBUG).
+    """
+    if name:
+        return _logger.bind(module=name)
+    return _logger
+
+
+def close() -> None:
+    """Remove all handlers, restore stdlib loggers, and flush pending records.
+
+    Safe to call repeatedly. After ``close`` the module can be reconfigured.
+    """
+    for handler_id in _handler_ids:
+        # Handler already removed — benign.
+        with contextlib.suppress(ValueError):
+            _logger.remove(handler_id)
+    _handler_ids.clear()
+
+    for name, original_handlers in _intercept_state.items():
+        stdlib_logger = logging.getLogger(name) if name else logging.root
+        stdlib_logger.handlers = original_handlers
+        stdlib_logger.propagate = True
+    _intercept_state.clear()