staran 1.0.0__py3-none-any.whl → 1.0.1__py3-none-any.whl

staran/tools/tests/__init__.py

@@ -0,0 +1,119 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+"""
+Staran Tools 测试模块
+==================
+
+为staran.tools包提供全面的单元测试和集成测试。
+
+测试模块结构：
+- test_date.py - Date类的完整测试套件
+- test_api_compatibility.py - API兼容性测试
+- test_logging.py - 日志系统测试
+- test_performance.py - 性能基准测试
+
+使用方法：
+    # 运行所有测试
+    python -m unittest discover staran.tools.tests
+    
+    # 运行特定测试文件
+    python -m unittest staran.tools.tests.test_date
+    
+    # 运行特定测试类
+    python -m unittest staran.tools.tests.test_date.TestDateCreation
+"""
+
+__version__ = '1.0.1'
+__author__ = 'StarAn'
+__description__ = 'Test suite for staran.tools package'
+
+# 测试相关的导入
+try:
+    import unittest
+    import logging
+    import sys
+    import os
+    
+    # 添加父目录到路径，确保可以导入staran模块
+    sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..', '..', '..'))
+    
+    HAS_UNITTEST = True
+except ImportError:
+    HAS_UNITTEST = False
+
+__all__ = [
+    'HAS_UNITTEST',
+    'run_all_tests',
+    'run_test_suite'
+]
+
+
+def run_all_tests(verbosity=2):
+    """
+    运行所有测试
+    
+    Args:
+        verbosity: 详细程度 (0=静默, 1=正常, 2=详细)
+        
+    Returns:
+        TestResult对象
+    """
+    if not HAS_UNITTEST:
+        print("❌ unittest模块不可用，无法运行测试")
+        return None
+    
+    # 发现并运行所有测试
+    loader = unittest.TestLoader()
+    start_dir = os.path.dirname(__file__)
+    suite = loader.discover(start_dir, pattern='test_*.py')
+    
+    runner = unittest.TextTestRunner(verbosity=verbosity)
+    result = runner.run(suite)
+    
+    return result
+
+
+def run_test_suite(test_module, verbosity=2):
+    """
+    运行指定的测试套件
+    
+    Args:
+        test_module: 测试模块名称 (如 'test_date')
+        verbosity: 详细程度
+        
+    Returns:
+        TestResult对象
+    """
+    if not HAS_UNITTEST:
+        print("❌ unittest模块不可用，无法运行测试")
+        return None
+    
+    # 导入并运行指定的测试模块
+    try:
+        module = __import__(f'staran.tools.tests.{test_module}', fromlist=[test_module])
+        loader = unittest.TestLoader()
+        suite = loader.loadTestsFromModule(module)
+        
+        runner = unittest.TextTestRunner(verbosity=verbosity)
+        result = runner.run(suite)
+        
+        return result
+    except ImportError as e:
+        print(f"❌ 无法导入测试模块 {test_module}: {e}")
+        return None
+
+
+if __name__ == "__main__":
+    print("🧪 Staran Tools 测试套件")
+    print("=" * 50)
+    
+    if HAS_UNITTEST:
+        result = run_all_tests()
+        if result:
+            if result.wasSuccessful():
+                print("✅ 所有测试通过!")
+            else:
+                print(f"❌ 测试失败: {len(result.failures)} 失败, {len(result.errors)} 错误")
+    else:
+        print("❌ 测试环境不完整，请确保Python环境正确安装")

staran/tools/tests/run_tests.py

@@ -0,0 +1,241 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+"""
+完整测试套件运行器
+===============
+
+运行所有测试并生成测试报告
+"""
+
+import unittest
+import sys
+import os
+import logging
+import time
+from io import StringIO
+
+# 添加项目根目录到路径
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..', '..', '..'))
+
+# 导入所有测试模块
+from test_date import *
+from test_api_compatibility import *
+from test_logging import *
+
+# 静音Date类的日志，避免干扰测试输出
+from staran.tools.date import Date
+Date.set_log_level(logging.CRITICAL)
+
+
+class ColoredTextTestResult(unittest.TextTestResult):
+    """带颜色的测试结果输出"""
+    
+    def __init__(self, stream, descriptions, verbosity):
+        super().__init__(stream, descriptions, verbosity)
+        self.verbosity = verbosity  # 确保verbosity属性存在
+        self.colors = {
+            'green': '\033[92m',
+            'red': '\033[91m',
+            'yellow': '\033[93m',
+            'blue': '\033[94m',
+            'purple': '\033[95m',
+            'cyan': '\033[96m',
+            'white': '\033[97m',
+            'end': '\033[0m',
+            'bold': '\033[1m'
+        }
+    
+    def addSuccess(self, test):
+        super().addSuccess(test)
+        if self.verbosity > 1:
+            self.stream.write(f"{self.colors['green']}✓{self.colors['end']} ")
+            self.stream.writeln(f"{self.colors['green']}{self.getDescription(test)}{self.colors['end']}")
+    
+    def addError(self, test, err):
+        super().addError(test, err)
+        if self.verbosity > 1:
+            self.stream.write(f"{self.colors['red']}✗{self.colors['end']} ")
+            self.stream.writeln(f"{self.colors['red']}{self.getDescription(test)}{self.colors['end']}")
+    
+    def addFailure(self, test, err):
+        super().addFailure(test, err)
+        if self.verbosity > 1:
+            self.stream.write(f"{self.colors['red']}✗{self.colors['end']} ")
+            self.stream.writeln(f"{self.colors['red']}{self.getDescription(test)}{self.colors['end']}")
+    
+    def addSkip(self, test, reason):
+        super().addSkip(test, reason)
+        if self.verbosity > 1:
+            self.stream.write(f"{self.colors['yellow']}⊝{self.colors['end']} ")
+            self.stream.writeln(f"{self.colors['yellow']}{self.getDescription(test)} (skipped: {reason}){self.colors['end']}")
+
+
+class ColoredTestRunner(unittest.TextTestRunner):
+    """带颜色的测试运行器"""
+    
+    def __init__(self, **kwargs):
+        kwargs['resultclass'] = ColoredTextTestResult
+        super().__init__(**kwargs)
+
+
+def create_test_suite():
+    """创建完整测试套件"""
+    loader = unittest.TestLoader()
+    suite = unittest.TestSuite()
+    
+    # 添加所有测试模块
+    test_modules = [
+        'test_date',
+        'test_api_compatibility', 
+        'test_logging'
+    ]
+    
+    for module_name in test_modules:
+        try:
+            module = __import__(module_name)
+            module_suite = loader.loadTestsFromModule(module)
+            suite.addTest(module_suite)
+        except ImportError as e:
+            print(f"警告: 无法导入测试模块 {module_name}: {e}")
+    
+    return suite
+
+
+def run_test_category(category_name, test_classes):
+    """运行特定类别的测试"""
+    print(f"\n{'='*60}")
+    print(f"运行 {category_name} 测试")
+    print(f"{'='*60}")
+    
+    suite = unittest.TestSuite()
+    
+    for test_class in test_classes:
+        tests = unittest.TestLoader().loadTestsFromTestCase(test_class)
+        suite.addTest(tests)
+    
+    runner = ColoredTestRunner(verbosity=2)
+    start_time = time.time()
+    result = runner.run(suite)
+    end_time = time.time()
+    
+    print(f"\n{category_name} 测试完成")
+    print(f"运行时间: {end_time - start_time:.2f}秒")
+    print(f"测试总数: {result.testsRun}")
+    print(f"成功: {result.testsRun - len(result.failures) - len(result.errors)}")
+    print(f"失败: {len(result.failures)}")
+    print(f"错误: {len(result.errors)}")
+    print(f"跳过: {len(result.skipped)}")
+    
+    return result
+
+
+def main():
+    """主函数"""
+    print("Staran Date 库测试套件")
+    print("="*60)
+    print(f"Python 版本: {sys.version}")
+    print(f"测试开始时间: {time.strftime('%Y-%m-%d %H:%M:%S')}")
+    
+    all_results = []
+    
+    # 1. 核心功能测试
+    print("\n🔧 运行核心功能测试...")
+    core_tests = [
+        TestDateCreation,
+        TestDateClassMethods,
+        TestDateConversion,
+        TestDateFormatting,
+        TestDateGetters,
+        TestDatePredicates,
+        TestDateArithmetic,
+        TestDateComparison,
+        TestDateCalculation,
+        TestDateErrorHandling,
+        TestBackwardCompatibility
+    ]
+    
+    core_result = run_test_category("核心功能", core_tests)
+    all_results.append(("核心功能", core_result))
+    
+    # 2. API兼容性测试
+    print("\n🔄 运行API兼容性测试...")
+    api_tests = [
+        TestAPICompatibility,
+        TestMethodSignatures,
+        TestAPIDocumentation,
+        TestAPIEvolution
+    ]
+    
+    api_result = run_test_category("API兼容性", api_tests)
+    all_results.append(("API兼容性", api_result))
+    
+    # 3. 日志系统测试
+    print("\n📝 运行日志系统测试...")
+    logging_tests = [
+        TestLoggingSystem,
+        TestLoggingConfiguration,
+        TestLoggingIntegration,
+        TestLoggingEdgeCases
+    ]
+    
+    logging_result = run_test_category("日志系统", logging_tests)
+    all_results.append(("日志系统", logging_result))
+    
+    # 生成总结报告
+    print("\n" + "="*60)
+    print("测试总结报告")
+    print("="*60)
+    
+    total_tests = 0
+    total_failures = 0
+    total_errors = 0
+    total_skipped = 0
+    
+    for category, result in all_results:
+        total_tests += result.testsRun
+        total_failures += len(result.failures)
+        total_errors += len(result.errors)
+        total_skipped += len(result.skipped)
+        
+        success_rate = ((result.testsRun - len(result.failures) - len(result.errors)) / result.testsRun * 100) if result.testsRun > 0 else 0
+        
+        print(f"{category:20} | 测试: {result.testsRun:3d} | 成功率: {success_rate:6.1f}% | 失败: {len(result.failures):2d} | 错误: {len(result.errors):2d}")
+    
+    print("-" * 60)
+    overall_success_rate = ((total_tests - total_failures - total_errors) / total_tests * 100) if total_tests > 0 else 0
+    print(f"{'总计':20} | 测试: {total_tests:3d} | 成功率: {overall_success_rate:6.1f}% | 失败: {total_failures:2d} | 错误: {total_errors:2d}")
+    
+    # 详细失败和错误报告
+    if total_failures > 0 or total_errors > 0:
+        print("\n" + "="*60)
+        print("失败和错误详情")
+        print("="*60)
+        
+        for category, result in all_results:
+            if result.failures:
+                print(f"\n{category} - 失败:")
+                for test, traceback in result.failures:
+                    print(f"  ✗ {test}")
+                    print(f"    {traceback.split('AssertionError:')[-1].strip() if 'AssertionError:' in traceback else '详见完整日志'}")
+            
+            if result.errors:
+                print(f"\n{category} - 错误:")
+                for test, traceback in result.errors:
+                    print(f"  ✗ {test}")
+                    print(f"    {traceback.split('\\n')[-2] if '\\n' in traceback else traceback}")
+    
+    print(f"\n测试完成时间: {time.strftime('%Y-%m-%d %H:%M:%S')}")
+    
+    # 返回适当的退出码
+    if total_failures > 0 or total_errors > 0:
+        print(f"\n❌ 测试失败! 失败: {total_failures}, 错误: {total_errors}")
+        return 1
+    else:
+        print(f"\n✅ 所有测试通过! 总计 {total_tests} 个测试")
+        return 0
+
+
+if __name__ == '__main__':
+    exit_code = main()
+    sys.exit(exit_code)

staran/tools/tests/test_api_compatibility.py

@@ -0,0 +1,319 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+"""
+API兼容性测试
+===========
+
+测试所有API方法的兼容性，包括：
+- 新API命名规范
+- 向后兼容性
+- 别名方法
+- 方法映射
+"""
+
+import unittest
+import sys
+import os
+import logging
+
+# 添加项目根目录到路径
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..', '..', '..'))
+
+from staran.tools.date import Date
+
+
+class TestAPICompatibility(unittest.TestCase):
+    """测试API兼容性"""
+    
+    def setUp(self):
+        """设置测试数据"""
+        self.date = Date('20250415')
+        # 静音日志
+        Date.set_log_level(logging.CRITICAL)
+    
+    def test_all_new_api_methods_exist(self):
+        """验证所有新API方法都存在"""
+        # from_* 系列
+        new_from_methods = [
+            'from_string', 'from_timestamp', 'from_date_object', 
+            'from_datetime_object'
+        ]
+        
+        for method_name in new_from_methods:
+            self.assertTrue(hasattr(Date, method_name), 
+                          f"Class method {method_name} not found")
+        
+        # to_* 系列
+        new_to_methods = [
+            'to_tuple', 'to_dict', 'to_date_object', 
+            'to_datetime_object', 'to_timestamp'
+        ]
+        
+        for method_name in new_to_methods:
+            self.assertTrue(hasattr(self.date, method_name), 
+                          f"Instance method {method_name} not found")
+        
+        # format_* 系列
+        new_format_methods = [
+            'format_default', 'format_iso', 'format_chinese', 
+            'format_compact', 'format_slash', 'format_dot', 
+            'format_custom', 'format_year_month', 'format_year_month_compact'
+        ]
+        
+        for method_name in new_format_methods:
+            self.assertTrue(hasattr(self.date, method_name), 
+                          f"Instance method {method_name} not found")
+        
+        # get_* 系列
+        new_get_methods = [
+            'get_weekday', 'get_isoweekday', 'get_days_in_month', 
+            'get_days_in_year', 'get_format_type', 'get_month_start', 
+            'get_month_end', 'get_year_start', 'get_year_end'
+        ]
+        
+        for method_name in new_get_methods:
+            self.assertTrue(hasattr(self.date, method_name), 
+                          f"Instance method {method_name} not found")
+        
+        # is_* 系列
+        new_is_methods = [
+            'is_weekend', 'is_weekday', 'is_leap_year', 
+            'is_month_start', 'is_month_end', 'is_year_start', 'is_year_end'
+        ]
+        
+        for method_name in new_is_methods:
+            self.assertTrue(hasattr(self.date, method_name), 
+                          f"Instance method {method_name} not found")
+        
+        # add_/subtract_* 系列
+        new_arithmetic_methods = [
+            'add_days', 'add_months', 'add_years',
+            'subtract_days', 'subtract_months', 'subtract_years'
+        ]
+        
+        for method_name in new_arithmetic_methods:
+            self.assertTrue(hasattr(self.date, method_name), 
+                          f"Instance method {method_name} not found")
+        
+        # calculate_* 系列
+        new_calculate_methods = [
+            'calculate_difference_days', 'calculate_difference_months'
+        ]
+        
+        for method_name in new_calculate_methods:
+            self.assertTrue(hasattr(self.date, method_name), 
+                          f"Instance method {method_name} not found")
+    
+    def test_backward_compatibility_methods_exist(self):
+        """验证所有向后兼容方法都存在"""
+        old_methods = [
+            'format', 'to_date', 'to_datetime', 'weekday', 'difference',
+            'start_of_month', 'end_of_month', 'start_of_year', 'end_of_year',
+            'add', 'subtract', 'days_in_month', 'is_leap', 'convert_format'
+        ]
+        
+        for method_name in old_methods:
+            self.assertTrue(hasattr(self.date, method_name), 
+                          f"Backward compatibility method {method_name} not found")
+    
+    def test_new_api_functionality(self):
+        """测试新API方法的功能"""
+        # 测试to_*系列
+        self.assertEqual(self.date.to_tuple(), (2025, 4, 15))
+        self.assertIsInstance(self.date.to_dict(), dict)
+        
+        # 测试format_*系列
+        self.assertEqual(self.date.format_iso(), '2025-04-15')
+        self.assertEqual(self.date.format_chinese(), '2025年04月15日')
+        
+        # 测试get_*系列
+        self.assertIsInstance(self.date.get_weekday(), int)
+        self.assertIsInstance(self.date.get_days_in_month(), int)
+        
+        # 测试is_*系列
+        self.assertIsInstance(self.date.is_weekend(), bool)
+        self.assertIsInstance(self.date.is_leap_year(), bool)
+        
+        # 测试add_/subtract_*系列
+        result = self.date.add_days(1)
+        self.assertEqual(str(result), '20250416')
+        
+        result = self.date.subtract_days(1)
+        self.assertEqual(str(result), '20250414')
+    
+    def test_backward_compatibility_functionality(self):
+        """测试向后兼容方法的功能"""
+        # 旧方法应该与新方法产生相同结果
+        self.assertEqual(self.date.format('%Y-%m-%d'), self.date.format_custom('%Y-%m-%d'))
+        self.assertEqual(self.date.to_date(), self.date.to_date_object())
+        self.assertEqual(self.date.to_datetime(), self.date.to_datetime_object())
+        self.assertEqual(self.date.weekday(), self.date.get_weekday())
+        
+        # 测试difference方法
+        other = Date('20250420')
+        self.assertEqual(other.difference(self.date), 
+                        other.calculate_difference_days(self.date))
+    
+    def test_method_aliases(self):
+        """测试方法别名"""
+        # 测试别名映射
+        self.assertEqual(self.date.start_of_month(), self.date.get_month_start())
+        self.assertEqual(self.date.end_of_month(), self.date.get_month_end())
+        self.assertEqual(self.date.start_of_year(), self.date.get_year_start())
+        self.assertEqual(self.date.end_of_year(), self.date.get_year_end())
+        self.assertEqual(self.date.days_in_month(), self.date.get_days_in_month())
+        self.assertEqual(self.date.is_leap(), self.date.is_leap_year())
+    
+    def test_api_consistency(self):
+        """测试API一致性"""
+        # 所有from_*方法都应该是类方法
+        self.assertTrue(callable(getattr(Date, 'from_string')))
+        self.assertTrue(callable(getattr(Date, 'from_timestamp')))
+        
+        # 所有to_*方法都应该返回转换后的值
+        self.assertIsInstance(self.date.to_tuple(), tuple)
+        self.assertIsInstance(self.date.to_dict(), dict)
+        
+        # 所有format_*方法都应该返回字符串
+        self.assertIsInstance(self.date.format_default(), str)
+        self.assertIsInstance(self.date.format_iso(), str)
+        
+        # 所有get_*方法都应该返回值
+        self.assertIsNotNone(self.date.get_weekday())
+        self.assertIsNotNone(self.date.get_format_type())
+        
+        # 所有is_*方法都应该返回布尔值
+        self.assertIsInstance(self.date.is_weekend(), bool)
+        self.assertIsInstance(self.date.is_leap_year(), bool)
+        
+        # 所有add_/subtract_*方法都应该返回新的Date对象
+        self.assertIsInstance(self.date.add_days(1), Date)
+        self.assertIsInstance(self.date.subtract_days(1), Date)
+
+
+class TestMethodSignatures(unittest.TestCase):
+    """测试方法签名"""
+    
+    def setUp(self):
+        """设置测试数据"""
+        self.date = Date('20250415')
+        Date.set_log_level(logging.CRITICAL)
+    
+    def test_from_methods_signatures(self):
+        """测试from_*方法签名"""
+        # from_string应该接受字符串
+        result = Date.from_string('20250101')
+        self.assertIsInstance(result, Date)
+        
+        # from_timestamp应该接受数字
+        import time
+        timestamp = time.time()
+        result = Date.from_timestamp(timestamp)
+        self.assertIsInstance(result, Date)
+    
+    def test_format_methods_signatures(self):
+        """测试format_*方法签名"""
+        # format_custom应该接受格式字符串
+        result = self.date.format_custom('%Y-%m-%d')
+        self.assertEqual(result, '2025-04-15')
+        
+        # 其他format方法不需要参数
+        self.assertIsInstance(self.date.format_default(), str)
+        self.assertIsInstance(self.date.format_iso(), str)
+    
+    def test_add_subtract_methods_signatures(self):
+        """测试add_/subtract_方法签名"""
+        # 所有方法都应该接受整数参数
+        result = self.date.add_days(1)
+        self.assertIsInstance(result, Date)
+        
+        result = self.date.add_months(1)
+        self.assertIsInstance(result, Date)
+        
+        result = self.date.subtract_years(1)
+        self.assertIsInstance(result, Date)
+
+
+class TestAPIDocumentation(unittest.TestCase):
+    """测试API文档字符串"""
+    
+    def setUp(self):
+        """设置测试数据"""
+        self.date = Date('20250415')
+    
+    def test_class_docstring(self):
+        """测试类文档字符串"""
+        self.assertIsNotNone(Date.__doc__)
+        self.assertIn('日期', Date.__doc__)
+    
+    def test_method_docstrings(self):
+        """测试方法文档字符串"""
+        # 检查主要方法的文档字符串
+        methods_to_check = [
+            'from_string', 'to_date_object', 'format_iso', 
+            'get_weekday', 'is_weekend', 'add_days'
+        ]
+        
+        for method_name in methods_to_check:
+            method = getattr(Date, method_name) if hasattr(Date, method_name) else getattr(self.date, method_name)
+            self.assertIsNotNone(method.__doc__, 
+                               f"Method {method_name} missing docstring")
+
+
+class TestAPIEvolution(unittest.TestCase):
+    """测试API演进"""
+    
+    def setUp(self):
+        """设置测试数据"""
+        self.date = Date('20250415')
+        Date.set_log_level(logging.CRITICAL)
+    
+    def test_version_tracking(self):
+        """测试版本跟踪"""
+        # 确保Date类有版本信息
+        self.assertTrue(hasattr(Date, '__version__') or 
+                       hasattr(Date, 'get_version'))
+    
+    def test_deprecation_warnings(self):
+        """测试废弃警告"""
+        # 目前不应该有废弃警告，但可以测试框架是否就位
+        import warnings
+        
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+            
+            # 使用旧方法不应该产生警告（目前保持向后兼容）
+            result = self.date.format('%Y-%m-%d')
+            
+            # 目前不期望有警告
+            deprecation_warnings = [warning for warning in w 
+                                  if issubclass(warning.category, DeprecationWarning)]
+            # 可以为空，因为我们还没有标记任何方法为废弃
+    
+    def test_future_compatibility(self):
+        """测试未来兼容性"""
+        # 确保新API方法都有适当的实现
+        new_methods = [
+            'from_string', 'to_tuple', 'format_iso', 
+            'get_weekday', 'is_weekend', 'add_days'
+        ]
+        
+        for method_name in new_methods:
+            if hasattr(Date, method_name):
+                method = getattr(Date, method_name)
+            else:
+                method = getattr(self.date, method_name)
+            
+            # 方法应该是可调用的
+            self.assertTrue(callable(method))
+            
+            # 方法不应该只是简单的pass或NotImplemented
+            if hasattr(method, '__code__'):
+                # 检查方法体不为空
+                self.assertGreater(method.__code__.co_code.__len__(), 0)
+
+
+if __name__ == '__main__':
+    # 运行所有兼容性测试
+    unittest.main(verbosity=2)