feat(date): 添加时间戳转换功能并优化类型注解

- 新增 to_datetime 函数用于将时间戳转换为 datetime 对象
- 优化 timestamp 函数的参数类型注解，将 digits 改为必选参数
- 为 format 和 parse 函数添加 Optional 类型注解
- 更新 __init__.py 导出新增的 to_datetime 函数

Author: mic1on

src/usepy/date/__init__.py

@@ -1,11 +1,12 @@
 from .parse import parse
 from .format import format
 from .now import now
-from .timestamp import timestamp
+from .timestamp import timestamp, to_datetime
 
 __all__ = [
     "parse",
     "format",
     "now",
     "timestamp",
+    "to_datetime",
 ]

src/usepy/date/format.py

@@ -1,7 +1,8 @@
 from datetime import datetime
+from typing import Optional
 
 
-def format(dt: datetime, fmt=None) -> str:
+def format(dt: datetime, fmt: Optional[str] = None) -> str:
     """format date
 
     Args:

src/usepy/date/parse.py

@@ -1,8 +1,9 @@
 from datetime import datetime
 from itertools import chain
+from typing import Optional
 
 
-def parse(time_str: str, fmt=None) -> datetime:
+def parse(time_str: str, fmt: Optional[str] = None) -> datetime:
     """parse date
 
     Args:

src/usepy/date/timestamp.py

@@ -2,13 +2,15 @@
 from typing import Optional
 
 
-def timestamp(dt: Optional[datetime] = None, digits: Optional[int] = 10) -> int:
-    """
-    get timestamp from datetime object
+def timestamp(dt: Optional[datetime] = None, digits: int = 10) -> int:
+    """get timestamp from datetime object
+
+    Args:
+        dt (Optional[datetime], optional): datetime object. Defaults to None.
+        digits (int, optional): timestamp digits, 10 or 13. Defaults to 10.
 
-    :param dt: datetime object, default to current time
-    :param digits: timestamp digits, 10 or 13, default to 10
-    :return: integer timestamp
+    Returns:
+        int: integer timestamp
     """
     if dt is None:
         dt = datetime.now()
@@ -19,3 +21,20 @@ def timestamp(dt: Optional[datetime] = None, digits: Optional[int] = 10) -> int:
         return int(dt.timestamp() * 1000)
     else:
         raise ValueError("timestamp digits must be 10 or 13")
+
+
+def to_datetime(ts: int) -> datetime:
+    """convert timestamp to datetime
+
+    Args:
+        ts (int): timestamp, can be 10 or 13 digits
+
+    Returns:
+        datetime: datetime object
+    """
+    if len(str(ts)) == 13:
+        return datetime.fromtimestamp(ts / 1000)
+    elif len(str(ts)) == 10:
+        return datetime.fromtimestamp(ts)
+    else:
+        raise ValueError("timestamp digits must be 10 or 13")