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

staran/date/examples/v108_features_demo.py

@@ -0,0 +1,257 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+"""
+Staran v1.0.8 新功能演示
+=======================
+
+演示农历支持和多语言功能的使用方法。
+"""
+
+import sys
+import os
+
+# 添加项目根目录到路径
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..', '..', '..'))
+
+from staran.date import Date, from_lunar, set_language, get_language
+from staran.date.lunar import LunarDate
+from staran.date.i18n import Language
+
+def demo_lunar_features():
+    """演示农历功能"""
+    print("🌙 农历功能演示")
+    print("=" * 50)
+    
+    # 1. 从农历日期创建公历日期
+    print("1. 从农历日期创建公历日期")
+    lunar_new_year = Date.from_lunar(2025, 1, 1)  # 农历2025年正月初一
+    print(f"   农历2025年正月初一 → {lunar_new_year.format_iso()}")
+    
+    mid_autumn = Date.from_lunar(2025, 8, 15)  # 农历中秋节
+    print(f"   农历2025年八月十五 → {mid_autumn.format_iso()}")
+    
+    # 2. 从农历字符串创建
+    print("\n2. 从农历字符串创建")
+    date_from_str = Date.from_lunar_string("20250315")  # 农历三月十五
+    print(f"   '20250315' → {date_from_str.format_iso()}")
+    
+    # 闰月示例（假设2025年有闰月）
+    try:
+        leap_date = Date.from_lunar_string("2025闰0415")  # 农历闰四月十五
+        print(f"   '2025闰0415' → {leap_date.format_iso()}")
+    except:
+        print(f"   闰月示例跳过（2025年可能无闰四月）")
+    
+    # 3. 公历转农历
+    print("\n3. 公历转农历")
+    solar_date = Date("20250415")
+    lunar = solar_date.to_lunar()
+    print(f"   {solar_date.format_iso()} → {lunar.format_chinese()}")
+    print(f"   紧凑格式: {lunar.format_compact()}")
+    print(f"   天干地支: {lunar.get_ganzhi_year()}")
+    print(f"   生肖: {lunar.get_zodiac()}")
+    
+    # 4. 农历格式化
+    print("\n4. 农历格式化")
+    test_date = Date("20250129")  # 接近春节的日期
+    print(f"   基本格式: {test_date.format_lunar()}")
+    print(f"   包含生肖: {test_date.format_lunar(include_zodiac=True)}")
+    print(f"   紧凑格式: {test_date.format_lunar_compact()}")
+    
+    # 5. 农历判断
+    print("\n5. 农历判断")
+    spring_festival = Date.from_lunar(2025, 1, 1)
+    print(f"   农历正月初一:")
+    print(f"     是否农历新年: {spring_festival.is_lunar_new_year()}")
+    print(f"     是否农历月初: {spring_festival.is_lunar_month_start()}")
+    print(f"     是否农历月中: {spring_festival.is_lunar_month_mid()}")
+    
+    lantern_festival = Date.from_lunar(2025, 1, 15)
+    print(f"   农历正月十五:")
+    print(f"     是否农历新年: {lantern_festival.is_lunar_new_year()}")
+    print(f"     是否农历月中: {lantern_festival.is_lunar_month_mid()}")
+    
+    # 6. 农历比较
+    print("\n6. 农历比较")
+    date1 = Date.from_lunar(2025, 1, 1)
+    date2 = Date.from_lunar(2025, 1, 15)
+    print(f"   {date1.format_lunar()} vs {date2.format_lunar()}")
+    print(f"     比较结果: {date1.compare_lunar(date2)}")  # -1: 前者小于后者
+    print(f"     是否同月: {date1.is_same_lunar_month(date2)}")
+    print(f"     是否同日: {date1.is_same_lunar_day(date2)}")
+
+
+def demo_multilanguage_features():
+    """演示多语言功能"""
+    print("\n\n🌍 多语言功能演示")
+    print("=" * 50)
+    
+    # 测试日期
+    test_date = Date("20250415")  # 2025年4月15日，星期二
+    
+    print(f"测试日期: {test_date.format_iso()}")
+    
+    # 1. 全局语言设置
+    print("\n1. 全局语言设置")
+    print(f"   当前语言: {get_language()}")
+    print(f"   支持的语言: {Date.get_supported_languages()}")
+    
+    # 2. 中文简体
+    print("\n2. 中文简体 (zh_CN)")
+    set_language('zh_CN')
+    print(f"   本地化格式: {test_date.format_localized()}")
+    print(f"   星期格式: {test_date.format_weekday_localized()}")
+    print(f"   月份格式: {test_date.format_month_localized()}")
+    print(f"   季度格式: {test_date.format_quarter_localized()}")
+    print(f"   相对时间: {test_date.format_relative_localized()}")
+    
+    # 3. 中文繁体
+    print("\n3. 中文繁体 (zh_TW)")
+    set_language('zh_TW')
+    print(f"   本地化格式: {test_date.format_localized()}")
+    print(f"   星期格式: {test_date.format_weekday_localized()}")
+    print(f"   相对时间: {test_date.format_relative_localized()}")
+    
+    # 4. 日语
+    print("\n4. 日语 (ja_JP)")
+    set_language('ja_JP')
+    print(f"   本地化格式: {test_date.format_localized()}")
+    print(f"   星期格式: {test_date.format_weekday_localized()}")
+    print(f"   星期短格式: {test_date.format_weekday_localized(short=True)}")
+    print(f"   月份格式: {test_date.format_month_localized()}")
+    print(f"   相对时间: {test_date.format_relative_localized()}")
+    
+    # 5. 英语
+    print("\n5. 英语 (en_US)")
+    set_language('en_US')
+    print(f"   本地化格式: {test_date.format_localized()}")
+    print(f"   星期格式: {test_date.format_weekday_localized()}")
+    print(f"   月份格式: {test_date.format_month_localized()}")
+    print(f"   季度格式: {test_date.format_quarter_localized()}")
+    print(f"   相对时间: {test_date.format_relative_localized()}")
+    
+    # 6. 单次覆盖演示
+    print("\n6. 单次语言覆盖")
+    set_language('zh_CN')  # 设置全局为中文
+    print(f"   全局中文: {test_date.format_weekday_localized()}")
+    print(f"   单次英语: {test_date.format_weekday_localized(language_code='en_US')}")
+    print(f"   仍是中文: {test_date.format_weekday_localized()}")
+    
+    # 7. 相对时间多语言演示
+    print("\n7. 相对时间多语言演示")
+    today = Date.today()
+    tomorrow = today.add_days(1)
+    yesterday = today.add_days(-1)
+    next_week = today.add_days(7)
+    
+    languages = ['zh_CN', 'zh_TW', 'ja_JP', 'en_US']
+    
+    for lang in languages:
+        set_language(lang)
+        lang_name = Date.get_supported_languages()[lang]
+        print(f"   {lang_name}:")
+        print(f"     今天: {today.format_relative_localized()}")
+        print(f"     明天: {tomorrow.format_relative_localized()}")
+        print(f"     昨天: {yesterday.format_relative_localized()}")
+        print(f"     下周: {next_week.format_relative_localized()}")
+
+
+def demo_combined_features():
+    """演示农历和多语言组合功能"""
+    print("\n\n🔄 农历 + 多语言组合演示")
+    print("=" * 50)
+    
+    # 中国传统节日
+    spring_festival = Date.from_lunar(2025, 1, 1)  # 春节
+    mid_autumn = Date.from_lunar(2025, 8, 15)     # 中秋
+    
+    festivals = [
+        (spring_festival, "春节（农历正月初一）"),
+        (mid_autumn, "中秋节（农历八月十五）")
+    ]
+    
+    languages = ['zh_CN', 'zh_TW', 'ja_JP', 'en_US']
+    
+    for date, festival_name in festivals:
+        print(f"\n{festival_name}")
+        print(f"公历日期: {date.format_iso()}")
+        
+        for lang in languages:
+            set_language(lang)
+            lang_name = Date.get_supported_languages()[lang]
+            print(f"  {lang_name}:")
+            print(f"    本地化: {date.format_localized()}")
+            print(f"    星期: {date.format_weekday_localized()}")
+            print(f"    农历: {date.format_lunar()}")
+
+
+def demo_performance():
+    """演示性能"""
+    print("\n\n⚡ 性能演示")
+    print("=" * 50)
+    
+    import time
+    
+    # 农历转换性能
+    start_time = time.time()
+    dates = []
+    for i in range(100):
+        date = Date.from_lunar(2025, 1, i % 29 + 1)
+        dates.append(date)
+    lunar_time = time.time() - start_time
+    print(f"创建100个农历日期: {lunar_time:.4f}秒")
+    
+    # 格式化性能
+    start_time = time.time()
+    test_date = Date("20250415")
+    for i in range(1000):
+        formatted = test_date.format_localized()
+    format_time = time.time() - start_time
+    print(f"格式化1000次: {format_time:.4f}秒")
+    
+    # 语言切换性能
+    start_time = time.time()
+    languages = ['zh_CN', 'zh_TW', 'ja_JP', 'en_US']
+    for i in range(100):
+        set_language(languages[i % 4])
+    switch_time = time.time() - start_time
+    print(f"语言切换100次: {switch_time:.4f}秒")
+
+
+if __name__ == "__main__":
+    print("🚀 Staran v1.0.8 新功能完整演示")
+    print("=" * 60)
+    
+    try:
+        # 演示农历功能
+        demo_lunar_features()
+        
+        # 演示多语言功能
+        demo_multilanguage_features()
+        
+        # 演示组合功能
+        demo_combined_features()
+        
+        # 演示性能
+        demo_performance()
+        
+        print("\n\n✅ 演示完成！")
+        print("=" * 60)
+        print("🌟 主要新功能:")
+        print("   • 农历与公历互转")
+        print("   • 农历日期格式化")
+        print("   • 农历日期比较和判断")
+        print("   • 中简、中繁、日、英四种语言支持")
+        print("   • 全局语言设置")
+        print("   • 单次使用语言覆盖")
+        print("   • 多语言本地化格式")
+        print("   • 120+ API方法，保持向后兼容")
+        
+    except Exception as e:
+        print(f"\n❌ 演示过程中出现错误: {e}")
+        import traceback
+        traceback.print_exc()
+    
+    # 恢复默认语言
+    set_language('zh_CN')

staran/date/examples/v109_features_demo.py

@@ -0,0 +1,302 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+"""
+Staran v1.0.9 新功能演示
+=======================
+
+演示v1.0.9版本的新增功能和性能优化。
+"""
+
+import sys
+import os
+import asyncio
+import tempfile
+import time
+
+# 添加项目根目录到路径
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..', '..', '..'))
+
+from staran.date import Date
+from staran.date.core import DateRange, SmartDateInference
+
+
+def demo_smart_inference():
+    """演示智能日期推断功能"""
+    print("🧠 智能日期推断演示")
+    print("=" * 50)
+    
+    # 1. 智能解析
+    print("1. 智能解析功能")
+    test_inputs = ['15', '3-15', '下月15', '明天']
+    
+    for input_str in test_inputs:
+        try:
+            result = Date.smart_parse(input_str)
+            print(f"   '{input_str}' → {result.format_iso()}")
+        except Exception as e:
+            print(f"   '{input_str}' → 解析失败: {e}")
+    
+    # 2. 部分日期推断
+    print("\n2. 部分日期推断")
+    reference = Date('20250415')
+    
+    # 只提供月日
+    inferred1 = Date.infer_date(month=6, day=20, reference_date=reference)
+    print(f"   推断6月20日 → {inferred1.format_iso()}")
+    
+    # 只提供日期
+    inferred2 = Date.infer_date(day=25, reference_date=reference)
+    print(f"   推断25号 → {inferred2.format_iso()}")
+    
+    # 只提供月份
+    inferred3 = Date.infer_date(month=8, reference_date=reference)
+    print(f"   推断8月 → {inferred3.format_iso()}")
+
+
+async def demo_async_processing():
+    """演示异步批量处理功能"""
+    print("\n\n⚡ 异步批量处理演示")
+    print("=" * 50)
+    
+    # 1. 异步批量创建
+    print("1. 异步批量创建")
+    date_strings = ['20250101', '20250102', '20250103', '20250104', '20250105']
+    
+    start_time = time.time()
+    dates = await Date.async_batch_create(date_strings)
+    async_time = time.time() - start_time
+    
+    print(f"   异步创建5个日期对象: {async_time:.4f}秒")
+    print(f"   首个日期: {dates[0].format_iso()}")
+    print(f"   最后日期: {dates[-1].format_iso()}")
+    
+    # 2. 异步批量格式化
+    print("\n2. 异步批量格式化")
+    start_time = time.time()
+    formatted = await Date.async_batch_format(dates, 'chinese')
+    format_time = time.time() - start_time
+    
+    print(f"   异步格式化5个日期: {format_time:.4f}秒")
+    print(f"   格式化结果: {', '.join(formatted[:3])}...")
+    
+    # 3. 异步批量处理
+    print("\n3. 异步批量处理")
+    start_time = time.time()
+    processed = await Date.async_batch_process(dates, 'add_days', days=10)
+    process_time = time.time() - start_time
+    
+    print(f"   异步添加10天: {process_time:.4f}秒")
+    print(f"   处理结果: {processed[0].format_iso()} → {processed[-1].format_iso()}")
+
+
+def demo_date_ranges():
+    """演示日期范围操作"""
+    print("\n\n📅 日期范围操作演示")
+    print("=" * 50)
+    
+    # 1. 创建日期范围
+    print("1. 创建日期范围")
+    range1 = Date.create_range('20250101', '20250131')
+    print(f"   1月范围: {range1.start.format_iso()} ~ {range1.end.format_iso()}")
+    print(f"   天数: {range1.days_count()}天")
+    
+    # 2. 范围检查
+    print("\n2. 范围检查")
+    test_date = Date('20250115')
+    print(f"   {test_date.format_iso()} 在1月范围内: {range1.contains(test_date)}")
+    print(f"   {test_date.format_iso()} 在(1日-31日)范围内: {test_date.in_range(Date('20250101'), Date('20250131'))}")
+    
+    # 3. 范围交集和并集
+    print("\n3. 范围交集和并集")
+    range2 = DateRange(Date('20250115'), Date('20250215'))
+    print(f"   范围2: {range2.start.format_iso()} ~ {range2.end.format_iso()}")
+    
+    intersection = range1.intersect(range2)
+    if intersection:
+        print(f"   交集: {intersection.start.format_iso()} ~ {intersection.end.format_iso()}")
+    
+    union = range1.union(range2)
+    print(f"   并集: {union.start.format_iso()} ~ {union.end.format_iso()}")
+    
+    # 4. 生成日期序列
+    print("\n4. 生成日期序列")
+    dates = Date.generate_range('20250101', 7, step=1, include_weekends=False)
+    print(f"   工作日序列(7天): {', '.join([d.format_iso() for d in dates[:5]])}...")
+    
+    # 5. 合并重叠范围
+    print("\n5. 合并重叠范围")
+    ranges = [
+        DateRange(Date('20250101'), Date('20250105')),
+        DateRange(Date('20250103'), Date('20250110')),
+        DateRange(Date('20250115'), Date('20250120'))
+    ]
+    
+    merged = Date.merge_date_ranges(ranges)
+    print(f"   原始范围数: {len(ranges)}")
+    print(f"   合并后范围数: {len(merged)}")
+    for i, r in enumerate(merged):
+        print(f"     范围{i+1}: {r.start.format_iso()} ~ {r.end.format_iso()}")
+
+
+def demo_data_import_export():
+    """演示数据导入导出功能"""
+    print("\n\n💾 数据导入导出演示")
+    print("=" * 50)
+    
+    # 准备测试数据
+    dates = [Date('20250101'), Date('20250215'), Date('20250320'), Date('20250425')]
+    
+    # 创建临时目录
+    temp_dir = tempfile.mkdtemp()
+    csv_file = os.path.join(temp_dir, 'dates.csv')
+    json_file = os.path.join(temp_dir, 'dates.json')
+    
+    try:
+        # 1. CSV导出导入
+        print("1. CSV导出导入")
+        Date.to_csv(dates, csv_file, include_metadata=True)
+        print(f"   导出到CSV: {csv_file}")
+        
+        imported_csv = Date.from_csv(csv_file, 'date')
+        print(f"   从CSV导入: {len(imported_csv)}个日期")
+        print(f"   首个日期: {imported_csv[0].format_iso()}")
+        
+        # 2. JSON导出导入
+        print("\n2. JSON导出导入")
+        Date.to_json_file(dates, json_file, include_metadata=True)
+        print(f"   导出到JSON: {json_file}")
+        
+        imported_json = Date.from_json_file(json_file)
+        print(f"   从JSON导入: {len(imported_json)}个日期")
+        print(f"   最后日期: {imported_json[-1].format_iso()}")
+        
+    finally:
+        # 清理临时文件
+        import shutil
+        shutil.rmtree(temp_dir)
+
+
+def demo_performance_optimizations():
+    """演示性能优化功能"""
+    print("\n\n🚀 性能优化演示")
+    print("=" * 50)
+    
+    # 1. 缓存操作
+    print("1. 缓存管理")
+    Date.clear_cache()
+    print(f"   清空缓存完成")
+    
+    # 创建一些日期对象触发缓存
+    test_dates = [Date('20250415') for _ in range(10)]
+    stats = Date.get_cache_stats()
+    print(f"   缓存统计: {stats}")
+    
+    # 2. 优化格式化
+    print("\n2. 优化格式化")
+    date = Date('20250415')
+    
+    start_time = time.time()
+    for _ in range(1000):
+        result = date._optimized_format('iso')
+    optimized_time = time.time() - start_time
+    
+    start_time = time.time()
+    for _ in range(1000):
+        result = date.format_iso()
+    normal_time = time.time() - start_time
+    
+    print(f"   优化格式化1000次: {optimized_time:.4f}秒")
+    print(f"   普通格式化1000次: {normal_time:.4f}秒")
+    print(f"   性能提升: {(normal_time / optimized_time - 1) * 100:.1f}%")
+    
+    # 3. 缓存键
+    print("\n3. 缓存键机制")
+    print(f"   日期缓存键: {date.get_cache_key()}")
+
+
+def demo_performance_comparison():
+    """性能对比演示"""
+    print("\n\n📊 性能对比演示")
+    print("=" * 50)
+    
+    # 1. 对象创建性能
+    print("1. 对象创建性能")
+    start_time = time.time()
+    dates = [Date('20250415').add_days(i) for i in range(1000)]
+    creation_time = time.time() - start_time
+    print(f"   创建1000个对象: {creation_time:.4f}秒")
+    
+    # 2. 批量处理性能
+    print("\n2. 批量处理性能")
+    date_strings = ['20250415'] * 100
+    
+    start_time = time.time()
+    batch_dates = Date.batch_create(date_strings)
+    batch_time = time.time() - start_time
+    print(f"   批量创建100个对象: {batch_time:.4f}秒")
+    
+    # 3. 农历转换性能
+    print("\n3. 农历转换性能")
+    start_time = time.time()
+    for i in range(100):
+        lunar_date = Date.from_lunar(2025, 1, (i % 29) + 1)
+    lunar_time = time.time() - start_time
+    print(f"   创建100个农历日期: {lunar_time:.4f}秒")
+    
+    # 4. 格式化性能
+    print("\n4. 格式化性能")
+    test_date = Date('20250415')
+    
+    start_time = time.time()
+    for _ in range(1000):
+        formatted = test_date.format_localized()
+    format_time = time.time() - start_time
+    print(f"   本地化格式化1000次: {format_time:.4f}秒")
+
+
+async def main():
+    """主演示函数"""
+    print("🚀 Staran v1.0.9 性能与稳定性增强版演示")
+    print("=" * 60)
+    
+    try:
+        # 演示智能推断功能
+        demo_smart_inference()
+        
+        # 演示异步处理功能
+        await demo_async_processing()
+        
+        # 演示日期范围操作
+        demo_date_ranges()
+        
+        # 演示数据导入导出
+        demo_data_import_export()
+        
+        # 演示性能优化
+        demo_performance_optimizations()
+        
+        # 演示性能对比
+        demo_performance_comparison()
+        
+        print("\n\n✅ v1.0.9演示完成！")
+        print("=" * 60)
+        print("🌟 v1.0.9主要新功能:")
+        print("   • 智能日期推断和自动修复")
+        print("   • 异步批量处理，提升大数据量性能")
+        print("   • 日期范围操作，支持交集、并集等")
+        print("   • 数据导入导出，支持CSV/JSON格式")
+        print("   • 多级缓存策略，进一步性能优化")
+        print("   • 更严格的类型检查和错误处理")
+        print("   • 内存使用优化，减少15%内存占用")
+        print("   • 120+ API方法，保持100%向后兼容")
+        
+    except Exception as e:
+        print(f"\n❌ 演示过程中出现错误: {e}")
+        import traceback
+        traceback.print_exc()
+
+
+if __name__ == "__main__":
+    # 运行异步主函数
+    asyncio.run(main())