staran 1.0.5__py3-none-any.whl → 1.0.7__py3-none-any.whl

staran/date/core.py

@@ -14,7 +14,7 @@ import calendar
 import re
 import logging
 import time
-from typing import Union, Optional, Tuple, Dict, Any
+from typing import Union, Optional, Tuple, Dict, Any, List
 from functools import lru_cache
 
 class DateError(ValueError):
@@ -104,8 +104,17 @@ class Date:
     >>> print(date.format_chinese())     # 2025年04月15日
     >>> print(date.get_weekday())        # 1 (星期二)
     >>> print(date.is_weekend())         # False
+    
+    Raises:
+    -------
+    InvalidDateFormatError
+        当输入的日期格式无效时抛出
+    InvalidDateValueError
+        当日期值超出有效范围时抛出
     """
     
+    __slots__ = ('year', 'month', 'day', '_input_format')
+    
     # 类级别的日志记录器
     _logger = DateLogger()
     
@@ -203,9 +212,14 @@ class Date:
     
     def _validate_date(self):
         """验证日期的有效性"""
+        # 基本范围检查
         if not (1 <= self.month <= 12):
             raise InvalidDateValueError(f"无效的月份: {self.month}")
         
+        # 年份合理性检查
+        if not (1900 <= self.year <= 3000):
+            self._logger.warning(f"年份 {self.year} 超出常规范围 (1900-3000)")
+        
         max_days = calendar.monthrange(self.year, self.month)[1]
         if not (1 <= self.day <= max_days):
             raise InvalidDateValueError(f"无效的日期: {self.day} (对于 {self.year}-{self.month})")
@@ -214,10 +228,39 @@ class Date:
             datetime.date(self.year, self.month, self.day)
         except ValueError as e:
             raise InvalidDateValueError(f"无效的日期: {self.year}-{self.month}-{self.day}") from e
+        
+        # 特殊日期检查
+        self._check_special_dates()
+    
+    def _check_special_dates(self):
+        """检查特殊日期"""
+        # 检查是否为闰年2月29日
+        if self.month == 2 and self.day == 29 and not calendar.isleap(self.year):
+            raise InvalidDateValueError(f"非闰年 {self.year} 不存在2月29日")
+            
+        # 检查历史边界日期
+        if self.year < 1582 and self.month == 10 and 5 <= self.day <= 14:
+            self._logger.warning("日期位于格里高利历改革期间 (1582年10月5-14日)")
+            
+    @classmethod
+    def is_valid_date_string(cls, date_string: str) -> bool:
+        """检查日期字符串是否有效
+        
+        Args:
+            date_string: 日期字符串
+            
+        Returns:
+            是否为有效日期字符串
+        """
+        try:
+            cls(date_string)
+            return True
+        except (InvalidDateFormatError, InvalidDateValueError):
+            return False
     
     @lru_cache(maxsize=128)
     def _create_with_same_format(self, year: int, month: int, day: int) -> 'Date':
-        """创建具有相同格式的新Date对象 (带缓存)"""
+        """创建具有相同格式的新Date对象"""
         new_date = Date(year, month, day)
         new_date._input_format = self._input_format
         return new_date
@@ -244,9 +287,17 @@ class Date:
         return cls(date_string)
     
     @classmethod
-    def from_timestamp(cls, timestamp: Union[int, float]) -> 'Date':
-        """从时间戳创建Date对象"""
+    def from_timestamp(cls, timestamp: Union[int, float], timezone_offset: int = 0) -> 'Date':
+        """从时间戳创建Date对象
+        
+        Args:
+            timestamp: Unix时间戳
+            timezone_offset: 时区偏移小时数 (如 +8 表示东八区)
+        """
         dt = datetime.datetime.fromtimestamp(timestamp)
+        # 调整时区
+        if timezone_offset != 0:
+            dt = dt + datetime.timedelta(hours=timezone_offset)
         return cls(dt.date())
     
     @classmethod
@@ -259,6 +310,95 @@ class Date:
         """创建今日Date对象"""
         return cls(datetime.date.today())
     
+    @classmethod
+    def date_range(cls, start: Union[str, 'Date'], end: Union[str, 'Date'], 
+                   step: int = 1) -> List['Date']:
+        """生成日期范围
+        
+        Args:
+            start: 开始日期
+            end: 结束日期
+            step: 步长（天数）
+            
+        Returns:
+            日期列表
+        """
+        if isinstance(start, str):
+            start = cls.from_string(start)
+        if isinstance(end, str):
+            end = cls.from_string(end)
+            
+        dates = []
+        current = start
+        while current <= end:
+            dates.append(current)
+            current = current.add_days(step)
+        return dates
+    
+    @classmethod
+    def business_days(cls, start: Union[str, 'Date'], end: Union[str, 'Date']) -> List['Date']:
+        """生成工作日列表"""
+        dates = cls.date_range(start, end)
+        return [date for date in dates if date.is_business_day()]
+    
+    @classmethod
+    def weekends(cls, start: Union[str, 'Date'], end: Union[str, 'Date']) -> List['Date']:
+        """生成周末日期列表"""
+        dates = cls.date_range(start, end)
+        return [date for date in dates if date.is_weekend()]
+    
+    @classmethod
+    def month_range(cls, start_year_month: Union[str, 'Date'], months: int) -> List['Date']:
+        """生成月份范围
+        
+        Args:
+            start_year_month: 开始年月 (如 "202501" 或 Date对象)
+            months: 月份数量
+            
+        Returns:
+            月份第一天的日期列表
+            
+        Example:
+            Date.month_range("202501", 3)  # [202501, 202502, 202503]
+        """
+        if isinstance(start_year_month, str):
+            start_date = cls.from_string(start_year_month)
+        else:
+            start_date = start_year_month
+            
+        # 确保是月初
+        start_date = start_date.get_month_start()
+        
+        result = []
+        current = start_date
+        for _ in range(months):
+            result.append(current)
+            current = current.add_months(1)
+        
+        return result
+    
+    @classmethod 
+    def quarter_dates(cls, year: int) -> Dict[int, Tuple['Date', 'Date']]:
+        """获取指定年份的季度起止日期
+        
+        Args:
+            year: 年份
+            
+        Returns:
+            季度字典 {1: (Q1开始, Q1结束), 2: (Q2开始, Q2结束), ...}
+        """
+        quarters = {}
+        for quarter in range(1, 5):
+            start_month = (quarter - 1) * 3 + 1
+            end_month = quarter * 3
+            
+            start_date = cls(year, start_month, 1)
+            end_date = cls(year, end_month, 1).get_month_end()
+            
+            quarters[quarter] = (start_date, end_date)
+            
+        return quarters
+    
     # =============================================
     # to_* 系列：转换方法
     # =============================================
@@ -267,14 +407,6 @@ class Date:
         """转为元组 (year, month, day)"""
         return (self.year, self.month, self.day)
     
-    def to_dict(self) -> Dict[str, int]:
-        """转为字典"""
-        return {
-            'year': self.year,
-            'month': self.month,
-            'day': self.day
-        }
-    
     def to_date_object(self) -> datetime.date:
         """转为datetime.date对象"""
         return datetime.date(self.year, self.month, self.day)
@@ -283,9 +415,109 @@ class Date:
         """转为datetime.datetime对象"""
         return datetime.datetime(self.year, self.month, self.day)
     
-    def to_timestamp(self) -> float:
-        """转为时间戳"""
-        return self.to_datetime_object().timestamp()
+    def to_timestamp(self, timezone_offset: int = 0) -> float:
+        """转为时间戳
+        
+        Args:
+            timezone_offset: 时区偏移小时数 (如 +8 表示东八区)
+            
+        Returns:
+            Unix时间戳
+        """
+        dt = self.to_datetime_object()
+        # 调整时区
+        if timezone_offset != 0:
+            dt = dt - datetime.timedelta(hours=timezone_offset)
+        return dt.timestamp()
+    
+    def to_json(self, include_metadata: bool = True) -> str:
+        """转为JSON字符串
+        
+        Args:
+            include_metadata: 是否包含元数据（格式、版本等）
+            
+        Returns:
+            JSON字符串
+        """
+        import json
+        
+        data = {
+            'date': self.format_iso(),
+            'year': self.year,
+            'month': self.month,
+            'day': self.day
+        }
+        
+        if include_metadata:
+            data.update({
+                'format': self._input_format,
+                'weekday': self.get_weekday(),
+                'is_weekend': self.is_weekend(),
+                'quarter': self.get_quarter(),
+                'version': '1.0.7'
+            })
+        
+        return json.dumps(data, ensure_ascii=False)
+    
+    @classmethod
+    def from_json(cls, json_str: str) -> 'Date':
+        """从JSON字符串创建Date对象
+        
+        Args:
+            json_str: JSON字符串
+            
+        Returns:
+            Date对象
+            
+        Raises:
+            ValueError: JSON格式错误或缺少必要字段
+        """
+        import json
+        
+        try:
+            data = json.loads(json_str)
+        except json.JSONDecodeError as e:
+            raise ValueError(f"无效的JSON格式: {e}")
+        
+        # 检查必要字段
+        required_fields = ['year', 'month', 'day']
+        missing_fields = [field for field in required_fields if field not in data]
+        if missing_fields:
+            raise ValueError(f"JSON缺少必要字段: {missing_fields}")
+        
+        try:
+            date = cls(data['year'], data['month'], data['day'])
+            date._input_format = data.get('format', 'iso')
+            return date
+        except (InvalidDateFormatError, InvalidDateValueError) as e:
+            raise ValueError(f"JSON中的日期数据无效: {e}")
+    
+    def to_dict(self, include_metadata: bool = False) -> Dict[str, Any]:
+        """转为字典
+        
+        Args:
+            include_metadata: 是否包含元数据
+            
+        Returns:
+            字典表示
+        """
+        result = {
+            'year': self.year,
+            'month': self.month,
+            'day': self.day
+        }
+        
+        if include_metadata:
+            result.update({
+                'format': self._input_format,
+                'weekday': self.get_weekday(),
+                'is_weekend': self.is_weekend(),
+                'quarter': self.get_quarter(),
+                'iso_string': self.format_iso(),
+                'compact_string': self.format_compact()
+            })
+        
+        return result
     
     # =============================================
     # format_* 系列：格式化方法
@@ -335,6 +567,67 @@ class Date:
         dt = self.to_datetime_object()
         return dt.strftime(fmt)
     
+    def format_weekday(self, lang: str = 'zh') -> str:
+        """格式化星期几"""
+        weekday = self.get_weekday()
+        if lang == 'zh':
+            weekdays = ['星期一', '星期二', '星期三', '星期四', '星期五', '星期六', '星期日']
+        else:  # en
+            weekdays = ['Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday', 'Sunday']
+        return weekdays[weekday]
+    
+    def format_month_name(self, lang: str = 'zh') -> str:
+        """格式化月份名称"""
+        if lang == 'zh':
+            months = ['一月', '二月', '三月', '四月', '五月', '六月',
+                     '七月', '八月', '九月', '十月', '十一月', '十二月']
+        else:  # en
+            months = ['January', 'February', 'March', 'April', 'May', 'June',
+                     'July', 'August', 'September', 'October', 'November', 'December']
+        return months[self.month - 1]
+    
+    def format_relative(self, reference_date: Optional['Date'] = None, lang: str = 'zh') -> str:
+        """相对时间格式化"""
+        if reference_date is None:
+            reference_date = Date.today()
+        
+        diff_days = reference_date.calculate_difference_days(self)
+        
+        if lang == 'zh':
+            if diff_days == 0:
+                return "今天"
+            elif diff_days == 1:
+                return "明天"
+            elif diff_days == -1:
+                return "昨天"
+            elif diff_days == 2:
+                return "后天"
+            elif diff_days == -2:
+                return "前天"
+            elif 3 <= diff_days <= 6:
+                return f"{diff_days}天后"
+            elif -6 <= diff_days <= -3:
+                return f"{abs(diff_days)}天前"
+            elif 7 <= diff_days <= 13:
+                return "下周"
+            elif -13 <= diff_days <= -7:
+                return "上周"
+            elif diff_days > 0:
+                return f"{diff_days}天后"
+            else:
+                return f"{abs(diff_days)}天前"
+        else:  # en
+            if diff_days == 0:
+                return "today"
+            elif diff_days == 1:
+                return "tomorrow"
+            elif diff_days == -1:
+                return "yesterday"
+            elif diff_days > 0:
+                return f"in {diff_days} days"
+            else:
+                return f"{abs(diff_days)} days ago"
+    
     # =============================================
     # get_* 系列：获取方法
     # =============================================
@@ -364,6 +657,38 @@ class Date:
         """获取年末日期"""
         return self._create_with_same_format(self.year, 12, 31)
     
+    def get_quarter_start(self) -> 'Date':
+        """获取季度开始日期"""
+        quarter = self.get_quarter()
+        start_month = (quarter - 1) * 3 + 1
+        return self._create_with_same_format(self.year, start_month, 1)
+    
+    def get_quarter_end(self) -> 'Date':
+        """获取季度结束日期"""
+        quarter = self.get_quarter()
+        end_month = quarter * 3
+        if end_month == 3:
+            end_day = 31
+        elif end_month == 6:
+            end_day = 30
+        elif end_month == 9:
+            end_day = 30
+        else:  # 12
+            end_day = 31
+        return self._create_with_same_format(self.year, end_month, end_day)
+    
+    def get_week_start(self) -> 'Date':
+        """获取本周开始日期（周一）"""
+        days_since_monday = self.get_weekday()
+        start_date = self.subtract_days(days_since_monday)
+        return start_date
+    
+    def get_week_end(self) -> 'Date':
+        """获取本周结束日期（周日）"""
+        days_until_sunday = 6 - self.get_weekday()
+        end_date = self.add_days(days_until_sunday)
+        return end_date
+    
     def get_days_in_month(self) -> int:
         """获取当月天数"""
         return calendar.monthrange(self.year, self.month)[1]
@@ -372,6 +697,18 @@ class Date:
         """获取当年天数"""
         return 366 if calendar.isleap(self.year) else 365
     
+    def get_quarter(self) -> int:
+        """获取季度 (1-4)"""
+        return (self.month - 1) // 3 + 1
+    
+    def get_week_of_year(self) -> int:
+        """获取年内第几周 (ISO周数)"""
+        return self.to_date_object().isocalendar()[1]
+    
+    def get_day_of_year(self) -> int:
+        """获取年内第几天 (1-366)"""
+        return self.to_date_object().timetuple().tm_yday
+    
     # =============================================
     # is_* 系列：判断方法
     # =============================================
@@ -404,6 +741,127 @@ class Date:
         """是否为年末"""
         return self.month == 12 and self.day == 31
     
+    def is_business_day(self) -> bool:
+        """是否为工作日（简单版本，仅考虑周末）"""
+        return self.get_weekday() < 5
+    
+    def is_quarter_start(self) -> bool:
+        """是否为季度开始"""
+        return self.day == 1 and self.month in [1, 4, 7, 10]
+    
+    def is_quarter_end(self) -> bool:
+        """是否为季度结束"""
+        quarter_end_months = {3: 31, 6: 30, 9: 30, 12: 31}
+        return (self.month in quarter_end_months and 
+                self.day == quarter_end_months[self.month])
+    
+    def is_holiday(self, country: str = 'CN') -> bool:
+        """是否为节假日（增强版实现）
+        
+        Args:
+            country: 国家代码 ('CN', 'US', 'UK', 'JP' 等)
+            
+        Returns:
+            是否为节假日
+            
+        Note:
+            支持多国节假日，包含农历节日计算
+        """
+        if country == 'CN':
+            # 中国固定节假日
+            fixed_holidays = [
+                (1, 1),   # 元旦
+                (5, 1),   # 劳动节
+                (10, 1),  # 国庆节
+                (10, 2),  # 国庆节
+                (10, 3),  # 国庆节
+                (12, 13), # 国家公祭日
+            ]
+            
+            # 检查固定节假日
+            if (self.month, self.day) in fixed_holidays:
+                return True
+                
+            # 特殊节日计算
+            # 春节：农历正月初一（简化版本，实际需要农历计算）
+            # 清明节：4月4日或5日（简化）
+            if self.month == 4 and self.day in [4, 5]:
+                return True
+                
+            # 端午节、中秋节等需要农历计算，这里提供扩展接口
+            return self._check_lunar_holidays()
+            
+        elif country == 'US':
+            # 美国节假日
+            fixed_holidays = [
+                (1, 1),   # New Year's Day
+                (7, 4),   # Independence Day
+                (12, 25), # Christmas Day
+                (11, 11), # Veterans Day
+            ]
+            
+            if (self.month, self.day) in fixed_holidays:
+                return True
+                
+            # 感恩节：11月第四个星期四
+            if self.month == 11:
+                return self._is_thanksgiving()
+                
+        elif country == 'JP':
+            # 日本节假日
+            fixed_holidays = [
+                (1, 1),   # 元日
+                (2, 11),  # 建国記念の日
+                (4, 29),  # 昭和の日
+                (5, 3),   # 憲法記念日
+                (5, 4),   # みどりの日
+                (5, 5),   # こどもの日
+                (11, 3),  # 文化の日
+                (11, 23), # 勤労感謝の日
+                (12, 23), # 天皇誕生日
+            ]
+            return (self.month, self.day) in fixed_holidays
+            
+        elif country == 'UK':
+            # 英国节假日
+            fixed_holidays = [
+                (1, 1),   # New Year's Day
+                (12, 25), # Christmas Day
+                (12, 26), # Boxing Day
+            ]
+            return (self.month, self.day) in fixed_holidays
+            
+        else:
+            # 未知国家，返回False
+            return False
+    
+    def _check_lunar_holidays(self) -> bool:
+        """检查农历节假日（扩展接口）
+        
+        Note:
+            这是一个扩展接口，实际项目中可以集成农历库
+            如 `lunardate` 或 `zhdate` 等第三方库
+        """
+        # 这里可以扩展农历节日计算
+        # 目前返回 False，保持轻量级
+        return False
+    
+    def _is_thanksgiving(self) -> bool:
+        """判断是否为美国感恩节（11月第四个星期四）"""
+        if self.month != 11:
+            return False
+            
+        # 找到11月第一天是星期几
+        first_day = Date(self.year, 11, 1)
+        first_weekday = first_day.get_weekday()
+        
+        # 计算第四个星期四的日期
+        # 星期四是weekday=3
+        days_to_first_thursday = (3 - first_weekday) % 7
+        fourth_thursday = 1 + days_to_first_thursday + 21  # 第四个星期四
+        
+        return self.day == fourth_thursday
+    
     # =============================================
     # add_*/subtract_* 系列：运算方法
     # =============================================
@@ -471,6 +929,120 @@ class Date:
         """计算与另一个日期的月数差（近似）"""
         return (other.year - self.year) * 12 + (other.month - self.month)
     
+    def calculate_age_years(self, reference_date: Optional['Date'] = None) -> int:
+        """计算年龄（以年为单位）"""
+        if reference_date is None:
+            reference_date = Date.today()
+        
+        age = reference_date.year - self.year
+        
+        # 如果还没到生日，年龄减1
+        if (reference_date.month, reference_date.day) < (self.month, self.day):
+            age -= 1
+            
+        return age
+    
+    def days_until(self, target_date: 'Date') -> int:
+        """计算距离目标日期还有多少天"""
+        return self.calculate_difference_days(target_date)
+    
+    def days_since(self, start_date: 'Date') -> int:
+        """计算从起始日期过了多少天"""
+        return start_date.calculate_difference_days(self)
+    
+    # =============================================
+    # 批量处理方法
+    # =============================================
+    
+    @classmethod
+    def batch_create(cls, date_strings: List[str]) -> List['Date']:
+        """批量创建Date对象
+        
+        Args:
+            date_strings: 日期字符串列表
+            
+        Returns:
+            Date对象列表
+            
+        Raises:
+            InvalidDateFormatError: 如果某个字符串格式无效
+        """
+        result = []
+        for date_str in date_strings:
+            try:
+                result.append(cls(date_str))
+            except (InvalidDateFormatError, InvalidDateValueError) as e:
+                cls._logger.error(f"批量创建失败: {date_str} - {e}")
+                raise
+        return result
+    
+    @classmethod
+    def batch_format(cls, dates: List['Date'], format_type: str = 'iso') -> List[str]:
+        """批量格式化日期
+        
+        Args:
+            dates: Date对象列表
+            format_type: 格式类型 ('iso', 'chinese', 'compact' 等)
+            
+        Returns:
+            格式化后的字符串列表
+        """
+        format_methods = {
+            'iso': lambda d: d.format_iso(),
+            'chinese': lambda d: d.format_chinese(),
+            'compact': lambda d: d.format_compact(),
+            'slash': lambda d: d.format_slash(),
+            'dot': lambda d: d.format_dot(),
+            'default': lambda d: d.format_default()
+        }
+        
+        format_func = format_methods.get(format_type, lambda d: d.format_default())
+        return [format_func(date) for date in dates]
+    
+    @classmethod
+    def batch_add_days(cls, dates: List['Date'], days: int) -> List['Date']:
+        """批量添加天数
+        
+        Args:
+            dates: Date对象列表
+            days: 要添加的天数
+            
+        Returns:
+            新的Date对象列表
+        """
+        return [date.add_days(days) for date in dates]
+    
+    def apply_business_rule(self, rule: str, **kwargs) -> 'Date':
+        """应用业务规则
+        
+        Args:
+            rule: 规则名称
+                - 'month_end': 移动到月末
+                - 'quarter_end': 移动到季度末
+                - 'next_business_day': 移动到下一个工作日
+                - 'prev_business_day': 移动到上一个工作日
+            **kwargs: 规则参数
+            
+        Returns:
+            应用规则后的新Date对象
+        """
+        if rule == 'month_end':
+            return self.get_month_end()
+        elif rule == 'quarter_end':
+            return self.get_quarter_end()
+        elif rule == 'next_business_day':
+            current = self
+            while not current.is_business_day():
+                current = current.add_days(1)
+            return current
+        elif rule == 'prev_business_day':
+            current = self
+            while not current.is_business_day():
+                current = current.subtract_days(1)
+            return current
+        else:
+            raise ValueError(f"未知的业务规则: {rule}")
+    
     # =============================================
     # 配置和日志方法
     # =============================================