dwyeapi 0.9.3__tar.gz → 0.9.4__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dwyeapi
-Version: 0.9.3
+Version: 0.9.4
 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.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "dwyeapi"
-version = "0.9.3"
+version = "0.9.4"
 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.4}/src/dwyeapi/__init__.py

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

dwyeapi-0.9.4/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.4}/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.3 → dwyeapi-0.9.4}/src/dwyeapi.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dwyeapi
-Version: 0.9.3
+Version: 0.9.4
 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.4}/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.4/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/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)