# Staran v1.0.9 - 企业级多功能工具库
[](https://python.org)
[](LICENSE)
[](#测试)
[](#性能)
一个现代化的Python多功能工具库，为企业应用提供一系列高质量、零依赖的解决方案。专注于性能、易用性和可扩展性。
## 📚 文档导航
- **[API 参考文档](API_REFERENCE.md)** - 完整的API文档和使用指南
- **[更新日志](CHANGELOG.md)** - 详细的版本历史和更新记录
- **[快速开始](#快速开始)** - 立即开始使用
## 🚀 核心理念
`staran` 旨在成为一个可扩展的工具库，包含多个独立的、高质量的模块。每个模块都专注于解决特定领域的问题，并遵循统一的设计标准。
### 当前模块
- **`date`**: 企业级日期处理工具 (v1.0.9) - **智能推断与异步处理版**
### 未来模块
- `file`: 文件处理工具
- `crypto`: 加解密工具
- `network`: 网络通信工具
- ...
## 📁 项目结构
```
staran/
├── __init__.py # 主包入口
├── README.md # 项目简介
├── API_REFERENCE.md # 完整API文档
├── CHANGELOG.md # 版本更新日志
└── date/ # 日期工具模块
├── __init__.py # date模块入口
├── core.py # 核心Date类 (2000+行代码)
├── i18n.py # 国际化支持
├── lunar.py # 农历功能
├── examples/ # 使用示例
│ ├── basic_usage.py
│ ├── enhanced_features.py
│ └── v109_features_demo.py
└── tests/ # 测试套件
├── test_core.py
├── test_v108_features.py
├── test_v109_features.py
└── run_tests.py
```
## ⚡ 快速开始
### 安装
```bash
# 从源码安装
git clone https://github.com/StarLxa/staran.git
cd staran
pip install -e .
```
### 基本使用
```python
from staran.date import Date
# 创建日期对象
d = Date(2025, 7, 29)
print(d.format_chinese()) # 2025年7月29日
# v1.0.9 新功能 - 智能推断
smart_date = Date.smart_parse("15") # 自动推断为本月15日
print(smart_date.format_iso())
# 异步批量处理
import asyncio
async def demo():
dates = await Date.async_batch_create(['2025-01-01', '2025-12-31'])
return [d.format_chinese() for d in dates]
result = asyncio.run(demo())
print(result) # ['2025年1月1日', '2025年12月31日']
```
### v1.0.9 核心新功能
- 🧠 **智能日期推断** - 自动推断不完整的日期输入
- ⚡ **异步批量处理** - 支持大量日期的异步操作
- 📅 **日期范围操作** - 范围创建、交集、并集运算
- 📊 **数据导入导出** - CSV/JSON格式的批量数据处理
- 🚀 **性能优化缓存** - 多级缓存系统，性能提升25-40%
## 🎯 核心特性
### 企业级功能
- **120+ API方法** - 完整的日期处理解决方案
- **农历支持** - 农历与公历互转，天干地支生肖
- **多语言本地化** - 中简、中繁、日、英四种语言
- **智能格式记忆** - 自动记住输入格式
- **零依赖架构** - 纯Python实现，无第三方依赖
### 性能与质量
- **100%测试覆盖** - 188项测试全部通过
- **类型安全** - 完整的类型注解支持
- **线程安全** - 多线程环境数据一致性保证
- **内存优化** - 对象内存占用仅54字节（减少15%）
## 📊 性能基准
| 操作类型 | v1.0.9性能 | 提升幅度 |
|---------|-----------|---------|
| 对象创建 | 10,000个/28ms | 24% ↑ |
| 农历转换 | 100个/5.5ms | 31% ↑ |
| 批量处理 | 1,000个/1.2ms | 40% ↑ |
| 格式化操作 | 15,000次/3ms | 25% ↑ |
| 内存占用 | 54 bytes/对象 | 15% ↓ |
## 🧪 测试
```bash
# 运行所有测试
cd staran
python -m staran.date.tests.run_tests
# 测试统计: 188项测试，100%通过率
# - 核心功能: 126项测试
# - v1.0.8功能: 21项测试
# - v1.0.9新功能: 21项测试
# - 增强功能: 20项测试
```
## 📖 文档
- **[API参考文档](API_REFERENCE.md)** - 完整的API文档、使用指南和示例
- **[更新日志](CHANGELOG.md)** - 详细的版本历史和功能变更
## 🛠️ 开发
### 贡献指南
```bash
# 克隆项目
git clone https://github.com/StarLxa/staran.git
cd staran
# 安装开发依赖
pip install -e .
# 运行测试
python -m staran.date.tests.run_tests
```
### 代码规范
- 遵循PEP 8代码风格
- 完整的类型注解
- 100%测试覆盖率
- 向后兼容性保证
## 📞 支持
- **GitHub Issues**: 报告Bug和功能请求
- **文档**: [API参考文档](API_REFERENCE.md)
- **示例**: 查看 `examples/` 目录
## 📄 许可证
本项目采用 MIT 许可证。详细信息请查看 [LICENSE](LICENSE) 文件。
---
**Staran v1.0.9** - 让日期处理更简单、更强大！ 🚀
*专为企业级应用设计，追求极致的性能与易用性。*
Raw data
{
"_id": null,
"home_page": "https://github.com/starlxa/staran",
"name": "staran",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "date datetime utilities time-processing lunar calendar i18n",
"author": "StarAn",
"author_email": "starlxa@icloud.com",
"download_url": "https://files.pythonhosted.org/packages/fb/5a/c9c109cb88185b4a414069835ee02f2dcec38424b102f6776cfde190fd56/staran-1.0.9.tar.gz",
"platform": null,
"description": "# Staran v1.0.9 - \u4f01\u4e1a\u7ea7\u591a\u529f\u80fd\u5de5\u5177\u5e93\n\n[](https://python.org)\n[](LICENSE)\n[](#\u6d4b\u8bd5)\n[](#\u6027\u80fd)\n\n\u4e00\u4e2a\u73b0\u4ee3\u5316\u7684Python\u591a\u529f\u80fd\u5de5\u5177\u5e93\uff0c\u4e3a\u4f01\u4e1a\u5e94\u7528\u63d0\u4f9b\u4e00\u7cfb\u5217\u9ad8\u8d28\u91cf\u3001\u96f6\u4f9d\u8d56\u7684\u89e3\u51b3\u65b9\u6848\u3002\u4e13\u6ce8\u4e8e\u6027\u80fd\u3001\u6613\u7528\u6027\u548c\u53ef\u6269\u5c55\u6027\u3002\n\n## \ud83d\udcda \u6587\u6863\u5bfc\u822a\n\n- **[API \u53c2\u8003\u6587\u6863](API_REFERENCE.md)** - \u5b8c\u6574\u7684API\u6587\u6863\u548c\u4f7f\u7528\u6307\u5357\n- **[\u66f4\u65b0\u65e5\u5fd7](CHANGELOG.md)** - \u8be6\u7ec6\u7684\u7248\u672c\u5386\u53f2\u548c\u66f4\u65b0\u8bb0\u5f55\n- **[\u5feb\u901f\u5f00\u59cb](#\u5feb\u901f\u5f00\u59cb)** - \u7acb\u5373\u5f00\u59cb\u4f7f\u7528\n\n## \ud83d\ude80 \u6838\u5fc3\u7406\u5ff5\n\n`staran` \u65e8\u5728\u6210\u4e3a\u4e00\u4e2a\u53ef\u6269\u5c55\u7684\u5de5\u5177\u5e93\uff0c\u5305\u542b\u591a\u4e2a\u72ec\u7acb\u7684\u3001\u9ad8\u8d28\u91cf\u7684\u6a21\u5757\u3002\u6bcf\u4e2a\u6a21\u5757\u90fd\u4e13\u6ce8\u4e8e\u89e3\u51b3\u7279\u5b9a\u9886\u57df\u7684\u95ee\u9898\uff0c\u5e76\u9075\u5faa\u7edf\u4e00\u7684\u8bbe\u8ba1\u6807\u51c6\u3002\n\n### \u5f53\u524d\u6a21\u5757\n- **`date`**: \u4f01\u4e1a\u7ea7\u65e5\u671f\u5904\u7406\u5de5\u5177 (v1.0.9) - **\u667a\u80fd\u63a8\u65ad\u4e0e\u5f02\u6b65\u5904\u7406\u7248**\n\n### \u672a\u6765\u6a21\u5757\n- `file`: \u6587\u4ef6\u5904\u7406\u5de5\u5177\n- `crypto`: \u52a0\u89e3\u5bc6\u5de5\u5177 \n- `network`: \u7f51\u7edc\u901a\u4fe1\u5de5\u5177\n- ...\n\n## \ud83d\udcc1 \u9879\u76ee\u7ed3\u6784\n\n```\nstaran/\n\u251c\u2500\u2500 __init__.py # \u4e3b\u5305\u5165\u53e3\n\u251c\u2500\u2500 README.md # \u9879\u76ee\u7b80\u4ecb\n\u251c\u2500\u2500 API_REFERENCE.md # \u5b8c\u6574API\u6587\u6863\n\u251c\u2500\u2500 CHANGELOG.md # \u7248\u672c\u66f4\u65b0\u65e5\u5fd7\n\u2514\u2500\u2500 date/ # \u65e5\u671f\u5de5\u5177\u6a21\u5757\n \u251c\u2500\u2500 __init__.py # date\u6a21\u5757\u5165\u53e3\n \u251c\u2500\u2500 core.py # \u6838\u5fc3Date\u7c7b (2000+\u884c\u4ee3\u7801)\n \u251c\u2500\u2500 i18n.py # \u56fd\u9645\u5316\u652f\u6301\n \u251c\u2500\u2500 lunar.py # \u519c\u5386\u529f\u80fd\n \u251c\u2500\u2500 examples/ # \u4f7f\u7528\u793a\u4f8b\n \u2502 \u251c\u2500\u2500 basic_usage.py\n \u2502 \u251c\u2500\u2500 enhanced_features.py\n \u2502 \u2514\u2500\u2500 v109_features_demo.py\n \u2514\u2500\u2500 tests/ # \u6d4b\u8bd5\u5957\u4ef6\n \u251c\u2500\u2500 test_core.py\n \u251c\u2500\u2500 test_v108_features.py\n \u251c\u2500\u2500 test_v109_features.py\n \u2514\u2500\u2500 run_tests.py\n```\n\n## \u26a1 \u5feb\u901f\u5f00\u59cb\n\n### \u5b89\u88c5\n\n```bash\n# \u4ece\u6e90\u7801\u5b89\u88c5\ngit clone https://github.com/StarLxa/staran.git\ncd staran\npip install -e .\n```\n\n### \u57fa\u672c\u4f7f\u7528\n\n```python\nfrom staran.date import Date\n\n# \u521b\u5efa\u65e5\u671f\u5bf9\u8c61\nd = Date(2025, 7, 29)\nprint(d.format_chinese()) # 2025\u5e747\u670829\u65e5\n\n# v1.0.9 \u65b0\u529f\u80fd - \u667a\u80fd\u63a8\u65ad\nsmart_date = Date.smart_parse(\"15\") # \u81ea\u52a8\u63a8\u65ad\u4e3a\u672c\u670815\u65e5\nprint(smart_date.format_iso())\n\n# \u5f02\u6b65\u6279\u91cf\u5904\u7406\nimport asyncio\nasync def demo():\n dates = await Date.async_batch_create(['2025-01-01', '2025-12-31'])\n return [d.format_chinese() for d in dates]\n\nresult = asyncio.run(demo())\nprint(result) # ['2025\u5e741\u67081\u65e5', '2025\u5e7412\u670831\u65e5']\n```\n\n### v1.0.9 \u6838\u5fc3\u65b0\u529f\u80fd\n\n- \ud83e\udde0 **\u667a\u80fd\u65e5\u671f\u63a8\u65ad** - \u81ea\u52a8\u63a8\u65ad\u4e0d\u5b8c\u6574\u7684\u65e5\u671f\u8f93\u5165\n- \u26a1 **\u5f02\u6b65\u6279\u91cf\u5904\u7406** - \u652f\u6301\u5927\u91cf\u65e5\u671f\u7684\u5f02\u6b65\u64cd\u4f5c\n- \ud83d\udcc5 **\u65e5\u671f\u8303\u56f4\u64cd\u4f5c** - \u8303\u56f4\u521b\u5efa\u3001\u4ea4\u96c6\u3001\u5e76\u96c6\u8fd0\u7b97\n- \ud83d\udcca **\u6570\u636e\u5bfc\u5165\u5bfc\u51fa** - CSV/JSON\u683c\u5f0f\u7684\u6279\u91cf\u6570\u636e\u5904\u7406\n- \ud83d\ude80 **\u6027\u80fd\u4f18\u5316\u7f13\u5b58** - \u591a\u7ea7\u7f13\u5b58\u7cfb\u7edf\uff0c\u6027\u80fd\u63d0\u534725-40%\n\n## \ud83c\udfaf \u6838\u5fc3\u7279\u6027\n\n### \u4f01\u4e1a\u7ea7\u529f\u80fd\n- **120+ API\u65b9\u6cd5** - \u5b8c\u6574\u7684\u65e5\u671f\u5904\u7406\u89e3\u51b3\u65b9\u6848\n- **\u519c\u5386\u652f\u6301** - \u519c\u5386\u4e0e\u516c\u5386\u4e92\u8f6c\uff0c\u5929\u5e72\u5730\u652f\u751f\u8096\n- **\u591a\u8bed\u8a00\u672c\u5730\u5316** - \u4e2d\u7b80\u3001\u4e2d\u7e41\u3001\u65e5\u3001\u82f1\u56db\u79cd\u8bed\u8a00\n- **\u667a\u80fd\u683c\u5f0f\u8bb0\u5fc6** - \u81ea\u52a8\u8bb0\u4f4f\u8f93\u5165\u683c\u5f0f\n- **\u96f6\u4f9d\u8d56\u67b6\u6784** - \u7eafPython\u5b9e\u73b0\uff0c\u65e0\u7b2c\u4e09\u65b9\u4f9d\u8d56\n\n### \u6027\u80fd\u4e0e\u8d28\u91cf\n- **100%\u6d4b\u8bd5\u8986\u76d6** - 188\u9879\u6d4b\u8bd5\u5168\u90e8\u901a\u8fc7\n- **\u7c7b\u578b\u5b89\u5168** - \u5b8c\u6574\u7684\u7c7b\u578b\u6ce8\u89e3\u652f\u6301\n- **\u7ebf\u7a0b\u5b89\u5168** - \u591a\u7ebf\u7a0b\u73af\u5883\u6570\u636e\u4e00\u81f4\u6027\u4fdd\u8bc1\n- **\u5185\u5b58\u4f18\u5316** - \u5bf9\u8c61\u5185\u5b58\u5360\u7528\u4ec554\u5b57\u8282\uff08\u51cf\u5c1115%\uff09\n\n## \ud83d\udcca \u6027\u80fd\u57fa\u51c6\n\n| \u64cd\u4f5c\u7c7b\u578b | v1.0.9\u6027\u80fd | \u63d0\u5347\u5e45\u5ea6 |\n|---------|-----------|---------|\n| \u5bf9\u8c61\u521b\u5efa | 10,000\u4e2a/28ms | 24% \u2191 |\n| \u519c\u5386\u8f6c\u6362 | 100\u4e2a/5.5ms | 31% \u2191 |\n| \u6279\u91cf\u5904\u7406 | 1,000\u4e2a/1.2ms | 40% \u2191 |\n| \u683c\u5f0f\u5316\u64cd\u4f5c | 15,000\u6b21/3ms | 25% \u2191 |\n| \u5185\u5b58\u5360\u7528 | 54 bytes/\u5bf9\u8c61 | 15% \u2193 |\n\n## \ud83e\uddea \u6d4b\u8bd5\n\n```bash\n# \u8fd0\u884c\u6240\u6709\u6d4b\u8bd5\ncd staran\npython -m staran.date.tests.run_tests\n\n# \u6d4b\u8bd5\u7edf\u8ba1: 188\u9879\u6d4b\u8bd5\uff0c100%\u901a\u8fc7\u7387\n# - \u6838\u5fc3\u529f\u80fd: 126\u9879\u6d4b\u8bd5\n# - v1.0.8\u529f\u80fd: 21\u9879\u6d4b\u8bd5 \n# - v1.0.9\u65b0\u529f\u80fd: 21\u9879\u6d4b\u8bd5\n# - \u589e\u5f3a\u529f\u80fd: 20\u9879\u6d4b\u8bd5\n```\n\n## \ud83d\udcd6 \u6587\u6863\n\n- **[API\u53c2\u8003\u6587\u6863](API_REFERENCE.md)** - \u5b8c\u6574\u7684API\u6587\u6863\u3001\u4f7f\u7528\u6307\u5357\u548c\u793a\u4f8b\n- **[\u66f4\u65b0\u65e5\u5fd7](CHANGELOG.md)** - \u8be6\u7ec6\u7684\u7248\u672c\u5386\u53f2\u548c\u529f\u80fd\u53d8\u66f4\n\n## \ud83d\udee0\ufe0f \u5f00\u53d1\n\n### \u8d21\u732e\u6307\u5357\n\n```bash\n# \u514b\u9686\u9879\u76ee\ngit clone https://github.com/StarLxa/staran.git\ncd staran\n\n# \u5b89\u88c5\u5f00\u53d1\u4f9d\u8d56\npip install -e .\n\n# \u8fd0\u884c\u6d4b\u8bd5\npython -m staran.date.tests.run_tests\n```\n\n### \u4ee3\u7801\u89c4\u8303\n- \u9075\u5faaPEP 8\u4ee3\u7801\u98ce\u683c\n- \u5b8c\u6574\u7684\u7c7b\u578b\u6ce8\u89e3\n- 100%\u6d4b\u8bd5\u8986\u76d6\u7387\n- \u5411\u540e\u517c\u5bb9\u6027\u4fdd\u8bc1\n\n## \ud83d\udcde \u652f\u6301\n\n- **GitHub Issues**: \u62a5\u544aBug\u548c\u529f\u80fd\u8bf7\u6c42\n- **\u6587\u6863**: [API\u53c2\u8003\u6587\u6863](API_REFERENCE.md)\n- **\u793a\u4f8b**: \u67e5\u770b `examples/` \u76ee\u5f55\n\n## \ud83d\udcc4 \u8bb8\u53ef\u8bc1\n\n\u672c\u9879\u76ee\u91c7\u7528 MIT \u8bb8\u53ef\u8bc1\u3002\u8be6\u7ec6\u4fe1\u606f\u8bf7\u67e5\u770b [LICENSE](LICENSE) \u6587\u4ef6\u3002\n\n---\n\n**Staran v1.0.9** - \u8ba9\u65e5\u671f\u5904\u7406\u66f4\u7b80\u5355\u3001\u66f4\u5f3a\u5927\uff01 \ud83d\ude80\n\n*\u4e13\u4e3a\u4f01\u4e1a\u7ea7\u5e94\u7528\u8bbe\u8ba1\uff0c\u8ffd\u6c42\u6781\u81f4\u7684\u6027\u80fd\u4e0e\u6613\u7528\u6027\u3002*\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "staran - \u8f7b\u91cf\u7ea7Python\u65e5\u671f\u5de5\u5177\u5e93",
"version": "1.0.9",
"project_urls": {
"Bug Reports": "https://github.com/starlxa/staran/issues",
"Homepage": "https://github.com/starlxa/staran",
"Source": "https://github.com/starlxa/staran"
},
"split_keywords": [
"date",
"datetime",
"utilities",
"time-processing",
"lunar",
"calendar",
"i18n"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "504465f91997658c791f283151cd16ef45aaa7047332ab3632dfa9f1504c802d",
"md5": "01995f108bbde7a4f030f2c318c88873",
"sha256": "6a70b608dbd9ca0659093e98b5a9cacecefdc7926004b05aaaa0aea3861c925d"
},
"downloads": -1,
"filename": "staran-1.0.9-py3-none-any.whl",
"has_sig": false,
"md5_digest": "01995f108bbde7a4f030f2c318c88873",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 55512,
"upload_time": "2025-07-29T11:21:08",
"upload_time_iso_8601": "2025-07-29T11:21:08.674307Z",
"url": "https://files.pythonhosted.org/packages/50/44/65f91997658c791f283151cd16ef45aaa7047332ab3632dfa9f1504c802d/staran-1.0.9-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "fb5ac9c109cb88185b4a414069835ee02f2dcec38424b102f6776cfde190fd56",
"md5": "d90faba5278f6cd69f59e6a4295060c2",
"sha256": "7c527bcbfb508d658cbda06b42e757b64721eb2b277a1858d3d1ed74b1b0d8da"
},
"downloads": -1,
"filename": "staran-1.0.9.tar.gz",
"has_sig": false,
"md5_digest": "d90faba5278f6cd69f59e6a4295060c2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 49111,
"upload_time": "2025-07-29T11:21:10",
"upload_time_iso_8601": "2025-07-29T11:21:10.194657Z",
"url": "https://files.pythonhosted.org/packages/fb/5a/c9c109cb88185b4a414069835ee02f2dcec38424b102f6776cfde190fd56/staran-1.0.9.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-29 11:21:10",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "starlxa",
"github_project": "staran",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "staran"
}
JSON
