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

staran/date/core.py

@@ -2,11 +2,18 @@
 # -*- coding: utf-8 -*-
 
 """
-Staran 核心日期处理模块
-====================
+Staran 核心日期处理模块 v1.0.9
+============================
 
-提供Date类的完整实现，包括86+个企业级API方法、
+提供Date类的完整实现，包括120+个企业级API方法、
 智能格式记忆、日期运算和多种格式化选项。
+
+v1.0.9 新增功能:
+- 智能日期推断
+- 异步批量处理支持  
+- 高级业务规则引擎
+- 日期范围操作
+- 性能优化和内存优化
 """
 
 import datetime
@@ -14,8 +21,17 @@ import calendar
 import re
 import logging
 import time
-from typing import Union, Optional, Tuple, Dict, Any, List
-from functools import lru_cache
+import asyncio
+import csv
+import json
+from typing import Union, Optional, Tuple, Dict, Any, List, Set, TypeVar, Generic
+from functools import lru_cache, wraps
+from dataclasses import dataclass
+import threading
+
+# 导入农历和多语言模块
+from .lunar import LunarDate
+from .i18n import Language
 
 class DateError(ValueError):
     """Date模块的特定异常基类"""
@@ -30,6 +46,149 @@ class InvalidDateValueError(DateError):
     pass
 
 
+@dataclass
+class DateRange:
+    """日期范围类 (v1.0.9)
+    
+    表示一个日期范围，支持交集、并集等操作
+    """
+    start: 'Date'
+    end: 'Date'
+    
+    def __post_init__(self):
+        if self.start > self.end:
+            raise ValueError(f"起始日期 {self.start} 不能大于结束日期 {self.end}")
+    
+    def contains(self, date: 'Date') -> bool:
+        """检查日期是否在范围内"""
+        return self.start <= date <= self.end
+    
+    def intersect(self, other: 'DateRange') -> Optional['DateRange']:
+        """计算与另一个范围的交集"""
+        start = max(self.start, other.start)
+        end = min(self.end, other.end)
+        if start <= end:
+            return DateRange(start, end)
+        return None
+    
+    def union(self, other: 'DateRange') -> 'DateRange':
+        """计算与另一个范围的并集"""
+        start = min(self.start, other.start)
+        end = max(self.end, other.end)
+        return DateRange(start, end)
+    
+    def days_count(self) -> int:
+        """范围内的天数"""
+        return self.start.calculate_difference_days(self.end) + 1
+
+
+class SmartDateInference:
+    """智能日期推断器 (v1.0.9)
+    
+    自动推断不完整的日期信息
+    """
+    
+    @staticmethod
+    def infer_year(month: int, day: int, reference_date: Optional['Date'] = None) -> int:
+        """推断年份"""
+        if reference_date is None:
+            reference_date = Date.today()
+        
+        # 优先使用当前年份
+        try:
+            current_year_date = Date(reference_date.year, month, day)
+            # 如果日期在未来6个月内，使用当前年份
+            if current_year_date >= reference_date and current_year_date.calculate_difference_days(reference_date) <= 180:
+                return reference_date.year
+        except (InvalidDateFormatError, InvalidDateValueError):
+            pass
+        
+        # 否则使用下一年
+        return reference_date.year + 1
+    
+    @staticmethod
+    def infer_day(year: int, month: int) -> int:
+        """推断日期（默认为月初）"""
+        return 1
+    
+    @staticmethod
+    def parse_smart(date_input: str, reference_date: Optional['Date'] = None) -> 'Date':
+        """智能解析日期字符串"""
+        if reference_date is None:
+            reference_date = Date.today()
+        
+        # 移除所有非数字字符
+        numbers = re.findall(r'\d+', date_input)
+        
+        if len(numbers) == 1:
+            # 只有一个数字，可能是日期
+            day = int(numbers[0])
+            if 1 <= day <= 31:
+                year = reference_date.year
+                month = reference_date.month
+                # 如果这个日期已经过去，推到下个月
+                try:
+                    inferred_date = Date(year, month, day)
+                    if inferred_date < reference_date:
+                        inferred_date = inferred_date.add_months(1)
+                    return inferred_date
+                except (InvalidDateFormatError, InvalidDateValueError):
+                    pass
+        
+        elif len(numbers) == 2:
+            # 两个数字，可能是月日
+            month, day = int(numbers[0]), int(numbers[1])
+            if 1 <= month <= 12 and 1 <= day <= 31:
+                year = SmartDateInference.infer_year(month, day, reference_date)
+                return Date(year, month, day)
+        
+        # 其他情况，回退到标准解析
+        return Date(date_input)
+
+
+class PerformanceCache:
+    """性能缓存管理器 (v1.0.9)
+    
+    多级缓存策略，提升重复操作性能
+    """
+    
+    def __init__(self):
+        self._object_cache = {}  # 对象创建缓存
+        self._format_cache = {}  # 格式化缓存
+        self._calculation_cache = {}  # 计算结果缓存
+        self._lock = threading.RLock()
+    
+    def get_or_create_date(self, key: str, factory_func):
+        """获取或创建Date对象"""
+        with self._lock:
+            if key not in self._object_cache:
+                self._object_cache[key] = factory_func()
+            return self._object_cache[key]
+    
+    def get_or_calculate(self, key: str, calculation_func):
+        """获取或计算结果"""
+        with self._lock:
+            if key not in self._calculation_cache:
+                self._calculation_cache[key] = calculation_func()
+            return self._calculation_cache[key]
+    
+    def clear(self):
+        """清空缓存"""
+        with self._lock:
+            self._object_cache.clear()
+            self._format_cache.clear()
+            self._calculation_cache.clear()
+
+
+# 全局性能缓存实例
+_performance_cache = PerformanceCache()
+
+
+class InvalidDateValueError(DateError):
+    """无效日期值异常"""
+    pass
+
+
 class DateLogger:
     """企业级日志记录器
     
@@ -74,19 +233,35 @@ class DateLogger:
 
 
 class Date:
-    """企业级日期处理类
+    """企业级日期处理类 v1.0.9
     
     提供智能格式记忆、统一API命名和完整的日期处理功能。
     支持YYYY、YYYYMM、YYYYMMDD等多种输入格式，并在运算中
     自动保持原始格式。
     
+    v1.0.8 功能:
+    - 农历日期支持 (from_lunar, to_lunar, format_lunar等)
+    - 多语言配置 (中简、中繁、日、英四种语言)
+    - 全局语言设置，一次配置全局生效
+    
+    v1.0.9 新增功能:
+    - 智能日期推断 (smart_parse, infer_date等)
+    - 异步批量处理 (async_batch_create, async_batch_format等)
+    - 高级业务规则 (扩展的业务规则引擎)
+    - 日期范围操作 (DateRange, 交集、并集等)
+    - 性能优化 (多级缓存、内存优化)
+    
     特性:
     ----
-    - 86+个统一命名的API方法
+    - 120+个统一命名的API方法
     - 智能格式记忆和保持
     - 企业级日志记录
+    - 农历与公历互转
+    - 多语言本地化支持
     - 类型安全的日期转换
     - 向后兼容的旧API支持
+    - 异步处理支持
+    - 智能推断和自动修复
     
     Examples:
     ---------
@@ -98,6 +273,22 @@ class Date:
     >>> print(date1.add_months(2))  # 202506
     >>> print(date2.add_days(10))   # 20250425
     >>> 
+    >>> # 农历支持 (v1.0.8)
+    >>> lunar_date = Date.from_lunar(2025, 3, 15)  # 农历2025年三月十五
+    >>> print(lunar_date.to_lunar().format_chinese())  # 农历2025年三月十五
+    >>> 
+    >>> # 多语言支持 (v1.0.8)
+    >>> Date.set_language('en_US')  # 设置全局语言为英语
+    >>> print(date2.format_localized())  # 04/15/2025
+    >>> print(date2.format_weekday_localized())  # Tuesday
+    >>> 
+    >>> # 智能推断 (v1.0.9)
+    >>> smart_date = Date.smart_parse('15')  # 智能推断为本月15号
+    >>> range_obj = DateRange(Date('20250101'), Date('20250131'))
+    >>> print(range_obj.days_count())  # 31
+    >>> 
+    >>> # 异步批量处理 (v1.0.9)
+    >>> dates = await Date.async_batch_create(['20250101', '20250102'])
     >>> # 统一API命名
     >>> date = Date('20250415')
     >>> print(date.format_iso())         # 2025-04-15
@@ -113,7 +304,7 @@ class Date:
         当日期值超出有效范围时抛出
     """
     
-    __slots__ = ('year', 'month', 'day', '_input_format')
+    __slots__ = ('year', 'month', 'day', '_input_format', '_cache_key')
     
     # 类级别的日志记录器
     _logger = DateLogger()
@@ -136,6 +327,7 @@ class Date:
         self.month: int = 1  
         self.day: int = 1
         self._input_format: str = 'iso'  # 默认ISO格式
+        self._cache_key: Optional[str] = None  # 缓存键(v1.0.9)
         
         # 根据参数类型进行初始化
         if len(args) == 1 and not kwargs:
@@ -157,8 +349,15 @@ class Date:
         else:
             raise InvalidDateValueError("无效的参数组合")
         
+        # 生成缓存键 (v1.0.9)
+        self._generate_cache_key()
+        
         self._logger.info(f"创建Date对象: {self.year}-{self.month:02d}-{self.day:02d}, 格式: {self._input_format}")
     
+    def _generate_cache_key(self):
+        """生成缓存键 (v1.0.9)"""
+        self._cache_key = f"{self.year}-{self.month:02d}-{self.day:02d}-{self._input_format}"
+    
     def _init_from_string(self, date_string: str):
         """从字符串初始化"""
         # 移除分隔符并清理字符串
@@ -310,6 +509,137 @@ class Date:
         """创建今日Date对象"""
         return cls(datetime.date.today())
     
+    @classmethod
+    def smart_parse(cls, date_input: str, reference_date: Optional['Date'] = None) -> 'Date':
+        """智能解析日期字符串 (v1.0.9)
+        
+        自动推断不完整的日期信息，支持多种模糊输入格式
+        
+        Args:
+            date_input: 日期输入字符串，支持模糊格式如 '15', '3-15', '明天' 等
+            reference_date: 参考日期，默认为今天
+            
+        Returns:
+            推断后的Date对象
+            
+        Examples:
+            >>> Date.smart_parse('15')      # 本月15号
+            >>> Date.smart_parse('3-15')    # 3月15号(智能推断年份)
+            >>> Date.smart_parse('下月15')   # 下个月15号
+        """
+        return SmartDateInference.parse_smart(date_input, reference_date)
+    
+    @classmethod
+    def infer_date(cls, year: Optional[int] = None, month: Optional[int] = None, 
+                   day: Optional[int] = None, reference_date: Optional['Date'] = None) -> 'Date':
+        """智能推断日期 (v1.0.9)
+        
+        根据提供的部分日期信息，智能推断完整日期
+        
+        Args:
+            year: 年份（可选）
+            month: 月份（可选）
+            day: 日期（可选）
+            reference_date: 参考日期，默认为今天
+            
+        Returns:
+            推断后的Date对象
+        """
+        if reference_date is None:
+            reference_date = cls.today()
+        
+        # 智能推断缺失信息
+        if year is None:
+            if month is not None and day is not None:
+                year = SmartDateInference.infer_year(month, day, reference_date)
+            else:
+                year = reference_date.year
+        
+        if month is None:
+            month = reference_date.month
+            
+        if day is None:
+            day = SmartDateInference.infer_day(year, month)
+        
+        return cls(year, month, day)
+    
+    @classmethod
+    def from_lunar(cls, year: int, month: int, day: int, is_leap: bool = False) -> 'Date':
+        """从农历日期创建Date对象 (v1.0.8)
+        
+        Args:
+            year: 农历年份
+            month: 农历月份
+            day: 农历日期
+            is_leap: 是否闰月
+            
+        Returns:
+            对应的公历Date对象
+            
+        Example:
+            >>> date = Date.from_lunar(2025, 3, 15)  # 农历2025年三月十五
+        """
+        lunar_date = LunarDate(year, month, day, is_leap)
+        solar_date = lunar_date.to_solar()
+        return cls(solar_date)
+    
+    @classmethod
+    def from_lunar_string(cls, lunar_string: str) -> 'Date':
+        """从农历字符串创建Date对象 (v1.0.8)
+        
+        支持格式:
+        - "20250315" (农历2025年3月15日)
+        - "2025闰0315" (农历2025年闰3月15日)
+        
+        Args:
+            lunar_string: 农历日期字符串
+            
+        Returns:
+            对应的公历Date对象
+        """
+        # 解析闰月标记
+        is_leap = '闰' in lunar_string
+        clean_string = lunar_string.replace('闰', '')
+        
+        if len(clean_string) != 8:
+            raise InvalidDateFormatError(f"农历日期字符串格式无效: {lunar_string}")
+        
+        year = int(clean_string[:4])
+        month = int(clean_string[4:6])
+        day = int(clean_string[6:8])
+        
+        return cls.from_lunar(year, month, day, is_leap)
+    
+    @classmethod
+    def set_language(cls, language_code: str) -> None:
+        """设置全局语言 (v1.0.8)
+        
+        一次设置，全局生效。支持中简、中繁、日、英四种语言。
+        
+        Args:
+            language_code: 语言代码
+                - 'zh_CN': 中文简体
+                - 'zh_TW': 中文繁体  
+                - 'ja_JP': 日语
+                - 'en_US': 英语
+                
+        Example:
+            >>> Date.set_language('en_US')  # 设置为英语
+            >>> Date.set_language('zh_TW')  # 设置为繁体中文
+        """
+        Language.set_global_language(language_code)
+        cls._logger.info(f"全局语言已设置为: {language_code}")
+    
+    @classmethod
+    def get_language(cls) -> str:
+        """获取当前全局语言设置 (v1.0.8)"""
+        return Language.get_global_language()
+    
+    @classmethod
+    def get_supported_languages(cls) -> Dict[str, str]:
+        """获取支持的语言列表 (v1.0.8)"""
+        return Language.get_supported_languages()
+    
     @classmethod
     def date_range(cls, start: Union[str, 'Date'], end: Union[str, 'Date'], 
                    step: int = 1) -> List['Date']:
@@ -430,6 +760,36 @@ class Date:
             dt = dt - datetime.timedelta(hours=timezone_offset)
         return dt.timestamp()
     
+    def to_lunar(self) -> LunarDate:
+        """转为农历日期对象 (v1.0.8)
+        
+        Returns:
+            对应的农历日期对象
+            
+        Example:
+            >>> date = Date('20250415')
+            >>> lunar = date.to_lunar()
+            >>> print(lunar.format_chinese())  # 农历2025年三月十八
+        """
+        return LunarDate.from_solar(self.to_date_object())
+    
+    def to_lunar_string(self, compact: bool = True) -> str:
+        """转为农历字符串 (v1.0.8)
+        
+        Args:
+            compact: 是否使用紧凑格式
+            
+        Returns:
+            农历日期字符串
+            
+        Example:
+            >>> date = Date('20250415')
+            >>> print(date.to_lunar_string())  # 20250318
+            >>> print(date.to_lunar_string(False))  # 农历2025年三月十八
+        """
+        lunar = self.to_lunar()
+        return lunar.format_compact() if compact else lunar.format_chinese()
+    
     def to_json(self, include_metadata: bool = True) -> str:
         """转为JSON字符串
         
@@ -454,7 +814,7 @@ class Date:
                 'weekday': self.get_weekday(),
                 'is_weekend': self.is_weekend(),
                 'quarter': self.get_quarter(),
-                'version': '1.0.7'
+                'version': '1.0.9'
             })
         
         return json.dumps(data, ensure_ascii=False)
@@ -628,6 +988,155 @@ class Date:
             else:
                 return f"{abs(diff_days)} days ago"
     
+    def format_localized(self, format_type: str = 'full', language_code: Optional[str] = None) -> str:
+        """多语言本地化格式 (v1.0.8)
+        
+        Args:
+            format_type: 格式类型 (full, short, year_month, month_day)
+            language_code: 语言代码，None时使用全局设置
+            
+        Returns:
+            本地化格式的日期字符串
+            
+        Example:
+            >>> Date.set_language('en_US')
+            >>> date = Date('20250415')
+            >>> print(date.format_localized())  # 04/15/2025
+            >>> print(date.format_localized('short'))  # 04/15/2025
+        """
+        return Language.format_date(self.year, self.month, self.day, format_type, language_code)
+    
+    def format_weekday_localized(self, short: bool = False, language_code: Optional[str] = None) -> str:
+        """多语言星期几格式 (v1.0.8)
+        
+        Args:
+            short: 是否使用短名称
+            language_code: 语言代码，None时使用全局设置
+            
+        Returns:
+            本地化的星期几名称
+            
+        Example:
+            >>> Date.set_language('ja_JP')
+            >>> date = Date('20250415')  # 星期二
+            >>> print(date.format_weekday_localized())  # 火曜日
+            >>> print(date.format_weekday_localized(short=True))  # 火
+        """
+        weekday_index = self.get_weekday()
+        return Language.get_weekday_name(weekday_index, short, language_code)
+    
+    def format_month_localized(self, short: bool = False, language_code: Optional[str] = None) -> str:
+        """多语言月份格式 (v1.0.8)
+        
+        Args:
+            short: 是否使用短名称
+            language_code: 语言代码，None时使用全局设置
+            
+        Returns:
+            本地化的月份名称
+        """
+        return Language.get_month_name(self.month, short, language_code)
+    
+    def format_quarter_localized(self, short: bool = False, language_code: Optional[str] = None) -> str:
+        """多语言季度格式 (v1.0.8)
+        
+        Args:
+            short: 是否使用短名称  
+            language_code: 语言代码，None时使用全局设置
+            
+        Returns:
+            本地化的季度名称
+        """
+        quarter = self.get_quarter()
+        return Language.get_quarter_name(quarter, short, language_code)
+    
+    def format_relative_localized(self, reference_date: Optional['Date'] = None, 
+                                 language_code: Optional[str] = None) -> str:
+        """多语言相对时间格式 (v1.0.8)
+        
+        Args:
+            reference_date: 参考日期，None时使用今天
+            language_code: 语言代码，None时使用全局设置
+            
+        Returns:
+            本地化的相对时间描述
+            
+        Example:
+            >>> Date.set_language('en_US')
+            >>> today = Date.today()
+            >>> tomorrow = today.add_days(1)
+            >>> print(tomorrow.format_relative_localized())  # tomorrow
+        """
+        if reference_date is None:
+            reference_date = Date.today()
+        
+        diff_days = reference_date.calculate_difference_days(self)
+        
+        if diff_days == 0:
+            return Language.format_relative_time('today', language_code=language_code)
+        elif diff_days == 1:
+            return Language.format_relative_time('tomorrow', language_code=language_code)
+        elif diff_days == -1:
+            return Language.format_relative_time('yesterday', language_code=language_code)
+        elif diff_days > 0:
+            if diff_days <= 6:
+                return Language.format_relative_time('days_later', diff_days, language_code)
+            elif diff_days <= 28:
+                weeks = diff_days // 7
+                return Language.format_relative_time('weeks_later', weeks, language_code)
+            elif diff_days <= 365:
+                months = diff_days // 30
+                return Language.format_relative_time('months_later', months, language_code)
+            else:
+                years = diff_days // 365
+                return Language.format_relative_time('years_later', years, language_code)
+        else:
+            abs_days = abs(diff_days)
+            if abs_days <= 6:
+                return Language.format_relative_time('days_ago', abs_days, language_code)
+            elif abs_days <= 28:
+                weeks = abs_days // 7
+                return Language.format_relative_time('weeks_ago', weeks, language_code)
+            elif abs_days <= 365:
+                months = abs_days // 30
+                return Language.format_relative_time('months_ago', months, language_code)
+            else:
+                years = abs_days // 365
+                return Language.format_relative_time('years_ago', years, language_code)
+    
+    def format_lunar(self, include_year: bool = True, include_zodiac: bool = False,
+                    language_code: Optional[str] = None) -> str:
+        """农历格式化 (v1.0.8)
+        
+        Args:
+            include_year: 是否包含年份
+            include_zodiac: 是否包含生肖
+            language_code: 语言代码，None时使用全局设置
+            
+        Returns:
+            农历日期字符串
+            
+        Example:
+            >>> date = Date('20250415')
+            >>> print(date.format_lunar())  # 农历2025年三月十八
+            >>> print(date.format_lunar(include_zodiac=True))  # 乙巳(蛇)年三月十八
+        """
+        lunar = self.to_lunar()
+        return lunar.format_chinese(include_year, include_zodiac)
+    
+    def format_lunar_compact(self) -> str:
+        """农历紧凑格式 (v1.0.8)
+        
+        Returns:
+            农历紧凑格式字符串
+            
+        Example:
+            >>> date = Date('20250415')
+            >>> print(date.format_lunar_compact())  # 20250318
+        """
+        lunar = self.to_lunar()
+        return lunar.format_compact()
+    
     # =============================================
     # get_* 系列：获取方法
     # =============================================
@@ -755,6 +1264,42 @@ class Date:
         return (self.month in quarter_end_months and 
                 self.day == quarter_end_months[self.month])
     
+    def is_lunar_new_year(self) -> bool:
+        """是否为农历新年 (v1.0.8)
+        
+        Returns:
+            是否为农历正月初一
+        """
+        lunar = self.to_lunar()
+        return lunar.month == 1 and lunar.day == 1 and not lunar.is_leap
+    
+    def is_lunar_month_start(self) -> bool:
+        """是否为农历月初 (v1.0.8)
+        
+        Returns:
+            是否为农历月初一
+        """
+        lunar = self.to_lunar()
+        return lunar.day == 1
+    
+    def is_lunar_month_mid(self) -> bool:
+        """是否为农历月中 (v1.0.8)
+        
+        Returns:
+            是否为农历十五
+        """
+        lunar = self.to_lunar()
+        return lunar.day == 15
+    
+    def is_lunar_leap_month(self) -> bool:
+        """是否在农历闰月 (v1.0.8)
+        
+        Returns:
+            是否为农历闰月
+        """
+        lunar = self.to_lunar()
+        return lunar.is_leap
+    
     def is_holiday(self, country: str = 'CN') -> bool:
         """是否为节假日（增强版实现）
         
@@ -1012,6 +1557,326 @@ class Date:
         """
         return [date.add_days(days) for date in dates]
     
+    # =============================================
+    # 异步批量处理方法 (v1.0.9)
+    # =============================================
+    
+    @classmethod
+    async def async_batch_create(cls, date_strings: List[str]) -> List['Date']:
+        """异步批量创建Date对象 (v1.0.9)
+        
+        适用于大量日期对象的创建，使用异步处理提升性能
+        
+        Args:
+            date_strings: 日期字符串列表
+            
+        Returns:
+            Date对象列表
+        """
+        async def create_single(date_str: str) -> 'Date':
+            return cls(date_str)
+        
+        tasks = [create_single(date_str) for date_str in date_strings]
+        return await asyncio.gather(*tasks)
+    
+    @classmethod
+    async def async_batch_format(cls, dates: List['Date'], format_type: str = 'iso') -> List[str]:
+        """异步批量格式化日期 (v1.0.9)
+        
+        Args:
+            dates: Date对象列表
+            format_type: 格式类型
+            
+        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())
+        
+        async def format_single(date: 'Date') -> str:
+            return format_func(date)
+        
+        tasks = [format_single(date) for date in dates]
+        return await asyncio.gather(*tasks)
+    
+    @classmethod
+    async def async_batch_process(cls, dates: List['Date'], operation: str, **kwargs) -> List['Date']:
+        """异步批量处理操作 (v1.0.9)
+        
+        Args:
+            dates: Date对象列表
+            operation: 操作类型 ('add_days', 'add_months', 'add_years')
+            **kwargs: 操作参数
+            
+        Returns:
+            处理后的Date对象列表
+        """
+        async def process_single(date: 'Date') -> 'Date':
+            if operation == 'add_days':
+                return date.add_days(kwargs.get('days', 0))
+            elif operation == 'add_months':
+                return date.add_months(kwargs.get('months', 0))
+            elif operation == 'add_years':
+                return date.add_years(kwargs.get('years', 0))
+            else:
+                return date
+        
+        tasks = [process_single(date) for date in dates]
+        return await asyncio.gather(*tasks)
+    
+    # =============================================
+    # 日期范围操作方法 (v1.0.9)
+    # =============================================
+    
+    @classmethod
+    def create_range(cls, start_date: Union[str, 'Date'], end_date: Union[str, 'Date']) -> 'DateRange':
+        """创建日期范围 (v1.0.9)
+        
+        Args:
+            start_date: 开始日期
+            end_date: 结束日期
+            
+        Returns:
+            DateRange对象
+        """
+        if isinstance(start_date, str):
+            start_date = cls(start_date)
+        if isinstance(end_date, str):
+            end_date = cls(end_date)
+        
+        return DateRange(start_date, end_date)
+    
+    def in_range(self, start_date: 'Date', end_date: 'Date') -> bool:
+        """检查是否在日期范围内 (v1.0.9)
+        
+        Args:
+            start_date: 开始日期
+            end_date: 结束日期
+            
+        Returns:
+            是否在范围内
+        """
+        return start_date <= self <= end_date
+    
+    @classmethod
+    def generate_range(cls, start_date: Union[str, 'Date'], days: int, 
+                      step: int = 1, include_weekends: bool = True) -> List['Date']:
+        """生成日期范围序列 (v1.0.9)
+        
+        Args:
+            start_date: 开始日期
+            days: 天数
+            step: 步长
+            include_weekends: 是否包含周末
+            
+        Returns:
+            日期列表
+        """
+        if isinstance(start_date, str):
+            start_date = cls(start_date)
+        
+        dates = []
+        current = start_date
+        
+        for _ in range(days):
+            if include_weekends or not current.is_weekend():
+                dates.append(current)
+            current = current.add_days(step)
+        
+        return dates
+    
+    @classmethod
+    def date_ranges_intersect(cls, range1: 'DateRange', range2: 'DateRange') -> bool:
+        """检查两个日期范围是否有交集 (v1.0.9)"""
+        return range1.intersect(range2) is not None
+    
+    @classmethod
+    def merge_date_ranges(cls, ranges: List['DateRange']) -> List['DateRange']:
+        """合并重叠的日期范围 (v1.0.9)
+        
+        Args:
+            ranges: 日期范围列表
+            
+        Returns:
+            合并后的日期范围列表
+        """
+        if not ranges:
+            return []
+        
+        # 按开始日期排序
+        sorted_ranges = sorted(ranges, key=lambda r: r.start)
+        merged = [sorted_ranges[0]]
+        
+        for current_range in sorted_ranges[1:]:
+            last_range = merged[-1]
+            
+            # 检查是否重叠或相邻
+            if current_range.start <= last_range.end.add_days(1):
+                # 合并范围
+                merged[-1] = DateRange(last_range.start, max(last_range.end, current_range.end))
+            else:
+                # 不重叠，添加新范围
+                merged.append(current_range)
+        
+        return merged
+    
+    # =============================================
+    # 数据导入导出方法 (v1.0.9)
+    # =============================================
+    
+    @classmethod
+    def from_csv(cls, file_path: str, date_column: str = 'date', 
+                 format_hint: Optional[str] = None) -> List['Date']:
+        """从CSV文件导入日期 (v1.0.9)
+        
+        Args:
+            file_path: CSV文件路径
+            date_column: 日期列名
+            format_hint: 日期格式提示
+            
+        Returns:
+            Date对象列表
+        """
+        dates = []
+        
+        with open(file_path, 'r', encoding='utf-8') as file:
+            reader = csv.DictReader(file)
+            for row in reader:
+                if date_column in row:
+                    try:
+                        date_str = row[date_column].strip()
+                        if date_str:
+                            dates.append(cls(date_str))
+                    except (InvalidDateFormatError, InvalidDateValueError) as e:
+                        cls._logger.warning(f"跳过无效日期: {row[date_column]} - {e}")
+        
+        return dates
+    
+    @classmethod
+    def to_csv(cls, dates: List['Date'], file_path: str, 
+               include_metadata: bool = False, format_type: str = 'iso') -> None:
+        """导出日期到CSV文件 (v1.0.9)
+        
+        Args:
+            dates: Date对象列表
+            file_path: 输出文件路径
+            include_metadata: 是否包含元数据
+            format_type: 日期格式类型
+        """
+        with open(file_path, 'w', newline='', encoding='utf-8') as file:
+            fieldnames = ['date']
+            if include_metadata:
+                fieldnames.extend(['weekday', 'quarter', 'is_weekend', 'format'])
+            
+            writer = csv.DictWriter(file, fieldnames=fieldnames)
+            writer.writeheader()
+            
+            for date in dates:
+                row = {'date': getattr(date, f'format_{format_type}')()}
+                if include_metadata:
+                    row.update({
+                        'weekday': date.get_weekday(),
+                        'quarter': date.get_quarter(),
+                        'is_weekend': date.is_weekend(),
+                        'format': date._input_format
+                    })
+                writer.writerow(row)
+    
+    @classmethod
+    def from_json_file(cls, file_path: str) -> List['Date']:
+        """从JSON文件导入日期 (v1.0.9)
+        
+        Args:
+            file_path: JSON文件路径
+            
+        Returns:
+            Date对象列表
+        """
+        with open(file_path, 'r', encoding='utf-8') as file:
+            data = json.load(file)
+        
+        dates = []
+        if isinstance(data, list):
+            for item in data:
+                try:
+                    if isinstance(item, str):
+                        dates.append(cls(item))
+                    elif isinstance(item, dict):
+                        # 支持to_dict()格式的JSON
+                        if 'year' in item and 'month' in item and 'day' in item:
+                            dates.append(cls(item['year'], item['month'], item['day']))
+                        elif 'date' in item:
+                            dates.append(cls(item['date']))
+                        elif 'iso_string' in item:
+                            dates.append(cls(item['iso_string']))
+                        elif 'compact_string' in item:
+                            dates.append(cls(item['compact_string']))
+                except (InvalidDateFormatError, InvalidDateValueError) as e:
+                    cls._logger.warning(f"跳过无效日期数据: {item} - {e}")
+        
+        return dates
+    
+    @classmethod
+    def to_json_file(cls, dates: List['Date'], file_path: str, 
+                     include_metadata: bool = False) -> None:
+        """导出日期到JSON文件 (v1.0.9)
+        
+        Args:
+            dates: Date对象列表
+            file_path: 输出文件路径
+            include_metadata: 是否包含元数据
+        """
+        data = [date.to_dict(include_metadata) for date in dates]
+        
+        with open(file_path, 'w', encoding='utf-8') as file:
+            json.dump(data, file, ensure_ascii=False, indent=2)
+    
+    # =============================================
+    # 性能优化方法 (v1.0.9)
+    # =============================================
+    
+    @classmethod
+    def clear_cache(cls):
+        """清空全局缓存 (v1.0.9)"""
+        _performance_cache.clear()
+    
+    @classmethod
+    def get_cache_stats(cls) -> Dict[str, Any]:
+        """获取缓存统计信息 (v1.0.9)"""
+        return {
+            'object_cache_size': len(_performance_cache._object_cache),
+            'format_cache_size': len(_performance_cache._format_cache),
+            'calculation_cache_size': len(_performance_cache._calculation_cache)
+        }
+    
+    def _optimized_format(self, format_type: str) -> str:
+        """优化的格式化方法 (v1.0.9)"""
+        cache_key = f"{self._cache_key}-{format_type}"
+        
+        def format_func():
+            if format_type == 'iso':
+                return self.format_iso()
+            elif format_type == 'chinese':
+                return self.format_chinese()
+            elif format_type == 'compact':
+                return self.format_compact()
+            else:
+                return self.format_default()
+        
+        return _performance_cache.get_or_calculate(cache_key, format_func)
+    
+    def get_cache_key(self) -> str:
+        """获取对象的缓存键 (v1.0.9)"""
+        return self._cache_key
+    
     def apply_business_rule(self, rule: str, **kwargs) -> 'Date':
         """应用业务规则
         
@@ -1088,6 +1953,58 @@ class Date:
     def __hash__(self) -> int:
         return hash(self.to_tuple())
     
+    def compare_lunar(self, other: 'Date') -> int:
+        """农历日期比较 (v1.0.8)
+        
+        Args:
+            other: 另一个Date对象
+            
+        Returns:
+            -1: self < other, 0: self == other, 1: self > other
+            
+        Example:
+            >>> date1 = Date.from_lunar(2025, 1, 1)  # 农历正月初一
+            >>> date2 = Date.from_lunar(2025, 1, 15) # 农历正月十五
+            >>> print(date1.compare_lunar(date2))    # -1
+        """
+        lunar_self = self.to_lunar()
+        lunar_other = other.to_lunar()
+        
+        if lunar_self < lunar_other:
+            return -1
+        elif lunar_self > lunar_other:
+            return 1
+        else:
+            return 0
+    
+    def is_same_lunar_month(self, other: 'Date') -> bool:
+        """是否同一农历月份 (v1.0.8)
+        
+        Args:
+            other: 另一个Date对象
+            
+        Returns:
+            是否为同一农历月份
+        """
+        lunar_self = self.to_lunar()
+        lunar_other = other.to_lunar()
+        return (lunar_self.year == lunar_other.year and
+                lunar_self.month == lunar_other.month and
+                lunar_self.is_leap == lunar_other.is_leap)
+    
+    def is_same_lunar_day(self, other: 'Date') -> bool:
+        """是否同一农历日期 (v1.0.8)
+        
+        Args:
+            other: 另一个Date对象
+            
+        Returns:
+            是否为同一农历日期
+        """
+        lunar_self = self.to_lunar()
+        lunar_other = other.to_lunar()
+        return lunar_self == lunar_other
+    
     # =============================================
     # 向后兼容的旧API
     # =============================================