staran 0.1.0__py3-none-any.whl → 0.1.1__py3-none-any.whl

staran-0.1.1.dist-info/METADATA

@@ -0,0 +1,225 @@
+Metadata-Version: 2.4
+Name: staran
+Version: 0.1.1
+Summary: staran - 高性能Python工具库
+Home-page: https://github.com/starlxa/staran
+Author: StarAn
+Author-email: starlxa@icloud.com
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.20
+Requires-Dist: pandas
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# Staran - 简化的Python日期工具库
+
+## 📅 简洁高效的日期处理
+
+Staran是一个基于Python标准库的简洁日期工具库，提供直观易用的API，无需复杂依赖。
+
+## 🚀 快速开始
+
+### 安装
+```bash
+pip install staran
+```
+
+### 基本使用
+
+```python
+from staran import Date, today, from_string
+
+# 创建日期
+today_date = today()                    # 今日
+birthday = Date(1990, 5, 15)           # 指定日期
+event = from_string('20240615')        # 从字符串
+
+print(f"今天是: {today_date}")
+print(f"生日: {birthday}")
+print(f"活动日期: {event}")
+```
+
+## 📖 功能特性
+
+### 1. 多种创建方式
+```python
+from tools.date import Date
+
+# 方式1: 无参数 - 今日
+today = Date()
+
+# 方式2: 指定年月日
+birthday = Date(1990, 5, 15)
+
+# 方式3: 从字符串
+event1 = Date('20240615')      # YYYYMMDD
+event2 = Date('2024-06-15')    # 带分隔符
+monthly = Date('202406')       # YYYYMM (日期默认为1号)
+
+# 方式4: 关键字参数
+deadline = Date(year=2024, month=12, day=31)
+```
+
+### 2. 日期运算
+```python
+date = Date(2024, 6, 15)
+
+# 加减天数
+tomorrow = date.add_days(1)
+last_week = date.add_days(-7)
+
+# 加减月份
+next_month = date.add_months(1)
+last_year = date.add_months(-12)
+
+# 计算日期差
+diff_days = date.difference(Date(2024, 6, 1))  # 14天
+```
+
+### 3. 格式化和转换
+```python
+date = Date(2024, 6, 15)
+
+# 格式化
+print(date.format('%Y-%m-%d'))      # 2024-06-15
+print(date.format('%Y年%m月%d日'))   # 2024年06月15日
+
+# 转换
+timestamp = date.to_timestamp()     # 时间戳
+dt_date = date.to_date()           # datetime.date对象
+dt_datetime = date.to_datetime()    # datetime.datetime对象
+```
+
+### 4. 日期信息
+```python
+date = Date(2024, 6, 15)
+
+# 基本信息
+print(f"是否闰年: {date.is_leap_year()}")      # False
+print(f"星期几: {date.weekday()}")              # 5 (Saturday)
+print(f"当月天数: {date.days_in_month()}")      # 30
+print(f"当年天数: {date.days_in_year()}")       # 365
+```
+
+### 5. 日期比较
+```python
+date1 = Date(2024, 6, 15)
+date2 = Date(2024, 6, 16)
+
+print(date1 < date2)   # True
+print(date1 == Date(2024, 6, 15))  # True
+print(date1 >= date2)  # False
+```
+
+## 🎯 设计理念
+
+### 简洁性
+- 基于Python标准库，无额外依赖
+- 直观的API设计
+- 清晰的错误消息
+
+### 可靠性
+- 完整的日期验证
+- 处理边界情况（如闰年、月末）
+- 标准的Python对象行为
+
+### 实用性
+- 支持常见的日期操作
+- 灵活的创建方式
+- 便捷的格式化选项
+
+## 📁 项目结构
+
+```
+staran/
+├── __init__.py                # 主包入口
+├── setup.py                  # 安装配置
+├── LICENSE                   # MIT许可证
+├── README.md                 # 本文档
+├── test_simple.py            # 功能测试
+└── tools/                    # 核心模块
+    ├── __init__.py           # 工具模块入口
+    └── date/                 # 日期功能
+        ├── __init__.py       # 日期模块入口
+        └── date.py           # Date类实现
+```
+
+## 🧪 测试
+
+```bash
+# 运行测试
+python test_simple.py
+```
+
+预期输出：
+```
+📅 简化Date类测试
+==============================
+1. 基本创建:
+   今日: 2025-07-28
+   指定日期: 2024-06-15
+   从字符串: 2024-06-15
+
+2. 日期操作:
+   明天: 2025-07-29
+   下月: 2025-08-28
+
+3. 时间戳转换:
+   2024-06-15 时间戳: 1718380800.0
+
+4. 格式化:
+   格式化: 2024年06月15日
+
+5. 日期比较:
+   2024-06-15 < 2024-06-16: True
+   2024-06-15 == Date(2024, 6, 15): True
+
+✅ 所有测试通过!
+```
+
+## 📋 API参考
+
+### Date类
+
+#### 构造方法
+- `Date()` - 创建今日日期
+- `Date(year, month, day)` - 指定年月日
+- `Date(date_string)` - 从字符串创建
+- `Date(year=y, month=m, day=d)` - 关键字参数
+
+#### 核心方法
+- `add_days(days)` - 增加/减少天数
+- `add_months(months)` - 增加/减少月数
+- `difference(other)` - 计算日期差
+- `format(fmt)` - 格式化字符串
+- `to_timestamp()` - 转换为时间戳
+- `is_leap_year()` - 判断闰年
+
+#### 便捷函数
+- `today()` - 获取今日
+- `from_string(s)` - 从字符串创建
+- `from_timestamp(ts)` - 从时间戳创建
+
+## 📄 许可证
+
+MIT License - 详见 [LICENSE](LICENSE) 文件
+
+## 🤝 贡献
+
+欢迎提交Issue和Pull Request！
+
+---
+
+**Staran** - 让日期处理变得简单 🌟

staran-0.1.1.dist-info/RECORD

@@ -0,0 +1,7 @@
+staran-0.1.1.dist-info/licenses/LICENSE,sha256=2EmsBIyDCono4iVXNpv5_px9qt2b7hfPq1WuyGVMNP4,1361
+tools/__init__.py,sha256=FHWxsrVTBYoqcZaMgbZacRbDZWliqUN8gsS4F0I_rDQ,348
+tools/date.py,sha256=UNydI8UyxgjcI1FTnLe0efPK_W6xE_xzgo1bhPU4xNM,7181
+staran-0.1.1.dist-info/METADATA,sha256=NshFvN_VxcTDDsATq7NQ7KESKdEzXX_pIo705s1tHgg,5046
+staran-0.1.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+staran-0.1.1.dist-info/top_level.txt,sha256=Ib4ZA2MPBpiT0tC-0qt5RcP9g42gLddRbx9PiYGa-Fc,6
+staran-0.1.1.dist-info/RECORD,,

tools/__init__.py

@@ -2,69 +2,19 @@
 # -*- coding: utf-8 -*-
 
 """
-Staran Tools - 高性能工具集合
-包含日期处理等各种实用工具
+Staran Tools - 简化的工具集合
+提供日期处理等实用功能
 """
 
 # 导入date模块的主要类和函数
-from .date import (
-    Date,
-    get_today,
-    date_to_timestamp,
-    days_between,
-    is_leap_year_c,
-    has_c_extension,
-    get_platform_info,
-    PlatformDateUtils,
-    create_date,
-    today,
-    from_string,
-    from_timestamp
-)
-
-# 为了向后兼容，也可以通过time模块访问
-from . import date as date_module
+from .date import Date
 
 # 主要导出
 __all__ = [
-    # 核心类
-    'Date',
-    'PlatformDateUtils',
-    
-    # 核心函数
-    'get_today',
-    'date_to_timestamp', 
-    'days_between',
-    'is_leap_year_c',
-    'has_c_extension',
-    'get_platform_info',
-    
-    # 便捷函数
-    'create_date',
-    'today',
-    'from_string',
-    'from_timestamp',
-    
-    # 子模块
-    'date_module'
+    'Date'
 ]
 
 # 模块信息
 __version__ = '1.0.0'
 __author__ = 'Staran Team'
-__description__ = 'Staran high-performance tools collection'
-
-# 模块级便捷函数
-def get_module_info():
-    """获取tools模块信息"""
-    return {
-        'version': __version__,
-        'author': __author__,
-        'description': __description__,
-        'available_modules': ['date'],
-        'date_c_extension': has_c_extension()
-    }
-
-# 显示加载信息
-print(f"🚀 Staran Tools v{__version__} 已加载")
-print(f"   📅 Date模块: {'C扩展' if has_c_extension() else 'Python实现'}")
+__description__ = 'Staran simple tools collection'

tools/date.py

@@ -0,0 +1,207 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+"""
+简化的Date类 - 纯Python实现
+使用datetime包提供日期处理功能
+"""
+
+import datetime
+import calendar
+import re
+
+class Date:
+    """简化的日期类，基于Python datetime实现"""
+    
+    def __init__(self, *args, **kwargs):
+        """
+        初始化日期对象
+        支持多种创建方式：
+        - Date() - 今日
+        - Date(year, month, day) - 指定日期
+        - Date('20240615') - 从字符串
+        - Date(year=2024, month=6, day=15) - 关键字参数
+        """
+        if not args and not kwargs:
+            # 无参数 - 今日
+            today = datetime.date.today()
+            self.year, self.month, self.day = today.year, today.month, today.day
+        elif len(args) == 1 and isinstance(args[0], str):
+            # 字符串参数
+            self._init_from_string(args[0])
+        elif len(args) == 1 and isinstance(args[0], int):
+            # 单个整数参数 - 视为时间戳
+            dt = datetime.datetime.fromtimestamp(args[0])
+            self.year, self.month, self.day = dt.year, dt.month, dt.day
+        elif len(args) in [2, 3]:
+            # 位置参数
+            self._init_from_args(args)
+        elif kwargs:
+            # 关键字参数
+            self._init_from_kwargs(kwargs)
+        else:
+            raise ValueError("Invalid arguments for Date initialization")
+        
+        # 验证日期有效性
+        self._validate_date()
+    
+    def _init_from_string(self, date_string):
+        """从字符串初始化日期"""
+        # 移除所有分隔符
+        clean_string = re.sub(r'[^\d]', '', date_string)
+        
+        if len(clean_string) == 6:  # YYYYMM
+            self.year = int(clean_string[:4])
+            self.month = int(clean_string[4:6])
+            self.day = 1
+        elif len(clean_string) == 8:  # YYYYMMDD
+            self.year = int(clean_string[:4])
+            self.month = int(clean_string[4:6])
+            self.day = int(clean_string[6:8])
+        else:
+            raise ValueError(f"Date string must be 6 (YYYYMM) or 8 (YYYYMMDD) digits after removing separators, got {len(clean_string)}")
+    
+    def _init_from_args(self, args):
+        """从位置参数初始化日期"""
+        if len(args) == 2:
+            self.year, self.month = args
+            self.day = 1
+        elif len(args) == 3:
+            self.year, self.month, self.day = args
+        else:
+            raise ValueError("Expected 2 or 3 positional arguments")
+    
+    def _init_from_kwargs(self, kwargs):
+        """从关键字参数初始化日期"""
+        self.year = kwargs.get('year')
+        self.month = kwargs.get('month')
+        self.day = kwargs.get('day', 1)
+        
+        if self.year is None or self.month is None:
+            raise ValueError("year and month are required")
+    
+    def _validate_date(self):
+        """验证日期有效性"""
+        if not isinstance(self.year, int) or self.year <= 0:
+            raise ValueError(f"Year must be positive, got {self.year}")
+        
+        if not isinstance(self.month, int) or not (1 <= self.month <= 12):
+            raise ValueError(f"Month must be between 1 and 12, got {self.month}")
+        
+        if not isinstance(self.day, int) or self.day <= 0:
+            raise ValueError(f"Day must be positive, got {self.day}")
+        
+        # 检查日期是否在该月的有效范围内
+        max_day = calendar.monthrange(self.year, self.month)[1]
+        if self.day > max_day:
+            raise ValueError(f"Day {self.day} is invalid for {self.year}-{self.month:02d}")
+    
+    def to_timestamp(self):
+        """转换为时间戳"""
+        dt = datetime.datetime.combine(
+            datetime.date(self.year, self.month, self.day),
+            datetime.time()
+        )
+        return dt.timestamp()
+    
+    def to_date(self):
+        """转换为Python datetime.date对象"""
+        return datetime.date(self.year, self.month, self.day)
+    
+    def to_datetime(self):
+        """转换为Python datetime.datetime对象"""
+        return datetime.datetime(self.year, self.month, self.day)
+    
+    def format(self, fmt='%Y-%m-%d'):
+        """格式化日期字符串"""
+        return self.to_date().strftime(fmt)
+    
+    def weekday(self):
+        """返回星期几（0=Monday, 6=Sunday）"""
+        return self.to_date().weekday()
+    
+    def isoweekday(self):
+        """返回星期几（1=Monday, 7=Sunday）"""
+        return self.to_date().isoweekday()
+    
+    def is_leap_year(self):
+        """判断是否为闰年"""
+        return calendar.isleap(self.year)
+    
+    def days_in_month(self):
+        """返回当月天数"""
+        return calendar.monthrange(self.year, self.month)[1]
+    
+    def days_in_year(self):
+        """返回当年天数"""
+        return 366 if self.is_leap_year() else 365
+    
+    def add_days(self, days):
+        """增加天数，返回新的Date对象"""
+        new_date = self.to_date() + datetime.timedelta(days=days)
+        return Date(new_date.year, new_date.month, new_date.day)
+    
+    def add_months(self, months):
+        """增加月数，返回新的Date对象"""
+        new_month = self.month + months
+        new_year = self.year
+        
+        while new_month > 12:
+            new_month -= 12
+            new_year += 1
+        while new_month < 1:
+            new_month += 12
+            new_year -= 1
+        
+        # 处理日期溢出（如1月31日+1个月=2月28/29日）
+        max_day = calendar.monthrange(new_year, new_month)[1]
+        new_day = min(self.day, max_day)
+        
+        return Date(new_year, new_month, new_day)
+    
+    def difference(self, other):
+        """计算与另一个日期的天数差"""
+        if not isinstance(other, Date):
+            raise TypeError("Expected Date object")
+        
+        date1 = self.to_date()
+        date2 = other.to_date()
+        return (date1 - date2).days
+    
+    def __str__(self):
+        """字符串表示"""
+        return f"{self.year}-{self.month:02d}-{self.day:02d}"
+    
+    def __repr__(self):
+        """调试表示"""
+        return f"Date({self.year}, {self.month}, {self.day})"
+    
+    def __eq__(self, other):
+        """相等比较"""
+        if not isinstance(other, Date):
+            return False
+        return (self.year, self.month, self.day) == (other.year, other.month, other.day)
+    
+    def __lt__(self, other):
+        """小于比较"""
+        if not isinstance(other, Date):
+            return NotImplemented
+        return (self.year, self.month, self.day) < (other.year, other.month, other.day)
+    
+    def __le__(self, other):
+        """小于等于比较"""
+        return self < other or self == other
+    
+    def __gt__(self, other):
+        """大于比较"""
+        if not isinstance(other, Date):
+            return NotImplemented
+        return (self.year, self.month, self.day) > (other.year, other.month, other.day)
+    
+    def __ge__(self, other):
+        """大于等于比较"""
+        return self > other or self == other
+    
+    def __hash__(self):
+        """哈希值"""
+        return hash((self.year, self.month, self.day))

staran-0.1.0.dist-info/METADATA

@@ -1,26 +0,0 @@
-Metadata-Version: 2.4
-Name: staran
-Version: 0.1.0
-Summary: A short description of your package
-Home-page: https://github.com/starlxa/staran
-Author: StarAn
-Author-email: starlxa@icloud.com
-Classifier: Programming Language :: Python :: 3
-Classifier: License :: OSI Approved :: MIT License
-Requires-Python: >=3.7
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: numpy>=1.20
-Requires-Dist: pandas
-Dynamic: author
-Dynamic: author-email
-Dynamic: classifier
-Dynamic: description
-Dynamic: description-content-type
-Dynamic: home-page
-Dynamic: license-file
-Dynamic: requires-dist
-Dynamic: requires-python
-Dynamic: summary
-
-## STARAN TOOL

staran-0.1.0.dist-info/RECORD

@@ -1,26 +0,0 @@
-._staran-0.1.0.dist-info,sha256=3_uwfdZqkY0vpvvPcxyU7-uCuMfSkGWarTVY5AY-mtg,4096
-._tools,sha256=3_uwfdZqkY0vpvvPcxyU7-uCuMfSkGWarTVY5AY-mtg,4096
-staran-0.1.0.dist-info/licenses/._LICENSE,sha256=3_uwfdZqkY0vpvvPcxyU7-uCuMfSkGWarTVY5AY-mtg,4096
-staran-0.1.0.dist-info/licenses/LICENSE,sha256=2EmsBIyDCono4iVXNpv5_px9qt2b7hfPq1WuyGVMNP4,1361
-tools/.___init__.py,sha256=3_uwfdZqkY0vpvvPcxyU7-uCuMfSkGWarTVY5AY-mtg,4096
-tools/._date,sha256=3_uwfdZqkY0vpvvPcxyU7-uCuMfSkGWarTVY5AY-mtg,4096
-tools/__init__.py,sha256=EfuYgERy0MGLzOrniACgZFc4r_ODDcMl9FAvl0h5b_8,1451
-tools/date/.___init__.py,sha256=3_uwfdZqkY0vpvvPcxyU7-uCuMfSkGWarTVY5AY-mtg,4096
-tools/date/._build_simple.py,sha256=3_uwfdZqkY0vpvvPcxyU7-uCuMfSkGWarTVY5AY-mtg,4096
-tools/date/._date.py,sha256=3_uwfdZqkY0vpvvPcxyU7-uCuMfSkGWarTVY5AY-mtg,4096
-tools/date/._platform_utils.py,sha256=3_uwfdZqkY0vpvvPcxyU7-uCuMfSkGWarTVY5AY-mtg,4096
-tools/date/__init__.py,sha256=pC-SxWTrimjy2cSzwm-zkcV2b3Kg3zqWkJrNaehFXjA,1370
-tools/date/build_simple.py,sha256=ImbpceY3DRY4mAodJtN8RazmVAlhZ5_Lly-dujIa_qs,3006
-tools/date/date.py,sha256=-T_8NSUyEb5Ww3wHeM6h9BvWP7djzZk3NdryYqpz4uE,28552
-tools/date/platform_utils.py,sha256=FVQ_YT4J_EG80pwHFnJn1Ijgc-VYBZJMQq9tT41WS0w,6911
-staran-0.1.0.dist-info/._METADATA,sha256=3_uwfdZqkY0vpvvPcxyU7-uCuMfSkGWarTVY5AY-mtg,4096
-staran-0.1.0.dist-info/._PKG-INFO,sha256=3_uwfdZqkY0vpvvPcxyU7-uCuMfSkGWarTVY5AY-mtg,4096
-staran-0.1.0.dist-info/._SOURCES.txt,sha256=3_uwfdZqkY0vpvvPcxyU7-uCuMfSkGWarTVY5AY-mtg,4096
-staran-0.1.0.dist-info/._WHEEL,sha256=3_uwfdZqkY0vpvvPcxyU7-uCuMfSkGWarTVY5AY-mtg,4096
-staran-0.1.0.dist-info/._licenses,sha256=3_uwfdZqkY0vpvvPcxyU7-uCuMfSkGWarTVY5AY-mtg,4096
-staran-0.1.0.dist-info/._requires.txt,sha256=3_uwfdZqkY0vpvvPcxyU7-uCuMfSkGWarTVY5AY-mtg,4096
-staran-0.1.0.dist-info/._top_level.txt,sha256=3_uwfdZqkY0vpvvPcxyU7-uCuMfSkGWarTVY5AY-mtg,4096
-staran-0.1.0.dist-info/METADATA,sha256=hy7Zw4GbAqRX2nOMjSI5bxOCzDIyXASZ-TkeIAjGMOQ,656
-staran-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-staran-0.1.0.dist-info/top_level.txt,sha256=Ib4ZA2MPBpiT0tC-0qt5RcP9g42gLddRbx9PiYGa-Fc,6
-staran-0.1.0.dist-info/RECORD,,

tools/date/__init__.py

@@ -1,60 +0,0 @@
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-
-"""
-Date模块 - 高性能日期处理工具
-支持C扩展加速和跨平台兼容
-"""
-
-from .date import Date
-from .platform_utils import (
-    get_today,
-    date_to_timestamp, 
-    days_between,
-    is_leap_year_c,
-    has_c_extension,
-    get_platform_info,
-    PlatformDateUtils
-)
-
-# 导出主要类和函数
-__all__ = [
-    'Date',
-    'get_today',
-    'date_to_timestamp',
-    'days_between', 
-    'is_leap_year_c',
-    'has_c_extension',
-    'get_platform_info',
-    'PlatformDateUtils'
-]
-
-# 模块信息
-__version__ = '1.0.0'
-__author__ = 'Staran Team'
-__description__ = 'High-performance date processing with C extension support'
-
-# 便捷访问
-def create_date(*args, **kwargs):
-    """便捷的日期创建函数"""
-    return Date(*args, **kwargs)
-
-def today():
-    """快速获取今日日期"""
-    return Date()
-
-def from_string(date_string):
-    """从字符串创建日期"""
-    return Date(date_string)
-
-def from_timestamp(timestamp):
-    """从时间戳创建日期（需要先实现该功能）"""
-    import datetime
-    dt = datetime.datetime.fromtimestamp(timestamp)
-    return Date(dt.year, dt.month, dt.day)
-
-# 检查C扩展状态并显示信息
-if has_c_extension():
-    print("✅ Date模块已加载，C扩展可用")
-else:
-    print("⚠️  Date模块已加载，使用Python备用实现")