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

staran/date/utils/helpers.py

@@ -0,0 +1,203 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+"""
+日期处理辅助工具
+==============
+
+提供日期处理相关的辅助函数和常量。
+"""
+
+import calendar
+from typing import List, Tuple
+
+# 常量定义
+WEEKDAYS_ZH = ['星期一', '星期二', '星期三', '星期四', '星期五', '星期六', '星期日']
+WEEKDAYS_EN = ['Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday', 'Sunday']
+MONTHS_ZH = ['一月', '二月', '三月', '四月', '五月', '六月', 
+            '七月', '八月', '九月', '十月', '十一月', '十二月']
+MONTHS_EN = ['January', 'February', 'March', 'April', 'May', 'June',
+            'July', 'August', 'September', 'October', 'November', 'December']
+
+
+def get_quarter(month: int) -> int:
+    """获取月份对应的季度
+    
+    Args:
+        month: 月份 (1-12)
+        
+    Returns:
+        季度 (1-4)
+    """
+    return (month - 1) // 3 + 1
+
+
+def get_quarter_months(quarter: int) -> List[int]:
+    """获取季度包含的月份
+    
+    Args:
+        quarter: 季度 (1-4)
+        
+    Returns:
+        月份列表
+    """
+    if quarter == 1:
+        return [1, 2, 3]
+    elif quarter == 2:
+        return [4, 5, 6]
+    elif quarter == 3:
+        return [7, 8, 9]
+    elif quarter == 4:
+        return [10, 11, 12]
+    else:
+        raise ValueError("季度必须在1-4之间")
+
+
+def is_business_day(year: int, month: int, day: int) -> bool:
+    """判断是否为工作日（简单版本，仅考虑周末）
+    
+    Args:
+        year: 年
+        month: 月
+        day: 日
+        
+    Returns:
+        是否为工作日
+    """
+    import datetime
+    date = datetime.date(year, month, day)
+    return date.weekday() < 5  # 0-4为周一到周五
+
+
+def get_week_range(year: int, month: int, day: int) -> Tuple[Tuple[int, int, int], Tuple[int, int, int]]:
+    """获取指定日期所在周的开始和结束日期
+    
+    Args:
+        year: 年
+        month: 月
+        day: 日
+        
+    Returns:
+        ((开始年, 开始月, 开始日), (结束年, 结束月, 结束日))
+    """
+    import datetime
+    date = datetime.date(year, month, day)
+    
+    # 计算周一（周开始）
+    days_since_monday = date.weekday()
+    monday = date - datetime.timedelta(days=days_since_monday)
+    
+    # 计算周日（周结束）
+    sunday = monday + datetime.timedelta(days=6)
+    
+    return ((monday.year, monday.month, monday.day), 
+            (sunday.year, sunday.month, sunday.day))
+
+
+def format_weekday(weekday: int, lang: str = 'zh') -> str:
+    """格式化星期几
+    
+    Args:
+        weekday: 星期几 (0=星期一, 6=星期日)
+        lang: 语言 ('zh'=中文, 'en'=英文)
+        
+    Returns:
+        格式化的星期几字符串
+    """
+    if lang == 'zh':
+        return WEEKDAYS_ZH[weekday]
+    elif lang == 'en':
+        return WEEKDAYS_EN[weekday]
+    else:
+        raise ValueError("语言必须是 'zh' 或 'en'")
+
+
+def format_month(month: int, lang: str = 'zh') -> str:
+    """格式化月份
+    
+    Args:
+        month: 月份 (1-12)
+        lang: 语言 ('zh'=中文, 'en'=英文)
+        
+    Returns:
+        格式化的月份字符串
+    """
+    if lang == 'zh':
+        return MONTHS_ZH[month - 1]
+    elif lang == 'en':
+        return MONTHS_EN[month - 1]
+    else:
+        raise ValueError("语言必须是 'zh' 或 'en'")
+
+
+def calculate_age(birth_year: int, birth_month: int, birth_day: int, 
+                 current_year: int, current_month: int, current_day: int) -> int:
+    """计算年龄
+    
+    Args:
+        birth_year: 出生年
+        birth_month: 出生月
+        birth_day: 出生日
+        current_year: 当前年
+        current_month: 当前月
+        current_day: 当前日
+        
+    Returns:
+        年龄
+    """
+    age = current_year - birth_year
+    
+    # 如果还没到生日，年龄减1
+    if (current_month, current_day) < (birth_month, birth_day):
+        age -= 1
+    
+    return age
+
+
+def get_zodiac_sign(month: int, day: int) -> str:
+    """获取星座
+    
+    Args:
+        month: 月份
+        day: 日期
+        
+    Returns:
+        星座名称
+    """
+    if (month == 3 and day >= 21) or (month == 4 and day <= 19):
+        return "白羊座"
+    elif (month == 4 and day >= 20) or (month == 5 and day <= 20):
+        return "金牛座"
+    elif (month == 5 and day >= 21) or (month == 6 and day <= 20):
+        return "双子座"
+    elif (month == 6 and day >= 21) or (month == 7 and day <= 22):
+        return "巨蟹座"
+    elif (month == 7 and day >= 23) or (month == 8 and day <= 22):
+        return "狮子座"
+    elif (month == 8 and day >= 23) or (month == 9 and day <= 22):
+        return "处女座"
+    elif (month == 9 and day >= 23) or (month == 10 and day <= 22):
+        return "天秤座"
+    elif (month == 10 and day >= 23) or (month == 11 and day <= 21):
+        return "天蝎座"
+    elif (month == 11 and day >= 22) or (month == 12 and day <= 21):
+        return "射手座"
+    elif (month == 12 and day >= 22) or (month == 1 and day <= 19):
+        return "摩羯座"
+    elif (month == 1 and day >= 20) or (month == 2 and day <= 18):
+        return "水瓶座"
+    else:  # (month == 2 and day >= 19) or (month == 3 and day <= 20)
+        return "双鱼座"
+
+
+def get_chinese_zodiac(year: int) -> str:
+    """获取生肖
+    
+    Args:
+        year: 年份
+        
+    Returns:
+        生肖名称
+    """
+    zodiacs = ['猴', '鸡', '狗', '猪', '鼠', '牛', '虎', '兔', '龙', '蛇', '马', '羊']
+    return zodiacs[year % 12]

staran-1.0.3.dist-info/METADATA

@@ -0,0 +1,198 @@
+Metadata-Version: 2.4
+Name: staran
+Version: 1.0.3
+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.3 - 企业级多功能工具库
+
+[![Python Version](https://img.shields.io/badge/python-3.7%2B-blue.svg)](https://python.org)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![Test Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen.svg)](#测试)
+
+一个现代化的Python多功能工具库，为企业应用提供一系列高质量、零依赖的解决方案。
+
+## 🚀 核心理念
+
+`staran` 旨在成为一个可扩展的工具库，包含多个独立的、高质量的模块。每个模块都专注于解决特定领域的问题，并遵循统一的设计标准。
+
+### 当前模块
+- **`date`**: 企业级日期处理工具 (v1.0.3)
+
+### 未来模块
+- `file`: 文件处理工具
+- `crypto`: 加解密工具
+- ...
+
+## 📁 项目结构
+
+```
+staran/
+├── __init__.py           # 主包入口，未来可集成更多工具
+└── date/                 # 日期工具模块
+    ├── __init__.py       # date模块入口
+    ├── core.py           # 核心Date类
+    ├── tests/            # date模块的测试
+    ├── utils/            # date模块的工具函数
+    └── examples/         # date模块的示例
+```
+
+---
+
+## ✨ `date` 模块 - 企业级日期处理
+
+`date` 模块提供了强大的日期处理功能，具有统一API、智能格式记忆和企业级日志等特性。
+
+### 快速开始
+
+#### 安装
+
+```bash
+pip install staran
+```
+
+#### 基本用法
+
+```python
+from staran.date import Date, today
+
+# 快速创建日期
+today_date = today()
+print(today_date)  # 2025-07-29
+
+# 从字符串创建
+date = Date.from_string("20250415")
+print(date.format_chinese())  # 2025年04月15日
+
+# 日期运算（保持格式）
+future = date.add_months(3)
+print(future)  # 20250715
+```
+
+### 📚 `date` 模块详细文档
+
+#### 1. 创建日期对象
+
+```python
+from staran.date import Date
+
+# 多种创建方式
+d1 = Date(2025, 4, 15)                    # 从参数
+d2 = Date.from_string("202504")           # 从字符串（智能解析）
+d3 = Date.from_string("20250415")         # 完整格式
+d4 = Date.from_string("2025")             # 年份格式
+d5 = Date.today()                         # 今日
+```
+
+#### 2. 智能格式记忆
+
+`date` 模块会记住输入格式，并在运算后保持相同格式：
+
+```python
+year_date = Date.from_string("2025")
+print(year_date.add_years(1))    # 2026
+
+month_date = Date.from_string("202504")
+print(month_date.add_months(2))  # 202506
+
+full_date = Date.from_string("20250415")
+print(full_date.add_days(10))    # 20250425
+```
+
+#### 3. 统一API命名
+
+`date` 模块遵循统一的API命名规范，如 `from_*`, `to_*`, `get_*`, `is_*`, `add_*/subtract_*` 等，具体请参考 `staran/date/examples/basic_usage.py`。
+
+#### 4. 异常处理
+
+`date` 模块提供了一套清晰的异常类，以便更好地处理错误：
+
+- `DateError`: 所有日期相关错误的基类。
+- `InvalidDateFormatError`: 当输入字符串格式不正确时抛出。
+- `InvalidDateValueError`: 当日期值无效时（如月份为13）抛出。
+
+**示例:**
+```python
+from staran.date import Date, InvalidDateValueError, InvalidDateFormatError
+
+try:
+    Date("2025", 13, 1)
+except InvalidDateValueError as e:
+    print(e)
+
+try:
+    Date("invalid-date")
+except InvalidDateFormatError as e:
+    print(e)
+```
+
+## 🧪 测试
+
+运行 `date` 模块的完整测试套件：
+
+```bash
+# 彩色测试输出
+python -m staran.date.tests.run_tests
+
+# 标准unittest
+python -m unittest staran.date.tests.test_core
+```
+
+测试覆盖率：**100%**（64项测试，涵盖所有功能模块）
+
+## 📄 许可证
+
+MIT License - 详见 [LICENSE](LICENSE) 文件
+
+## 🤝 贡献
+
+欢迎为 `staran` 贡献新的工具模块或改进现有模块！
+
+1. Fork 本项目
+2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
+3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
+4. 推送到分支 (`git push origin feature/AmazingFeature`)
+5. 开启Pull Request
+
+## 📞 支持
+
+- 📧 Email: team@staran.dev
+- 📖 文档: https://staran.readthedocs.io/
+- 🐛 问题报告: https://github.com/starlxa/staran/issues
+
+---
+
+**Staran v1.0.3** - 让工具开发变得简单而强大 ✨

staran-1.0.3.dist-info/RECORD

@@ -0,0 +1,15 @@
+staran/__init__.py,sha256=tHIqYKvkrhwhUKQ-H2DLHj0JjvOY5QbkTrk7_pfLaFI,1172
+staran/date/__init__.py,sha256=nm6tx-Qq9ntiwPGG4ieDTSl8MhTn3KugZyGLfUUBiaA,615
+staran/date/core.py,sha256=E-fs3lfX4ZVeh0YN8Vjmt3wv-UOrrfW8bETj-R8Js8E,18595
+staran/date/examples/__init__.py,sha256=5q6uxzeIhPcFo64gXybEozx4E4lt8TEEibFC-dF_EV0,163
+staran/date/examples/basic_usage.py,sha256=hsQZaMRR6tY9krLjmYrH7GrMkk2cGapY-bfjwsL_6YQ,4738
+staran/date/tests/__init__.py,sha256=oYQFFa4lv_68398OrMGk4CMX_4XX-9KuPHTflhkLmbo,171
+staran/date/tests/run_tests.py,sha256=Ix4qm_gF5blbSfVx05Deoml35BdQ7eIYERRPSw5AAP4,3424
+staran/date/tests/test_core.py,sha256=V7aTXAjNaHrdSWHE5aoem2u8s00ilI-Skbxo0fgqjvk,16444
+staran/date/utils/__init__.py,sha256=W5DkeslSOINF7kq6wFz3l16fUmGI0XALNuJAALQeLLM,142
+staran/date/utils/helpers.py,sha256=9TlebdCr-YD4vrXjTFMXDG413gbSFwdUNyivAarIp5M,5553
+staran-1.0.3.dist-info/licenses/LICENSE,sha256=2EmsBIyDCono4iVXNpv5_px9qt2b7hfPq1WuyGVMNP4,1361
+staran-1.0.3.dist-info/METADATA,sha256=a8Ct1x3Sm_fqFJlBc7k4yzGzYtFUwFGEmfqNn_586XI,5528
+staran-1.0.3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+staran-1.0.3.dist-info/top_level.txt,sha256=NOUZtXSh5oSIEjHrC0lQ9WmoKtD010Q00dghWyag-Zs,7
+staran-1.0.3.dist-info/RECORD,,

staran/tools/__init__.py

@@ -1,43 +0,0 @@
-#!/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'
-__description__ = 'Lightweight Python date utilities with smart format memory'