"""
日期时间工具类

提供日期时间相关的工具方法

作者: 张翔
日期: 2026-04-01
"""

from datetime import datetime, timedelta
from typing import Optional
import pytz


class DateHelper:
    """日期时间工具类"""
    
    @staticmethod
    def format_datetime(dt: datetime, fmt: str = "%Y-%m-%d %H:%M:%S") -> str:
        """
        格式化日期时间
        
        Args:
            dt: datetime对象
            fmt: 格式字符串
            
        Returns:
            格式化后的字符串
        """
        if dt is None:
            return ""
        return dt.strftime(fmt)
    
    @staticmethod
    def parse_datetime(date_string: str, fmt: str = "%Y-%m-%d %H:%M:%S") -> Optional[datetime]:
        """
        解析日期时间字符串
        
        Args:
            date_string: 日期时间字符串
            fmt: 格式字符串
            
        Returns:
            datetime对象,解析失败返回None
        """
        try:
            return datetime.strptime(date_string, fmt)
        except (ValueError, TypeError):
            return None
    
    @staticmethod
    def days_between(start_date: datetime, end_date: datetime) -> int:
        """
        计算两个日期之间的天数
        
        Args:
            start_date: 开始日期
            end_date: 结束日期
            
        Returns:
            天数差
        """
        if start_date is None or end_date is None:
            return 0
        delta = end_date - start_date
        return delta.days
    
    @staticmethod
    def utc_to_local(utc_time: datetime, timezone: str = "Asia/Shanghai") -> datetime:
        """
        UTC时间转本地时间
        
        Args:
            utc_time: UTC时间
            timezone: 时区名称
            
        Returns:
            本地时间
        """
        if utc_time is None:
            return None
        
        utc_tz = pytz.UTC
        local_tz = pytz.timezone(timezone)
        
        if utc_time.tzinfo is None:
            utc_time = utc_tz.localize(utc_time)
        
        return utc_time.astimezone(local_tz)
    
    @staticmethod
    def get_current_timestamp() -> int:
        """
        获取当前时间戳(秒)
        
        Returns:
            当前时间戳
        """
        return int(datetime.now().timestamp())
    
    @staticmethod
    def add_days(dt: datetime, days: int) -> datetime:
        """
        日期加减天数
        
        Args:
            dt: 日期
            days: 天数(可为负数)
            
        Returns:
            新日期
        """
        if dt is None:
            return None
        return dt + timedelta(days=days)