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

staran/tools/date.py

@@ -1,300 +0,0 @@
-#!/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) - 关键字参数
-        """
-        # 默认格式设置
-        self._default_format = '%Y-%m-%d'  # 默认完整日期格式
-        self._input_format_type = 'full'   # 输入格式类型: 'full', 'year_month', 'timestamp', 'today'
-        
-        if not args and not kwargs:
-            # 无参数 - 今日
-            today = datetime.date.today()
-            self.year, self.month, self.day = today.year, today.month, today.day
-            self._input_format_type = 'today'
-            self._default_format = '%Y-%m-%d'
-        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
-            self._input_format_type = 'timestamp'
-            self._default_format = '%Y-%m-%d'
-        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
-            self._input_format_type = 'year_month'
-            self._default_format = '%Y%m'
-        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])
-            self._input_format_type = 'full'
-            self._default_format = '%Y%m%d'
-        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
-            self._input_format_type = 'year_month'
-            self._default_format = '%Y-%m'
-        elif len(args) == 3:
-            self.year, self.month, self.day = args
-            self._input_format_type = 'full'
-            self._default_format = '%Y-%m-%d'
-        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")
-        
-        # 根据是否提供day参数设置格式
-        if 'day' in kwargs:
-            self._input_format_type = 'full'
-            self._default_format = '%Y-%m-%d'
-        else:
-            self._input_format_type = 'year_month'
-            self._default_format = '%Y-%m'
-    
-    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=None):
-        """
-        格式化日期字符串
-        如果不指定格式，使用默认格式（根据输入时的格式确定）
-        """
-        if fmt is None:
-            fmt = self._default_format
-        return self.to_date().strftime(fmt)
-    
-    def format_default(self):
-        """使用默认格式输出（保持输入时的格式风格）"""
-        return self.format()
-    
-    def format_full(self):
-        """完整日期格式: YYYY-MM-DD"""
-        return self.format('%Y-%m-%d')
-    
-    def format_compact(self):
-        """紧凑格式: YYYYMMDD"""
-        return self.format('%Y%m%d')
-    
-    def format_year_month(self):
-        """年月格式: YYYY-MM"""
-        return self.format('%Y-%m')
-    
-    def format_year_month_compact(self):
-        """年月紧凑格式: YYYYMM"""
-        return self.format('%Y%m')
-    
-    def format_chinese(self):
-        """中文格式: YYYY年MM月DD日"""
-        return self.format('%Y年%m月%d日')
-    
-    def format_chinese_short(self):
-        """中文短格式: YYYY年MM月（适用于年月类型）"""
-        if self._input_format_type == 'year_month':
-            return self.format('%Y年%m月')
-        else:
-            return self.format('%Y年%m月%d日')
-    
-    def format_iso(self):
-        """ISO 8601格式: YYYY-MM-DD"""
-        return self.format('%Y-%m-%d')
-    
-    def format_us(self):
-        """美式格式: MM/DD/YYYY"""
-        return self.format('%m/%d/%Y')
-    
-    def format_european(self):
-        """欧式格式: DD/MM/YYYY"""
-        return self.format('%d/%m/%Y')
-    
-    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 get_default_format(self):
-        """获取默认格式字符串"""
-        return self._default_format
-    
-    def get_input_format_type(self):
-        """获取输入格式类型"""
-        return self._input_format_type
-    
-    def set_default_format(self, fmt):
-        """设置新的默认格式"""
-        self._default_format = fmt
-        return self
-    
-    def add_days(self, days):
-        """增加天数，返回新的Date对象，保持原始格式"""
-        new_date = self.to_date() + datetime.timedelta(days=days)
-        result = Date(new_date.year, new_date.month, new_date.day)
-        # 保持原始格式设置
-        result._default_format = self._default_format
-        result._input_format_type = self._input_format_type
-        return result
-    
-    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)
-        
-        result = Date(new_year, new_month, new_day)
-        # 保持原始格式设置
-        result._default_format = self._default_format
-        result._input_format_type = self._input_format_type
-        return result
-    
-    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 self.format_default()
-    
-    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-1.0.0.dist-info/METADATA

@@ -1,301 +0,0 @@
-Metadata-Version: 2.4
-Name: staran
-Version: 1.0.0
-Summary: staran - 轻量级Python日期工具库
-Home-page: https://github.com/starlxa/staran
-Author: StarAn
-Author-email: starlxa@icloud.com
-License: MIT
-Project-URL: Bug Reports, https://github.com/starlxa/staran/issues
-Project-URL: Source, https://github.com/starlxa/staran
-Keywords: date datetime utilities time-processing
-Classifier: Development Status :: 5 - Production/Stable
-Classifier: Intended Audience :: Developers
-Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Classifier: Topic :: Utilities
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.7
-Classifier: Programming Language :: Python :: 3.8
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Operating System :: OS Independent
-Requires-Python: >=3.7
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Dynamic: author
-Dynamic: author-email
-Dynamic: classifier
-Dynamic: description
-Dynamic: description-content-type
-Dynamic: home-page
-Dynamic: keywords
-Dynamic: license
-Dynamic: license-file
-Dynamic: project-url
-Dynamic: requires-python
-Dynamic: summary
-
-# Staran ✨ v1.0.0 - 轻量级Python日期工具库
-
-- 🔧 **完善的包管理** - 优化setup.py配置，专注核心日期功能
-- 🗓️ **智能日期处理** - 支持多种日期格式，自动格式记忆
-- 📅 **灵活日期运算** - 便捷的日期加减运算，保持原格式
-- 🎯 **简洁易用** - 专注日期处理，轻量级设计
-- 🔄 **格式转换** - 支持多种日期格式输出
-- 📦 **零依赖** - 只使用Python标准库，无外部依赖
-
-## 🎯 专为日期处理设计的Python工具库
-
-Staran是一个轻量级的日期处理工具库，提供智能的日期格式记忆和便捷的日期运算功能。特别适合需要处理多种日期格式的应用场景。
-
-## ✨ v1.0.0 新特性
-
-🎉 **稳定版本发布** - 核心功能完备，API稳定
-
-- 🔧 **完善的包管理** - 优化setup.py配置，专注核心功能
-- 📦 **轻量化重构** - 移除非核心模块，专注日期处理
-- 🗓️ **智能格式记忆** - 根据输入自动记住日期格式
-- 📅 **丰富的运算功能** - 支持天数和月数的加减运算
-- 🎯 **零外部依赖** - 只使用Python标准库
-- 🔄 **多种输出格式** - 支持中文、ISO等多种格式输出
-
-## 🚧 v1.1.0 计划中的企业级优化
-
-> **注意：** 当前v1.0.0版本具备完整的核心功能，但在企业工程化标准方面还有提升空间。
-> 我们将在v1.1.0版本中完成以下企业级优化：
-
-### 🔬 **代码质量提升**
-- ✅ **类型注解** - 完整的typing支持和类型检查
-- ✅ **单元测试** - 100%代码覆盖率的测试套件
-- ✅ **文档规范** - 完善的docstring和API文档
-- ✅ **异常处理** - 标准化的异常体系和错误码
-
-### 🏗️ **架构优化**
-- ✅ **性能优化** - 缓存机制和延迟计算
-- ✅ **配置管理** - 支持配置文件和环境变量
-- ✅ **日志系统** - 结构化日志和调试支持
-- ✅ **插件架构** - 可扩展的格式化器和验证器
-
-### 🛡️ **企业级特性**
-- ✅ **输入验证** - 严格的数据验证和清洗
-- ✅ **国际化支持** - 多语言和时区处理
-- ✅ **向后兼容** - API版本管理和迁移指南
-- ✅ **安全考虑** - 输入安全和数据保护
-
-### 📊 **开发体验**
-- ✅ **IDE支持** - 完整的代码提示和自动完成
-- ✅ **调试工具** - 丰富的调试信息和工具
-- ✅ **基准测试** - 性能基准和监控
-- ✅ **CI/CD集成** - 自动化测试和发布流程
-
-## ⚠️ 当前版本限制
-
-v1.0.0是一个功能完备的稳定版本，但请注意以下企业级使用的限制：
-
-### 📝 **代码质量**
-- **类型检查**: 当前缺少typing注解，IDE代码提示可能不完整
-- **测试覆盖**: 没有自动化测试套件，建议在生产环境使用前进行充分测试
-- **异常处理**: 异常信息可能不够详细，调试时需要注意
-
-### 🏗️ **架构限制**
-- **性能**: 没有缓存机制，频繁计算可能影响性能
-- **配置**: 不支持配置文件，所有设置需要在代码中硬编码
-- **日志**: 没有内置日志系统，调试信息有限
-
-### 🛡️ **企业特性**
-- **验证**: 输入验证相对简单，复杂场景可能需要额外验证
-- **国际化**: 目前只支持基本的中文格式，缺少完整的i18n支持
-- **安全**: 没有特殊的安全考虑，输入数据请自行验证
-
-> 💡 **建议**: 如果您需要在企业级生产环境中使用，建议等待v1.1.0版本，或者基于当前版本进行二次开发。
-
-## 🚀 快速开始
-
-### 安装
-```bash
-pip install staran
-```
-
-### 基础用法 - 智能日期处理
-
-```python
-from staran import Date
-
-# 创建日期 - 智能格式记忆
-date1 = Date('202504')      # 输出: 202504 (记住年月格式)
-date2 = Date('20250415')    # 输出: 20250415 (记住完整格式)
-date3 = Date(2025, 4, 15)   # 输出: 2025-04-15
-
-# 日期运算保持格式
-new_date = date1.add_months(2)  # 输出: 202506 (保持YYYYMM格式)
-
-# 多种格式输出
-print(date2.format_chinese())   # 输出: 2025年04月15日
-print(date2.format_iso())       # 输出: 2025-04-15
-```
-
-## 📚 核心功能
-
-### 🗓️ Date类 - 智能日期处理
-
-#### 创建日期对象
-
-```python
-from staran import Date
-
-# 字符串格式（自动识别）
-date1 = Date('2025')        # 年份
-date2 = Date('202504')      # 年月
-date3 = Date('20250415')    # 年月日
-
-# 参数格式
-date4 = Date(2025, 4, 15)   # 年, 月, 日
-date5 = Date(year=2025, month=4, day=15)
-
-# 从datetime对象
-from datetime import datetime
-date6 = Date(datetime.now())
-```
-
-#### 日期运算
-
-```python
-# 加减天数
-tomorrow = date.add_days(1)
-yesterday = date.add_days(-1)
-
-# 加减月数
-next_month = date.add_months(1)
-last_month = date.add_months(-1)
-
-# 月末日期
-month_end = date.month_end()
-
-# 月初日期
-month_start = date.month_start()
-```
-
-#### 格式化输出
-
-```python
-date = Date('20250415')
-
-print(date)                    # 20250415 (保持原格式)
-print(date.format_iso())       # 2025-04-15
-print(date.format_chinese())   # 2025年04月15日
-print(date.format_slash())     # 2025/04/15
-print(date.format_dot())       # 2025.04.15
-```
-
-#### 日期比较
-
-```python
-date1 = Date('20250415')
-date2 = Date('20250416')
-
-print(date1 < date2)    # True
-print(date1 == date2)   # False
-print(date1 > date2)    # False
-```
-
-## 🎯 特色功能
-
-### 智能格式记忆
-
-Date类会根据输入格式自动选择默认输出格式：
-
-```python
-# 年月格式 - 输出保持YYYYMM
-date_ym = Date('202504')
-print(date_ym)                    # 202504
-print(date_ym.add_months(1))      # 202505
-
-# 完整格式 - 输出保持YYYYMMDD
-date_full = Date('20250415')
-print(date_full)                  # 20250415
-print(date_full.add_days(1))      # 20250416
-```
-
-### 灵活的日期运算
-
-```python
-date = Date('202504')
-
-# 月份运算
-print(date.add_months(3))    # 202507
-print(date.add_months(-2))   # 202502
-
-# 季度运算
-print(date.add_months(3))    # 下一季度
-
-# 年份运算
-print(date.add_months(12))   # 明年同月
-```
-
-## 🛠️ 高级用法
-
-### 批量日期处理
-
-```python
-from staran import Date
-
-# 生成日期序列
-start_date = Date('202501')
-dates = []
-for i in range(12):
-    dates.append(start_date.add_months(i))
-
-print(dates)  # ['202501', '202502', ..., '202512']
-```
-
-### 与datetime互操作
-
-```python
-from staran import Date
-from datetime import datetime
-
-# Date转datetime
-date = Date('20250415')
-dt = date.to_datetime()
-
-# datetime转Date
-dt = datetime.now()
-date = Date(dt)
-```
-
-## 📋 API参考
-
-### Date类方法
-
-| 方法 | 描述 | 示例 |
-|------|------|------|
-| `Date(input)` | 创建日期对象 | `Date('202504')` |
-| `add_days(n)` | 加减天数 | `date.add_days(7)` |
-| `add_months(n)` | 加减月数 | `date.add_months(2)` |
-| `month_start()` | 获取月初 | `date.month_start()` |
-| `month_end()` | 获取月末 | `date.month_end()` |
-| `format_iso()` | ISO格式 | `date.format_iso()` |
-| `format_chinese()` | 中文格式 | `date.format_chinese()` |
-| `format_slash()` | 斜杠格式 | `date.format_slash()` |
-| `format_dot()` | 点分格式 | `date.format_dot()` |
-| `to_datetime()` | 转datetime | `date.to_datetime()` |
-
-## 🤝 贡献
-
-欢迎提交Issues和Pull Requests！
-
-## 📄 许可证
-
-MIT License - 详见 [LICENSE](LICENSE) 文件。
-
-## 🔗 链接
-
-- [GitHub仓库](https://github.com/starlxa/staran)
-- [PyPI包页面](https://pypi.org/project/staran/)
-- [问题反馈](https://github.com/starlxa/staran/issues)
-
----
-
-**Staran** - 让日期处理变得简单而优雅 ✨

staran-1.0.0.dist-info/RECORD

@@ -1,8 +0,0 @@
-staran/__init__.py,sha256=G8Kfqho5-4yN_2WS7xkRa63C0AdDS4OQTWRMLtVnypw,208
-staran/tools/__init__.py,sha256=4R2WpIlVtR0_QZL2eB5AcwlKffNc0z1V-YIg1lk8xYA,1061
-staran/tools/date.py,sha256=-QyEMWVx6czMuOIwcV7kR3gBMRVOwb5qevo7GEFSJKE,10488
-staran-1.0.0.dist-info/licenses/LICENSE,sha256=2EmsBIyDCono4iVXNpv5_px9qt2b7hfPq1WuyGVMNP4,1361
-staran-1.0.0.dist-info/METADATA,sha256=bnl3wnJe3bVEpCfEC6SwBv7-1BRicwIgf9RTFUCqdOw,8862
-staran-1.0.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-staran-1.0.0.dist-info/top_level.txt,sha256=NOUZtXSh5oSIEjHrC0lQ9WmoKtD010Q00dghWyag-Zs,7
-staran-1.0.0.dist-info/RECORD,,