dwyeapi 0.9.3__tar.gz → 0.9.5__tar.gz

{dwyeapi-0.9.3 → dwyeapi-0.9.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dwyeapi
-Version: 0.9.3
+Version: 0.9.5
 Summary: Lightweight FastAPI infrastructure — exceptions, database, config, security, cache, pagination, logger
 License: MIT
 Project-URL: Repository, https://github.com/danweiyuancircle/dwy-ai-experience

{dwyeapi-0.9.3 → dwyeapi-0.9.5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "dwyeapi"
-version = "0.9.3"
+version = "0.9.5"
 description = "Lightweight FastAPI infrastructure — exceptions, database, config, security, cache, pagination, logger"
 requires-python = ">=3.11"
 license = {text = "MIT"}

{dwyeapi-0.9.3 → dwyeapi-0.9.5}/src/dwyeapi/__init__.py

@@ -32,4 +32,4 @@ __all__ = [
     "is_prod",
     "logger",
 ]
-__version__ = "0.9.1"
+__version__ = "0.9.5"

dwyeapi-0.9.5/src/dwyeapi/dt.py

@@ -0,0 +1,113 @@
+"""全局时间工具 — 所有日期 / 时长操作的唯一入口。
+
+业务时间统一 Asia/Shanghai, JWT 等协议场景提供 UTC 方法。
+禁止在业务代码中直接使用 ``datetime.now()`` / ``datetime.utcnow()`` /
+``from datetime import timedelta``,统一通过本模块访问。
+
+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
+
+    dt.timedelta(minutes=10)      # 时长(透传 stdlib timedelta)
+    dt.after(days=1)              # now + 偏移(naive 中国时间)
+    dt.before(hours=1)            # now - 偏移
+    dt.utc_after(minutes=30)      # utc_now + 偏移(aware UTC, JWT exp)
+    dt.utc_before(days=1)         # utc_now - 偏移
+"""
+
+from datetime import date, datetime
+from datetime import timedelta as _Timedelta
+from zoneinfo import ZoneInfo
+
+TZ = ZoneInfo("Asia/Shanghai")
+UTC = ZoneInfo("UTC")
+
+# 公开 re-export:业务侧用 dt.timedelta(...),不再 from datetime import timedelta
+timedelta = _Timedelta
+
+
+# ── 业务时间(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()
+
+
+def after(**kwargs: int | float) -> datetime:
+    """当前中国时间加上偏移,返回 naive datetime(写库 / 业务截止时间)。
+
+    Args:
+        **kwargs: 同 ``datetime.timedelta`` 关键字参数
+            (``days`` / ``seconds`` / ``microseconds`` / ``milliseconds`` /
+            ``minutes`` / ``hours`` / ``weeks``)。示例:``days=1, hours=2``。
+
+    Returns:
+        datetime: ``now() + timedelta(**kwargs)``,无时区信息。
+    """
+    return now() + _Timedelta(**kwargs)
+
+
+def before(**kwargs: int | float) -> datetime:
+    """当前中国时间减去偏移,返回 naive datetime。
+
+    Args:
+        **kwargs: 同 ``after``。示例:``hours=1``。
+
+    Returns:
+        datetime: ``now() - timedelta(**kwargs)``,无时区信息。
+    """
+    return now() - _Timedelta(**kwargs)
+
+
+# ── UTC(JWT 等协议场景) ──────────────────────────────────────────────
+
+
+def utc_now() -> datetime:
+    """当前 UTC 时间(aware, 用于 JWT exp 等协议字段)。"""
+    return datetime.now(UTC)
+
+
+def utc_after(**kwargs: int | float) -> datetime:
+    """当前 UTC 时间加上偏移,返回 aware datetime(JWT exp 等)。
+
+    Args:
+        **kwargs: 同 ``after``。示例:``minutes=30``。
+
+    Returns:
+        datetime: ``utc_now() + timedelta(**kwargs)``,tzinfo=UTC。
+    """
+    return utc_now() + _Timedelta(**kwargs)
+
+
+def utc_before(**kwargs: int | float) -> datetime:
+    """当前 UTC 时间减去偏移,返回 aware datetime。
+
+    Args:
+        **kwargs: 同 ``after``。示例:``days=1``。
+
+    Returns:
+        datetime: ``utc_now() - timedelta(**kwargs)``,tzinfo=UTC。
+    """
+    return utc_now() - _Timedelta(**kwargs)

{dwyeapi-0.9.3 → dwyeapi-0.9.5}/src/dwyeapi/providers/email/base.py

@@ -63,11 +63,17 @@ class EmailProviderBase(ABC):
         return "".join(secrets.choice("0123456789") for _ in range(self._length))
 
     async def send_code(self, target: str) -> bool:
-        """生成验证码存 Redis 并调用 `_send()` 发送。"""
+        """生成验证码：先发送成功再写入 Redis。
+
+        顺序约束：``_send`` 失败时不落库，避免用户未收到邮件却有可校验码。
+        发送成功后写 Redis；若写库失败则返回 False（邮件已发出属极端边界，业务可重发覆盖）。
+        """
         code = self._generate_code()
+        if not await self._send(target, code):
+            return False
         redis = await self._get_redis()
         await redis.set(f"{CODE_KEY_PREFIX}{target}", code, ex=self._ttl)
-        return await self._send(target, code)
+        return True
 
     async def verify_code(self, target: str, code: str) -> bool:
         """从 Redis 读取存储的验证码比对,成功则删除 key(一次性)。"""

{dwyeapi-0.9.3 → dwyeapi-0.9.5}/src/dwyeapi/providers/email/factory.py

@@ -64,6 +64,9 @@ def make_email_provider(settings: EmailSettings) -> EmailProvider:
 
         if not settings.resend.api_key:
             raise ValueError("EMAIL__RESEND__API_KEY 未配置")
+        # from_email 启用时必填：缺省会导致 resend 运行时发信失败，尽早在工厂拦截
+        if not settings.resend.from_email:
+            raise ValueError("EMAIL__RESEND__FROM_EMAIL 未配置")
         return ResendEmailProvider(
             api_key=settings.resend.api_key,
             from_email=settings.resend.from_email,

{dwyeapi-0.9.3 → dwyeapi-0.9.5}/src/dwyeapi/security.py

@@ -4,7 +4,6 @@
 所有函数保持无状态 — 密钥和算法由调用方以参数显式传入,方便在不同环境或密钥版本之间切换。
 """
 
-from datetime import timedelta
 from typing import Any
 
 import bcrypt
@@ -63,7 +62,8 @@ def create_token(
         编码后的 JWT 字符串。
     """
     to_encode = data.copy()
-    expire = dt.utc_now() + timedelta(minutes=expires_minutes)
+    # JWT exp 必须用 UTC aware;时长与当前时刻统一走 dt
+    expire = dt.utc_after(minutes=expires_minutes)
     to_encode["exp"] = expire
     return jwt.encode(to_encode, secret, algorithm=algorithm)
 

dwyeapi-0.9.5/src/dwyeapi/tasks/schema.py

@@ -0,0 +1,42 @@
+"""任务 API 请求/响应的 Pydantic schema。"""
+
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from dwyeapi.tasks.model import TaskStatus
+
+# 与 Task ORM 列 String(50) 对齐；params 键数/体积限制防超大 body
+_TASK_TYPE_MAX_LEN = 50
+_PARAMS_MAX_KEYS = 50
+
+
+class TaskCreate(BaseModel):
+    """提交新任务的请求体。
+
+    约束与 ORM / 输入限长规则对齐：``task_type`` 最长 50；``params`` 最多 50 个键。
+    """
+
+    task_type: str = Field(min_length=1, max_length=_TASK_TYPE_MAX_LEN, description="已注册的任务类型名")
+    params: dict[str, Any] = Field(
+        default_factory=dict,
+        description="任务参数；键数量上限 50，避免超大 JSON 入库",
+        max_length=_PARAMS_MAX_KEYS,
+    )
+
+
+class TaskResponse(BaseModel):
+    """任务详情响应体,覆盖状态、进度、日志与结果等字段。"""
+
+    id: str
+    task_type: str
+    status: TaskStatus
+    params: dict[str, Any]
+    result: dict[str, Any] | None
+    progress: int
+    logs: str
+    created_at: datetime
+    updated_at: datetime
+
+    model_config = ConfigDict(from_attributes=True)

{dwyeapi-0.9.3 → dwyeapi-0.9.5}/src/dwyeapi.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dwyeapi
-Version: 0.9.3
+Version: 0.9.5
 Summary: Lightweight FastAPI infrastructure — exceptions, database, config, security, cache, pagination, logger
 License: MIT
 Project-URL: Repository, https://github.com/danweiyuancircle/dwy-ai-experience

{dwyeapi-0.9.3 → dwyeapi-0.9.5}/src/dwyeapi.egg-info/SOURCES.txt

@@ -38,6 +38,7 @@ tests/test_cache.py
 tests/test_config.py
 tests/test_database.py
 tests/test_dependencies.py
+tests/test_dt.py
 tests/test_exceptions.py
 tests/test_health.py
 tests/test_logger.py

dwyeapi-0.9.5/tests/test_dt.py

@@ -0,0 +1,75 @@
+"""Tests for dwyeapi.dt — 时钟与时长统一入口。"""
+
+from datetime import datetime, timedelta, timezone
+
+from dwyeapi import dt
+
+
+class TestClock:
+    def test_now_is_naive(self):
+        assert dt.now().tzinfo is None
+
+    def test_utc_now_is_aware_utc(self):
+        now = dt.utc_now()
+        assert now.tzinfo is not None
+        # 与 UTC 偏移为 0
+        assert now.utcoffset() == timedelta(0)
+
+    def test_today_is_date(self):
+        assert dt.today() == dt.now().date()
+
+    def test_timestamp_is_float(self):
+        ts = dt.timestamp()
+        assert isinstance(ts, float)
+        assert ts > 0
+
+
+class TestTimedelta:
+    def test_timedelta_reexport(self):
+        delta = dt.timedelta(minutes=10)
+        assert isinstance(delta, timedelta)
+        assert delta == timedelta(minutes=10)
+
+    def test_timedelta_days_and_hours(self):
+        assert dt.timedelta(days=1, hours=2) == timedelta(days=1, hours=2)
+
+
+class TestAfterBefore:
+    def test_after_is_naive_and_future(self):
+        base = dt.now()
+        future = dt.after(minutes=5)
+        assert future.tzinfo is None
+        assert future > base
+        # 约 5 分钟,允许毫秒级误差
+        assert abs((future - base).total_seconds() - 300) < 1
+
+    def test_before_is_naive_and_past(self):
+        base = dt.now()
+        past = dt.before(hours=1)
+        assert past.tzinfo is None
+        assert past < base
+        assert abs((base - past).total_seconds() - 3600) < 1
+
+    def test_utc_after_is_aware_and_future(self):
+        base = dt.utc_now()
+        future = dt.utc_after(minutes=30)
+        assert future.tzinfo is not None
+        assert future.utcoffset() == timedelta(0)
+        assert future > base
+        assert abs((future - base).total_seconds() - 1800) < 1
+
+    def test_utc_before_is_aware_and_past(self):
+        base = dt.utc_now()
+        past = dt.utc_before(days=1)
+        assert past.tzinfo is not None
+        assert past < base
+        assert abs((base - past).total_seconds() - 86400) < 1
+
+    def test_utc_after_compatible_with_jwt_exp(self):
+        """utc_after 结果可直接写入 JWT exp(aware UTC)。"""
+        exp = dt.utc_after(minutes=10)
+        # python-jose 接受 datetime;这里只校验形态
+        assert isinstance(exp, datetime)
+        assert exp.tzinfo is not None
+        # 与 timezone.utc 兼容
+        assert exp.astimezone(timezone.utc).tzinfo is not None

{dwyeapi-0.9.3 → dwyeapi-0.9.5}/tests/test_tasks.py

@@ -127,6 +127,30 @@ class TestSchemas:
         assert tc.task_type == "export"
         assert tc.params == {"format": "csv"}
 
+    def test_task_create_rejects_empty_task_type(self):
+        """task_type 最短 1 字符。"""
+        import pytest
+        from pydantic import ValidationError
+
+        with pytest.raises(ValidationError):
+            TaskCreate(task_type="", params={})
+
+    def test_task_create_rejects_long_task_type(self):
+        """task_type 最长 50，对齐 ORM String(50)。"""
+        import pytest
+        from pydantic import ValidationError
+
+        with pytest.raises(ValidationError):
+            TaskCreate(task_type="x" * 51, params={})
+
+    def test_task_create_rejects_too_many_params_keys(self):
+        """params 键数上限 50。"""
+        import pytest
+        from pydantic import ValidationError
+
+        with pytest.raises(ValidationError):
+            TaskCreate(task_type="export", params={f"k{i}": i for i in range(51)})
+
     async def test_task_response_from_attributes(self, session):
         """TaskResponse should be constructible from a persisted Task ORM object."""
         task = Task(

dwyeapi-0.9.3/src/dwyeapi/dt.py

@@ -1,52 +0,0 @@
-"""全局时间工具 — 所有日期操作的唯一入口。
-
-业务时间统一 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
-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.9.3/src/dwyeapi/tasks/schema.py

@@ -1,31 +0,0 @@
-"""任务 API 请求/响应的 Pydantic schema。"""
-
-from datetime import datetime
-from typing import Any
-
-from pydantic import BaseModel, ConfigDict
-
-from dwyeapi.tasks.model import TaskStatus
-
-
-class TaskCreate(BaseModel):
-    """提交新任务的请求体。"""
-
-    task_type: str
-    params: dict[str, Any]
-
-
-class TaskResponse(BaseModel):
-    """任务详情响应体,覆盖状态、进度、日志与结果等字段。"""
-
-    id: str
-    task_type: str
-    status: TaskStatus
-    params: dict[str, Any]
-    result: dict[str, Any] | None
-    progress: int
-    logs: str
-    created_at: datetime
-    updated_at: datetime
-
-    model_config = ConfigDict(from_attributes=True)