staran 0.1.1__tar.gz → 0.1.3__tar.gz

staran-0.1.3/PKG-INFO

@@ -0,0 +1,140 @@
+Metadata-Version: 2.4
+Name: staran
+Version: 0.1.3
+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: datetime
+Requires-Dist: calendar
+Requires-Dist: re
+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工具库
+
+## � 轻量级Python实用工具集
+
+Staran是一个基于Python标准库的实用工具库，提供日期处理等常用功能，无需复杂依赖。
+
+## 🚀 快速开始
+
+### 安装
+```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格式)
+```
+
+## 📖 主要功能
+
+### 1. 智能格式记忆
+Date类会根据输入格式自动设置默认输出格式：
+
+| 输入方式 | 默认输出 | 说明 |
+|---------|---------|------|
+| `Date('202504')` | `202504` | 年月紧凑格式 |
+| `Date('20250415')` | `20250415` | 完整紧凑格式 |
+| `Date(2025, 4)` | `2025-04` | 年月格式 |
+| `Date(2025, 4, 15)` | `2025-04-15` | 完整格式 |
+
+### 2. 多种输出格式
+```python
+date = Date('202504')
+
+# 默认格式（保持输入风格）
+print(date)                         # 202504
+
+# 常用格式
+print(date.format_full())          # 2025-04-01
+print(date.format_chinese())       # 2025年04月01日
+print(date.format_year_month())    # 2025-04
+print(date.format_compact())       # 20250401
+```
+
+### 3. 日期运算
+```python
+date = Date('202504')
+
+# 运算后保持原格式
+next_month = date.add_months(1)     # 202505
+tomorrow = date.add_days(1)         # 202504 (智能处理)
+
+# 日期差计算
+diff = date.difference(Date('202502'))  # 天数差
+```
+
+### 4. 基本信息
+```python
+date = Date(2024, 2, 29)
+print(date.is_leap_year())          # True
+print(date.weekday())               # 星期几
+print(date.days_in_month())         # 当月天数
+```
+
+## 🎯 设计特色
+
+- **格式智能** - 自动记忆输入格式，保持输出一致性
+- **零依赖** - 仅基于Python标准库
+- **直观API** - 符合Python习惯的设计
+- **类型安全** - 完整的参数验证和错误处理
+
+## 📁 项目结构
+
+```
+staran/
+├── __init__.py           # 主包入口，包含使用示例
+├── tools/
+│   ├── __init__.py      # 工具模块
+│   └── date.py          # Date类实现
+├── setup.py             # 安装配置  
+└── README.md            # 本文档
+```
+
+## 🧪 快速测试
+
+```python
+from staran import Date
+
+# 测试格式记忆
+date = Date('202504')
+print(f"原始: {date}")                    # 202504
+print(f"加2月: {date.add_months(2)}")     # 202506
+
+# 测试多格式输出
+print(f"中文: {date.format_chinese()}")   # 2025年04月01日
+print(f"完整: {date.format_full()}")      # 2025-04-01
+```
+
+## 📄 许可证
+
+MIT License
+
+---
+
+**Staran** - 让Python工具使用更简单 🌟

staran-0.1.3/README.md

@@ -0,0 +1,114 @@
+# Staran - 简化的Python工具库
+
+## � 轻量级Python实用工具集
+
+Staran是一个基于Python标准库的实用工具库，提供日期处理等常用功能，无需复杂依赖。
+
+## 🚀 快速开始
+
+### 安装
+```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格式)
+```
+
+## 📖 主要功能
+
+### 1. 智能格式记忆
+Date类会根据输入格式自动设置默认输出格式：
+
+| 输入方式 | 默认输出 | 说明 |
+|---------|---------|------|
+| `Date('202504')` | `202504` | 年月紧凑格式 |
+| `Date('20250415')` | `20250415` | 完整紧凑格式 |
+| `Date(2025, 4)` | `2025-04` | 年月格式 |
+| `Date(2025, 4, 15)` | `2025-04-15` | 完整格式 |
+
+### 2. 多种输出格式
+```python
+date = Date('202504')
+
+# 默认格式（保持输入风格）
+print(date)                         # 202504
+
+# 常用格式
+print(date.format_full())          # 2025-04-01
+print(date.format_chinese())       # 2025年04月01日
+print(date.format_year_month())    # 2025-04
+print(date.format_compact())       # 20250401
+```
+
+### 3. 日期运算
+```python
+date = Date('202504')
+
+# 运算后保持原格式
+next_month = date.add_months(1)     # 202505
+tomorrow = date.add_days(1)         # 202504 (智能处理)
+
+# 日期差计算
+diff = date.difference(Date('202502'))  # 天数差
+```
+
+### 4. 基本信息
+```python
+date = Date(2024, 2, 29)
+print(date.is_leap_year())          # True
+print(date.weekday())               # 星期几
+print(date.days_in_month())         # 当月天数
+```
+
+## 🎯 设计特色
+
+- **格式智能** - 自动记忆输入格式，保持输出一致性
+- **零依赖** - 仅基于Python标准库
+- **直观API** - 符合Python习惯的设计
+- **类型安全** - 完整的参数验证和错误处理
+
+## 📁 项目结构
+
+```
+staran/
+├── __init__.py           # 主包入口，包含使用示例
+├── tools/
+│   ├── __init__.py      # 工具模块
+│   └── date.py          # Date类实现
+├── setup.py             # 安装配置  
+└── README.md            # 本文档
+```
+
+## 🧪 快速测试
+
+```python
+from staran import Date
+
+# 测试格式记忆
+date = Date('202504')
+print(f"原始: {date}")                    # 202504
+print(f"加2月: {date.add_months(2)}")     # 202506
+
+# 测试多格式输出
+print(f"中文: {date.format_chinese()}")   # 2025年04月01日
+print(f"完整: {date.format_full()}")      # 2025-04-01
+```
+
+## 📄 许可证
+
+MIT License
+
+---
+
+**Staran** - 让Python工具使用更简单 🌟

{staran-0.1.1 → staran-0.1.3}/setup.py

@@ -2,17 +2,18 @@ from setuptools import setup, find_packages
 
 setup(
     name='staran',
-    version='0.1.1',
+    version='0.1.3',
     description='staran - 高性能Python工具库',
     long_description=open('README.md', encoding='utf-8').read(),
     long_description_content_type='text/markdown',
     author='StarAn',
     author_email='starlxa@icloud.com',
     url='https://github.com/starlxa/staran',
-    packages=find_packages(),
+    packages=['staran', 'staran.tools'],
     install_requires=[
-        'numpy>=1.20',
-        'pandas'
+        'datetime',
+        'calendar',
+        're',
     ],
     classifiers=[
         'Programming Language :: Python :: 3',

staran-0.1.3/staran/__init__.py

@@ -0,0 +1,143 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+"""
+Staran - 简化的Python工具库
+=========================
+
+基于Python标准库的轻量级实用工具集，提供日期处理等常用功能。
+
+主要特性：
+- 零依赖：仅基于Python标准库
+- 智能格式：自动记忆输入格式并保持一致性
+- 直观API：符合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 (保持原格式)
+
+多种输出格式::
+
+    date = Date('202504')
+    
+    print(date)                     # 202504 (默认格式)
+    print(date.format_full())      # 2025-04-01
+    print(date.format_chinese())   # 2025年04月01日
+    print(date.format_compact())   # 20250401
+
+日期运算::
+
+    date = Date(2025, 4, 15)
+    
+    # 日期运算
+    tomorrow = date.add_days(1)     # 2025-04-16
+    next_month = date.add_months(1) # 2025-05-15
+    
+    # 日期比较
+    other = Date(2025, 4, 20)
+    diff = other.difference(date)   # 5 (天数差)
+    print(date < other)             # True
+
+创建方式::
+
+    # 多种创建方式
+    today = Date()                  # 今日
+    birthday = Date(1990, 5, 15)    # 指定日期
+    event = Date('20240615')        # 从字符串
+    deadline = Date(year=2024, month=12, day=31)  # 关键字参数
+
+格式化选项::
+
+    date = Date('202504')
+    
+    # 常用格式
+    date.format_default()           # 202504 (默认)
+    date.format_full()              # 2025-04-01 (完整)
+    date.format_year_month()        # 2025-04 (年月)
+    date.format_chinese()           # 2025年04月01日 (中文)
+    date.format_iso()               # 2025-04-01 (ISO)
+    date.format_us()                # 04/01/2025 (美式)
+    date.format_european()          # 01/04/2025 (欧式)
+
+核心功能：
+---------
+- Date: 智能日期类，支持格式记忆和多种输出
+- 日期运算：add_days(), add_months()
+- 格式化：多种预设格式方法
+- 比较：支持标准比较操作符
+- 转换：to_timestamp(), to_date(), to_datetime()
+- 信息：is_leap_year(), weekday(), days_in_month()
+
+版本信息：
+---------
+- 版本: 1.0.0
+- 许可: MIT
+- 作者: Staran Team
+"""
+
+# 导入主要功能
+from .tools import Date
+
+# 主要导出
+__all__ = [
+    'Date'
+]
+
+# 包信息
+__version__ = '1.0.0'
+__author__ = 'Staran Team'
+__description__ = 'Simple Python utilities with smart format memory'
+__license__ = 'MIT'
+
+# 便捷函数示例
+def help_examples():
+    """
+    显示Staran使用示例
+    
+    Returns:
+        None: 打印示例到控制台
+    """
+    print("""
+Staran 使用示例
+===============
+
+1. 基本创建：
+   from staran import Date
+   
+   date1 = Date('202504')      # 202504
+   date2 = Date('20250415')    # 20250415  
+   date3 = Date(2025, 4, 15)   # 2025-04-15
+
+2. 格式保持：
+   date = Date('202504')
+   new_date = date.add_months(2)  # 202506 (保持格式)
+
+3. 多种格式：
+   date.format_full()         # 2025-04-01
+   date.format_chinese()      # 2025年04月01日
+   date.format_compact()      # 20250401
+
+4. 日期运算：
+   date.add_days(30)          # 增加30天
+   date.add_months(2)         # 增加2个月
+   date.difference(other)     # 计算天数差
+
+更多信息请查看: help(Date)
+    """)
+
+# 快捷访问帮助
+def examples():
+    """显示使用示例的快捷方法"""
+    help_examples()

staran-0.1.3/staran/tools/__init__.py

@@ -0,0 +1,43 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+"""
+Staran Tools - 工具集合模块
+==========================
+
+提供各种实用工具类和函数：
+
+Date类 - 智能日期处理：
+- 格式记忆：根据输入自动设置默认格式
+- 多种创建方式：支持字符串、参数、关键字等
+- 丰富格式化：提供多种预设输出格式
+- 日期运算：支持天数、月数的加减运算
+- 标准比较：支持日期间的比较操作
+
+示例::
+
+    from staran.tools import Date
+    
+    # 创建日期
+    date = Date('202504')       # 自动记住YYYYMM格式
+    full_date = Date('20250415') # 自动记住YYYYMMDD格式
+    
+    # 运算保持格式
+    next_month = date.add_months(1)  # 输出: 202505
+    
+    # 多种格式输出
+    print(date.format_chinese())     # 2025年04月01日
+"""
+
+# 导入date模块的主要类和函数
+from .date import Date
+
+# 主要导出
+__all__ = [
+    'Date'
+]
+
+# 模块信息
+__version__ = '1.0.0'
+__author__ = 'Staran Team'
+__description__ = 'Staran utilities with smart format memory'

{staran-0.1.1 → staran-0.1.3/staran}/tools/date.py

@@ -22,10 +22,16 @@ class Date:
         - 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])
@@ -33,6 +39,8 @@ class Date:
             # 单个整数参数 - 视为时间戳
             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)
@@ -54,10 +62,14 @@ class Date:
             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)}")
     
@@ -66,8 +78,12 @@ class Date:
         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")
     
@@ -79,6 +95,14 @@ class Date:
         
         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):
         """验证日期有效性"""
@@ -112,10 +136,58 @@ class Date:
         """转换为Python datetime.datetime对象"""
         return datetime.datetime(self.year, self.month, self.day)
     
-    def format(self, fmt='%Y-%m-%d'):
-        """格式化日期字符串"""
+    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()
@@ -136,13 +208,30 @@ class Date:
         """返回当年天数"""
         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对象"""
+        """增加天数，返回新的Date对象，保持原始格式"""
         new_date = self.to_date() + datetime.timedelta(days=days)
-        return Date(new_date.year, new_date.month, new_date.day)
+        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对象"""
+        """增加月数，返回新的Date对象，保持原始格式"""
         new_month = self.month + months
         new_year = self.year
         
@@ -157,7 +246,11 @@ class Date:
         max_day = calendar.monthrange(new_year, new_month)[1]
         new_day = min(self.day, max_day)
         
-        return Date(new_year, new_month, new_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):
         """计算与另一个日期的天数差"""
@@ -169,8 +262,8 @@ class Date:
         return (date1 - date2).days
     
     def __str__(self):
-        """字符串表示"""
-        return f"{self.year}-{self.month:02d}-{self.day:02d}"
+        """字符串表示，使用默认格式"""
+        return self.format_default()
     
     def __repr__(self):
         """调试表示"""