staran 1.0.8__py3-none-any.whl → 1.0.10__py3-none-any.whl

staran/date/examples/v1010_features_demo.py

@@ -0,0 +1,376 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+"""
+Staran v1.0.10 新功能演示
+========================
+
+演示v1.0.10版本的所有新功能：
+- 完整时区支持
+- 日期表达式解析
+- 二十四节气扩展
+- 数据可视化集成
+- REST API接口
+"""
+
+import sys
+import os
+import datetime
+
+# 添加项目根目录到路径
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..', '..', '..'))
+
+from staran.date import (
+    Date, get_version_info, get_feature_status, parse_expression,
+    create_timeline_chart, start_api_server
+)
+
+def demo_version_info():
+    """演示版本信息和功能状态"""
+    print("🚀 Staran v1.0.10 版本信息")
+    print("=" * 50)
+    
+    version_info = get_version_info()
+    print(f"版本: {version_info['version']}")
+    print(f"v1.0.10功能可用: {version_info['v1010_features_available']}")
+    
+    print("\n可用模块:")
+    for module, available in version_info['modules'].items():
+        status = "✅" if available else "❌"
+        print(f"  {status} {module}")
+    
+    if version_info.get('new_features'):
+        print(f"\n新功能: {', '.join(version_info['new_features'])}")
+    
+    # Date对象的功能状态
+    date_obj = Date.today()
+    feature_status = date_obj.get_feature_status()
+    
+    print(f"\nDate对象功能状态:")
+    for feature, available in feature_status.items():
+        status = "✅" if available else "❌"
+        print(f"  {status} {feature}")
+
+def demo_timezone_support():
+    """演示时区支持功能"""
+    print("\n\n🌍 时区支持功能演示")
+    print("=" * 50)
+    
+    date = Date("2025-07-29")
+    
+    try:
+        # 列出支持的时区
+        timezones = Date.get_supported_timezones()
+        print(f"支持的时区数量: {len(timezones)}")
+        print(f"主要时区: {timezones[:10]}")
+        
+        # 时区信息查询
+        print(f"\n时区信息查询:")
+        for tz in ['UTC+8', 'EST', 'JST', 'GMT']:
+            try:
+                tz_info = date.get_timezone_info(tz)
+                print(f"  {tz}: {tz_info['name']} ({tz_info['description']})")
+                print(f"      当前偏移: {tz_info['offset_string']}")
+                print(f"      夏令时: {'是' if tz_info['is_dst_active'] else '否'}")
+            except Exception as e:
+                print(f"  {tz}: 获取信息失败 - {e}")
+        
+        # 时区转换演示
+        print(f"\n时区转换演示:")
+        try:
+            import datetime as dt
+            base_time = dt.time(12, 0, 0)  # 中午12点
+            
+            beijing_dt = date.to_timezone('UTC+8', base_time)
+            print(f"  北京时间: {beijing_dt}")
+            
+            # 创建其他时区的时间
+            utc_dt = date.to_timezone('UTC', base_time)
+            print(f"  UTC时间: {utc_dt}")
+            
+        except Exception as e:
+            print(f"  时区转换演示失败: {e}")
+    
+    except Exception as e:
+        print(f"时区功能不可用: {e}")
+
+def demo_expression_parsing():
+    """演示日期表达式解析功能"""
+    print("\n\n📝 日期表达式解析演示")
+    print("=" * 50)
+    
+    expressions = [
+        "今天", "明天", "后天", "昨天", "前天",
+        "下周一", "上周五", "这周三",
+        "下个月", "上个月", "明年",
+        "3天后", "5天前", "2周后", "1个月前",
+        "2025年春节", "2025-12-25", "12月15日"
+    ]
+    
+    print("表达式解析测试:")
+    for expr in expressions:
+        try:
+            result = parse_expression(expr)
+            if result:
+                print(f"  '{expr}' → {result.format_iso()} ({result.format_chinese()})")
+                
+                # 获取详细解析信息
+                detailed = Date.parse_expression_detailed(expr)
+                if detailed['success']:
+                    print(f"    置信度: {detailed['confidence']:.2f}")
+                    print(f"    匹配模式: {detailed['matched_pattern']}")
+            else:
+                print(f"  '{expr}' → 解析失败")
+        except Exception as e:
+            print(f"  '{expr}' → 错误: {e}")
+
+def demo_solar_terms():
+    """演示二十四节气功能"""
+    print("\n\n🌸 二十四节气功能演示")
+    print("=" * 50)
+    
+    try:
+        current_year = 2025
+        
+        # 获取全年节气
+        solar_terms = Date.get_year_solar_terms(current_year)
+        print(f"{current_year}年二十四节气:")
+        
+        for i, term in enumerate(solar_terms):
+            print(f"  {i+1:2d}. {term.name:4s} - {term.date.strftime('%m月%d日')} ({term.season})")
+            if i == 5:  # 只显示前6个，节省空间
+                print(f"      ... (共{len(solar_terms)}个节气)")
+                break
+        
+        # 当前日期的节气信息
+        today = Date.today()
+        print(f"\n当前日期节气信息:")
+        print(f"  日期: {today.format_chinese()}")
+        
+        try:
+            current_term = today.get_solar_term()
+            if current_term:
+                print(f"  最近节气: {current_term.name}")
+                print(f"  节气日期: {current_term.date.strftime('%Y年%m月%d日')}")
+                print(f"  节气描述: {current_term.description}")
+                print(f"  气候特征: {current_term.climate_features}")
+            
+            # 下一个节气
+            next_term = today.get_next_solar_term()
+            print(f"  下一节气: {next_term.name}")
+            print(f"  节气日期: {next_term.date.strftime('%Y年%m月%d日')}")
+            print(f"  距离天数: {today.days_to_next_solar_term()}天")
+            
+            # 判断是否节气日
+            is_term_day = today.is_solar_term()
+            print(f"  今天是节气日: {'是' if is_term_day else '否'}")
+            
+        except Exception as e:
+            print(f"  节气信息获取失败: {e}")
+    
+    except Exception as e:
+        print(f"节气功能不可用: {e}")
+
+def demo_visualization():
+    """演示数据可视化功能"""
+    print("\n\n📊 数据可视化功能演示")
+    print("=" * 50)
+    
+    try:
+        # 创建示例数据
+        dates = [Date("2025-07-29"), Date("2025-08-01"), Date("2025-08-15")]
+        events = ["项目开始", "里程碑1", "项目完成"]
+        
+        # 创建时间轴图表
+        chart_data = create_timeline_chart(dates, events, 'echarts')
+        
+        print("时间轴图表数据:")
+        print(f"  图表类型: {chart_data.chart_type}")
+        print(f"  标题: {chart_data.title}")
+        print(f"  图表库: {chart_data.library}")
+        print(f"  数据点数量: {len(chart_data.data)}")
+        
+        # 显示部分数据
+        print(f"  示例数据:")
+        for i, data_point in enumerate(chart_data.data[:3]):
+            print(f"    {i+1}. {data_point}")
+        
+        # 日历热力图示例
+        print(f"\n日历热力图数据生成:")
+        date_values = {
+            Date("2025-07-29"): 85,
+            Date("2025-07-30"): 92,
+            Date("2025-07-31"): 78
+        }
+        
+        try:
+            heatmap_data = Date.create_calendar_heatmap(date_values, 2025, 'echarts')
+            print(f"  热力图标题: {heatmap_data.title}")
+            print(f"  数据点数量: {len(heatmap_data.data)}")
+        except Exception as e:
+            print(f"  热力图生成失败: {e}")
+        
+        # 时间序列图表
+        print(f"\n时间序列图表:")
+        time_series_data = [
+            (Date("2025-07-29"), 100),
+            (Date("2025-07-30"), 120),
+            (Date("2025-07-31"), 95)
+        ]
+        
+        try:
+            series_chart = Date.create_time_series_chart(time_series_data, 'echarts')
+            print(f"  系列图标题: {series_chart.title}")
+            print(f"  配置类型: {series_chart.config.get('type')}")
+        except Exception as e:
+            print(f"  时间序列图生成失败: {e}")
+    
+    except Exception as e:
+        print(f"可视化功能不可用: {e}")
+
+def demo_enhanced_date_ranges():
+    """演示增强的日期范围功能"""
+    print("\n\n📅 增强日期范围功能演示")
+    print("=" * 50)
+    
+    start_date = Date("2025-07-29")
+    end_date = Date("2025-08-15")
+    
+    # 创建日期范围
+    date_range = start_date.create_range_to(end_date)
+    print(f"日期范围: {start_date.format_iso()} 到 {end_date.format_iso()}")
+    print(f"范围天数: {date_range.days_count()}天")
+    
+    # 检查日期是否在范围内
+    test_date = Date("2025-08-01")
+    in_range = test_date.in_range(start_date, end_date)
+    print(f"{test_date.format_iso()} 在范围内: {'是' if in_range else '否'}")
+    
+    # 创建日期序列
+    sequence = Date.create_date_sequence(start_date, start_date.add_days(6), 2)
+    print(f"日期序列 (步长2天): {[d.format_iso() for d in sequence]}")
+    
+    # 范围操作
+    range1 = start_date.create_range_with_days(10)
+    range2 = start_date.add_days(5).create_range_with_days(10)
+    
+    print(f"范围1: {range1.start.format_iso()} - {range1.end.format_iso()}")
+    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()}")
+    else:
+        print("无交集")
+    
+    # 并集
+    union = range1.union(range2)
+    print(f"并集: {union.start.format_iso()} - {union.end.format_iso()}")
+
+def demo_api_server():
+    """演示REST API服务器功能"""
+    print("\n\n🌐 REST API服务器演示")
+    print("=" * 50)
+    
+    try:
+        from staran.date import start_api_server
+        
+        print("API服务器功能演示:")
+        print("  注意: 这里只演示服务器创建，不实际启动")
+        print("  实际使用时可以启动完整的HTTP服务")
+        
+        # 实际使用时的示例
+        print("\n启动API服务器的方法:")
+        print("  server = start_api_server('localhost', 8000, background=True)")
+        print("  # 服务器将在 http://localhost:8000 运行")
+        print("")
+        print("主要API端点:")
+        endpoints = [
+            "GET /api/health - 健康检查",
+            "GET /api/date/create?date=2025-07-29 - 创建日期",
+            "GET /api/date/format?date=2025-07-29&format=chinese - 格式化日期",
+            "GET /api/lunar/convert?date=2025-07-29&direction=solar_to_lunar - 农历转换",
+            "GET /api/solar-terms?year=2025 - 查询节气",
+            "GET /api/timezone/convert?date=2025-07-29&from_tz=UTC+8&to_tz=EST - 时区转换",
+            "GET /api/expression/parse?expression=明天 - 表达式解析",
+            "GET /api/visualization/data?type=calendar_heatmap&year=2025 - 可视化数据"
+        ]
+        
+        for endpoint in endpoints:
+            print(f"  {endpoint}")
+        
+        print(f"\n文档地址: GET /api/docs")
+        
+    except Exception as e:
+        print(f"API服务器功能不可用: {e}")
+
+def demo_help_system():
+    """演示帮助系统"""
+    print("\n\n❓ 帮助系统演示")
+    print("=" * 50)
+    
+    date = Date.today()
+    
+    # 获取创建方法帮助
+    help_creation = date.help('creation')
+    print("创建方法帮助:")
+    print(help_creation)
+    
+    # 获取时区功能帮助
+    try:
+        help_timezone = date.help('timezone')
+        print(f"\n时区功能帮助:")
+        print(help_timezone)
+    except:
+        print(f"\n时区功能帮助不可用")
+    
+    # 获取节气功能帮助
+    try:
+        help_solar_terms = date.help('solar_terms')
+        print(f"\n节气功能帮助:")
+        print(help_solar_terms)
+    except:
+        print(f"\n节气功能帮助不可用")
+
+def main():
+    """主演示函数"""
+    print("🚀 Staran v1.0.10 完整功能演示")
+    print("=" * 60)
+    
+    try:
+        # 基础信息
+        demo_version_info()
+        
+        # 新功能演示
+        demo_timezone_support()
+        demo_expression_parsing()
+        demo_solar_terms()
+        demo_visualization()
+        demo_enhanced_date_ranges()
+        demo_api_server()
+        demo_help_system()
+        
+        print("\n\n✅ v1.0.10 功能演示完成！")
+        print("=" * 60)
+        print("🌟 主要新增功能:")
+        print("   • 完整时区支持 - 全球时区转换和处理")
+        print("   • 日期表达式解析 - 自然语言日期解析")
+        print("   • 二十四节气扩展 - 完整节气计算和查询")
+        print("   • 数据可视化集成 - 多种图表库支持")
+        print("   • REST API接口 - HTTP API服务")
+        print("   • 增强日期范围操作 - 更丰富的范围功能")
+        print("   • 智能帮助系统 - 分类帮助信息")
+        print("")
+        print("📚 更多信息:")
+        print("   • API文档: 调用 Date().help() 查看")
+        print("   • 版本信息: 调用 get_version_info() 查看")
+        print("   • 功能状态: 调用 Date().get_feature_status() 查看")
+        
+    except Exception as e:
+        print(f"\n❌ 演示过程中出现错误: {e}")
+        import traceback
+        traceback.print_exc()
+
+if __name__ == "__main__":
+    main()

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())