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

staran/date/examples/enhanced_features.py

@@ -0,0 +1,230 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+"""
+Staran Date 模块增强功能演示
+==========================
+
+展示v1.0.7版本的所有新增和优化功能。
+"""
+
+import sys
+import os
+import json
+
+# 添加项目根目录到路径
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..', '..', '..'))
+
+from staran.date import Date
+
+
+def enhanced_holidays_demo():
+    """增强的节假日功能演示"""
+    print("🎊 增强的节假日功能")
+    print("=" * 40)
+    
+    # 中国节假日
+    print("中国节假日:")
+    cn_dates = ['20250101', '20250501', '20251001', '20250405']
+    for date_str in cn_dates:
+        date = Date(date_str)
+        is_holiday = date.is_holiday('CN')
+        status = "✅ 节假日" if is_holiday else "❌ 工作日"
+        print(f"   {date.format_chinese()}: {status}")
+    
+    # 美国节假日
+    print("\n美国节假日:")
+    us_dates = ['20250101', '20250704', '20251225', '20251127']
+    for date_str in us_dates:
+        date = Date(date_str)
+        is_holiday = date.is_holiday('US')
+        status = "✅ 节假日" if is_holiday else "❌ 工作日"
+        print(f"   {date.format_iso()}: {status}")
+    
+    print()
+
+
+def batch_processing_demo():
+    """批量处理功能演示"""
+    print("⚡ 批量处理功能")
+    print("=" * 40)
+    
+    # 批量创建
+    date_strings = ['20250101', '20250201', '20250301', '20250401']
+    dates = Date.batch_create(date_strings)
+    print("批量创建结果:")
+    for i, date in enumerate(dates):
+        print(f"   {date_strings[i]} -> {date}")
+    
+    # 批量格式化
+    print("\n批量格式化:")
+    iso_formats = Date.batch_format(dates, 'iso')
+    chinese_formats = Date.batch_format(dates, 'chinese')
+    
+    for i, date in enumerate(dates):
+        print(f"   原始: {date}")
+        print(f"   ISO: {iso_formats[i]}")
+        print(f"   中文: {chinese_formats[i]}")
+        print()
+
+
+def timezone_demo():
+    """时区支持演示"""
+    print("🌍 时区支持功能")
+    print("=" * 40)
+    
+    date = Date('20250101')
+    
+    # 不同时区的时间戳
+    utc_timestamp = date.to_timestamp(0)      # UTC
+    beijing_timestamp = date.to_timestamp(8) # 北京时间 (UTC+8)
+    ny_timestamp = date.to_timestamp(-5)     # 纽约时间 (UTC-5)
+    
+    print("同一日期在不同时区的时间戳:")
+    print(f"   UTC: {utc_timestamp}")
+    print(f"   北京时间: {beijing_timestamp}")
+    print(f"   纽约时间: {ny_timestamp}")
+    
+    # 从时间戳创建日期
+    print("\n从时间戳创建日期:")
+    base_timestamp = 1735689600  # 2025-01-01 00:00:00 UTC
+    utc_date = Date.from_timestamp(base_timestamp, 0)
+    beijing_date = Date.from_timestamp(base_timestamp, 8)
+    
+    print(f"   UTC时间戳 -> {utc_date.format_iso()}")
+    print(f"   +8小时偏移 -> {beijing_date.format_iso()}")
+    print()
+
+
+def business_rules_demo():
+    """业务规则演示"""
+    print("📊 业务规则功能")
+    print("=" * 40)
+    
+    date = Date('20250415')  # 2025年4月15日
+    
+    print(f"基准日期: {date.format_chinese()}")
+    
+    # 各种业务规则
+    rules = [
+        ('month_end', '月末'),
+        ('quarter_end', '季度末'),
+        ('next_business_day', '下一个工作日'),
+        ('prev_business_day', '上一个工作日')
+    ]
+    
+    for rule, description in rules:
+        try:
+            result = date.apply_business_rule(rule)
+            print(f"   {description}: {result.format_chinese()}")
+        except ValueError as e:
+            print(f"   {description}: {e}")
+    
+    print()
+
+
+def enhanced_json_demo():
+    """增强JSON功能演示"""
+    print("📄 增强JSON序列化")
+    print("=" * 40)
+    
+    date = Date('20250415')
+    
+    # 包含元数据的JSON
+    json_with_meta = date.to_json(include_metadata=True)
+    json_simple = date.to_json(include_metadata=False)
+    
+    print("包含元数据的JSON:")
+    print(json.dumps(json.loads(json_with_meta), indent=2, ensure_ascii=False))
+    
+    print("\n简单JSON:")
+    print(json.dumps(json.loads(json_simple), indent=2, ensure_ascii=False))
+    
+    # 字典转换
+    dict_with_meta = date.to_dict(include_metadata=True)
+    print("\n包含元数据的字典:")
+    for key, value in dict_with_meta.items():
+        print(f"   {key}: {value}")
+    
+    print()
+
+
+def date_ranges_demo():
+    """日期范围功能演示"""
+    print("📅 新增日期范围功能")
+    print("=" * 40)
+    
+    # 工作日和周末
+    print("一周的工作日和周末:")
+    business_days = Date.business_days('20250407', '20250413')  # 一周
+    weekends = Date.weekends('20250407', '20250413')
+    
+    print("   工作日:", [str(d) for d in business_days])
+    print("   周末:", [str(d) for d in weekends])
+    
+    # 月份范围
+    print("\n月份范围 (前3个月):")
+    months = Date.month_range('202501', 3)
+    for month in months:
+        print(f"   {month} ({month.format_chinese()})")
+    
+    # 季度日期
+    print("\n2025年季度划分:")
+    quarters = Date.quarter_dates(2025)
+    for q, (start, end) in quarters.items():
+        print(f"   Q{q}: {start.format_compact()} - {end.format_compact()}")
+    
+    print()
+
+
+def validation_demo():
+    """验证功能演示"""
+    print("✅ 日期验证功能")
+    print("=" * 40)
+    
+    test_strings = [
+        '20250415',  # 有效
+        '20250230',  # 无效 - 2月30日
+        '202504',    # 有效
+        'invalid',   # 无效
+        '20251301',  # 无效 - 13月
+    ]
+    
+    print("日期字符串验证:")
+    for test_str in test_strings:
+        is_valid = Date.is_valid_date_string(test_str)
+        status = "✅ 有效" if is_valid else "❌ 无效"
+        print(f"   '{test_str}': {status}")
+    
+    print()
+
+
+def main():
+    """主演示函数"""
+    print("✨ Staran Date 模块 v1.0.7 增强功能演示")
+    print("=" * 50)
+    print()
+    
+    # 运行各个演示
+    enhanced_holidays_demo()
+    batch_processing_demo()
+    timezone_demo()
+    business_rules_demo()
+    enhanced_json_demo()
+    date_ranges_demo()
+    validation_demo()
+    
+    print("🎉 演示完成!")
+    print("\n📝 总结:")
+    print("   • 增强的节假日支持 (多国节假日)")
+    print("   • 高效的批量处理功能")
+    print("   • 基础时区转换支持")
+    print("   • 灵活的业务规则引擎")
+    print("   • 增强的JSON序列化")
+    print("   • 丰富的日期范围生成")
+    print("   • 严格的数据验证")
+    print("\n更多功能请查阅API文档! 📚")
+
+
+if __name__ == '__main__':
+    main()

staran/date/tests/test_enhancements.py

@@ -0,0 +1,295 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+"""
+Date类增强功能测试
+================
+
+测试新增的优化和改进功能：
+- 增强的节假日支持
+- 批量处理方法
+- 时区支持
+- 业务规则
+- 改进的JSON序列化
+"""
+
+import unittest
+import datetime
+import sys
+import os
+
+# 添加项目根目录到路径
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..', '..', '..'))
+
+from staran.date.core import Date
+
+
+class TestEnhancedHolidays(unittest.TestCase):
+    """测试增强的节假日功能"""
+    
+    def test_chinese_holidays(self):
+        """测试中国节假日"""
+        # 元旦
+        new_year = Date('20250101')
+        self.assertTrue(new_year.is_holiday('CN'))
+        
+        # 劳动节
+        labor_day = Date('20250501')
+        self.assertTrue(labor_day.is_holiday('CN'))
+        
+        # 国庆节
+        national_day = Date('20251001')
+        self.assertTrue(national_day.is_holiday('CN'))
+        
+        # 普通日期
+        regular_day = Date('20250315')
+        self.assertFalse(regular_day.is_holiday('CN'))
+    
+    def test_us_holidays(self):
+        """测试美国节假日"""
+        # 独立日
+        independence_day = Date('20250704')
+        self.assertTrue(independence_day.is_holiday('US'))
+        
+        # 圣诞节
+        christmas = Date('20251225')
+        self.assertTrue(christmas.is_holiday('US'))
+        
+        # 感恩节测试（11月第四个星期四）
+        thanksgiving_2025 = Date('20251127')  # 2025年11月27日是第四个星期四
+        self.assertTrue(thanksgiving_2025.is_holiday('US'))
+    
+    def test_japanese_holidays(self):
+        """测试日本节假日"""
+        # 元日
+        new_year = Date('20250101')
+        self.assertTrue(new_year.is_holiday('JP'))
+        
+        # 建国記念の日
+        foundation_day = Date('20250211')
+        self.assertTrue(foundation_day.is_holiday('JP'))
+        
+        # 文化の日
+        culture_day = Date('20251103')
+        self.assertTrue(culture_day.is_holiday('JP'))
+
+
+class TestBatchProcessing(unittest.TestCase):
+    """测试批量处理功能"""
+    
+    def test_batch_create(self):
+        """测试批量创建"""
+        date_strings = ['20250101', '20250202', '20250303']
+        dates = Date.batch_create(date_strings)
+        
+        self.assertEqual(len(dates), 3)
+        self.assertEqual(str(dates[0]), '20250101')
+        self.assertEqual(str(dates[1]), '20250202')
+        self.assertEqual(str(dates[2]), '20250303')
+    
+    def test_batch_format(self):
+        """测试批量格式化"""
+        dates = [Date('20250101'), Date('20250202'), Date('20250303')]
+        
+        # ISO格式
+        iso_results = Date.batch_format(dates, 'iso')
+        self.assertEqual(iso_results, ['2025-01-01', '2025-02-02', '2025-03-03'])
+        
+        # 中文格式
+        chinese_results = Date.batch_format(dates, 'chinese')
+        self.assertEqual(chinese_results, ['2025年01月01日', '2025年02月02日', '2025年03月03日'])
+    
+    def test_batch_add_days(self):
+        """测试批量添加天数"""
+        dates = [Date('20250101'), Date('20250202')]
+        new_dates = Date.batch_add_days(dates, 10)
+        
+        self.assertEqual(str(new_dates[0]), '20250111')
+        self.assertEqual(str(new_dates[1]), '20250212')
+
+
+class TestTimezoneSupport(unittest.TestCase):
+    """测试时区支持"""
+    
+    def test_timestamp_with_timezone(self):
+        """测试带时区的时间戳转换"""
+        date = Date('20250101')
+        
+        # 默认时区
+        timestamp_default = date.to_timestamp()
+        
+        # 东八区
+        timestamp_utc8 = date.to_timestamp(8)
+        
+        # 时差应该是8小时
+        self.assertAlmostEqual(timestamp_default - timestamp_utc8, 8 * 3600, delta=1)
+    
+    def test_from_timestamp_with_timezone(self):
+        """测试从带时区的时间戳创建"""
+        timestamp = 1735689600  # 2025-01-01 00:00:00 UTC
+        
+        # UTC时间
+        date_utc = Date.from_timestamp(timestamp, 0)
+        
+        # 东八区时间
+        date_utc8 = Date.from_timestamp(timestamp, 8)
+        
+        # 应该相差一天或在边界情况下相同
+        self.assertTrue(abs((date_utc8.to_date_object() - date_utc.to_date_object()).days) <= 1)
+
+
+class TestBusinessRules(unittest.TestCase):
+    """测试业务规则"""
+    
+    def test_month_end_rule(self):
+        """测试月末规则"""
+        date = Date('20250415')
+        month_end = date.apply_business_rule('month_end')
+        self.assertEqual(str(month_end), '20250430')
+    
+    def test_quarter_end_rule(self):
+        """测试季度末规则"""
+        date = Date('20250415')
+        quarter_end = date.apply_business_rule('quarter_end')
+        self.assertEqual(str(quarter_end), '20250630')
+    
+    def test_next_business_day_rule(self):
+        """测试下一个工作日规则"""
+        # 周五
+        friday = Date('20250418')  # 假设这是周五
+        next_business = friday.add_days(1).apply_business_rule('next_business_day')
+        
+        # 应该跳过周末到周一
+        self.assertTrue(next_business.is_business_day())
+    
+    def test_prev_business_day_rule(self):
+        """测试上一个工作日规则"""
+        # 周一
+        monday = Date('20250421')  # 假设这是周一
+        prev_business = monday.subtract_days(1).apply_business_rule('prev_business_day')
+        
+        # 应该跳过周末到周五
+        self.assertTrue(prev_business.is_business_day())
+
+
+class TestEnhancedJSON(unittest.TestCase):
+    """测试增强的JSON功能"""
+    
+    def test_json_with_metadata(self):
+        """测试包含元数据的JSON序列化"""
+        date = Date('20250415')
+        json_str = date.to_json(include_metadata=True)
+        
+        import json
+        data = json.loads(json_str)
+        
+        # 检查基本字段
+        self.assertEqual(data['year'], 2025)
+        self.assertEqual(data['month'], 4)
+        self.assertEqual(data['day'], 15)
+        
+        # 检查元数据
+        self.assertIn('weekday', data)
+        self.assertIn('is_weekend', data)
+        self.assertIn('quarter', data)
+        self.assertIn('version', data)
+    
+    def test_json_without_metadata(self):
+        """测试不包含元数据的JSON序列化"""
+        date = Date('20250415')
+        json_str = date.to_json(include_metadata=False)
+        
+        import json
+        data = json.loads(json_str)
+        
+        # 检查基本字段存在
+        required_fields = ['date', 'year', 'month', 'day']
+        for field in required_fields:
+            self.assertIn(field, data)
+        
+        # 检查元数据不存在
+        metadata_fields = ['weekday', 'is_weekend', 'quarter', 'version']
+        for field in metadata_fields:
+            self.assertNotIn(field, data)
+    
+    def test_dict_with_metadata(self):
+        """测试包含元数据的字典转换"""
+        date = Date('20250415')
+        data = date.to_dict(include_metadata=True)
+        
+        # 检查基本字段
+        self.assertEqual(data['year'], 2025)
+        self.assertEqual(data['month'], 4)
+        self.assertEqual(data['day'], 15)
+        
+        # 检查元数据
+        self.assertIn('weekday', data)
+        self.assertIn('is_weekend', data)
+        self.assertIn('quarter', data)
+        self.assertIn('iso_string', data)
+        self.assertIn('compact_string', data)
+
+
+class TestNewDateRanges(unittest.TestCase):
+    """测试新的日期范围功能"""
+    
+    def test_weekends_range(self):
+        """测试周末范围生成"""
+        weekends = Date.weekends('20250401', '20250407')  # 一周
+        
+        # 应该只包含周末日期
+        for date in weekends:
+            self.assertTrue(date.is_weekend())
+    
+    def test_month_range(self):
+        """测试月份范围生成"""
+        months = Date.month_range('202501', 3)
+        
+        self.assertEqual(len(months), 3)
+        # 注意：月份范围返回的是年月格式，保持输入格式
+        self.assertEqual(str(months[0]), '202501')  # 2025年1月1日
+        self.assertEqual(str(months[1]), '202502')  # 2025年2月1日
+        self.assertEqual(str(months[2]), '202503')  # 2025年3月1日
+    
+    def test_quarter_dates(self):
+        """测试季度日期生成"""
+        quarters = Date.quarter_dates(2025)
+        
+        self.assertEqual(len(quarters), 4)
+        
+        # 检查第一季度 - 季度日期使用ISO格式
+        q1_start, q1_end = quarters[1]
+        self.assertEqual(q1_start.format_compact(), '20250101')
+        self.assertEqual(q1_end.format_compact(), '20250331')
+        
+        # 检查第四季度
+        q4_start, q4_end = quarters[4]
+        self.assertEqual(q4_start.format_compact(), '20251001')
+        self.assertEqual(q4_end.format_compact(), '20251231')
+
+
+class TestDateValidation(unittest.TestCase):
+    """测试日期验证功能"""
+    
+    def test_is_valid_date_string(self):
+        """测试日期字符串验证"""
+        # 有效日期
+        self.assertTrue(Date.is_valid_date_string('20250415'))
+        self.assertTrue(Date.is_valid_date_string('202504'))
+        self.assertTrue(Date.is_valid_date_string('2025'))
+        
+        # 无效日期
+        self.assertFalse(Date.is_valid_date_string('20250230'))  # 2月30日
+        self.assertFalse(Date.is_valid_date_string('invalid'))
+        self.assertFalse(Date.is_valid_date_string(''))
+    
+    def test_year_boundary_warning(self):
+        """测试年份边界警告"""
+        # 这个测试检查是否会记录警告日志
+        # 在实际应用中，可能需要设置日志级别来捕获警告
+        extreme_year_date = Date('10000101')  # 公元1000年
+        self.assertEqual(extreme_year_date.year, 1000)
+
+
+if __name__ == '__main__':
+    unittest.main(verbosity=2)