🦞 时间戳转换工具

一个强大的Python时间戳转换工具，支持多种格式、时区转换和批量操作。

✨ 特性

核心功能

• ✅ 毫秒时间戳 → 日期时间字符串：支持多种输出格式
• ✅ 日期字符串 → 时间戳：支持灵活解析
• ✅ 时区转换：支持任意时区偏移
• ✅ 相对时间计算：自动计算"3天前"、"2小时后"等相对描述
• ✅ 批量转换：支持文件批量处理
• ✅ 灵活输入：支持时间戳、日期字符串、ISO 8601格式
• ✅ 验证测试：100%测试覆盖率

格式支持

• 标准格式：2026-03-07 14:30:45
• ISO 8601：2026-03-07T14:30:45+08:00
• 完整格式：2026年03月07日 14时30分45秒
• 仅日期：2026-03-07
• 仅时间：14:30:45
• 自定义格式：支持任意Python datetime格式

🚀 快速开始

安装方式

方式一：源码安装

# 克隆项目
git clone https://github.com/openclaw/timestamp-converter.git
cd timestamp-converter

# 安装
pip install -e .

# 或使用安装脚本
./scripts/install.sh

方式二：PyPI安装（待发布）

pip install timestamp-converter

命令行使用

# 转换时间戳
timestamp-convert 1774800000000

# 转换为ISO格式
timestamp-convert --iso 1774800000000

# 显示当前时间
timestamp-convert --now

# 从日期字符串转换
timestamp-convert --from-string "2026-03-07"

# 计算相对时间
timestamp-convert --relative 1774800000000

# 批量转换
timestamp-convert --batch timestamps.txt

# 比较两个时间戳
timestamp-convert --compare 1774800000000 1774808640000

# 自定义时区（纽约，UTC-5）
timestamp-convert --timezone -5 1774800000000

# 进入交互模式
timestamp-convert --interactive

Python模块使用

from timestamp_converter import TimestampConverter, ms_to_string, ms_to_iso8601

# 创建转换器
converter = TimestampConverter(timezone_offset=8)  # 东八区

# 基本转换
timestamp_ms = 1774800000000
dt_string = converter.ms_to_string(timestamp_ms)  # "2026-03-07 00:00:00"
iso_string = converter.ms_to_iso8601(timestamp_ms)  # "2026-03-07T00:00:00+08:00"

# 快捷函数
from timestamp_converter import ms_to_string, string_to_ms, now_ms, relative_time

# 时间戳转字符串
print(ms_to_string(1774800000000))  # "2026-03-07 00:00:00"

# 字符串转时间戳
timestamp = string_to_ms("2026-03-07 00:00:00")
print(timestamp)  # 1774800000000

# 当前时间
current = now_ms()

# 相对时间
print(relative_time(1774800000000))  # "几天前"

# 格式化输出
from timestamp_converter import format_timestamp
print(format_timestamp(1774800000000, "full"))  # "2026年03月07日 00时00分00秒"
print(format_timestamp(1774800000000, "date"))   # "2026-03-07"
print(format_timestamp(1774800000000, "time"))   # "00:00:00"

📦 项目结构

timestamp-converter/
├── src/                             # 源代码目录
│   └── timestamp_converter.py      # 主模块
├── tests/                          # 测试代码
│   └── test_timestamp_converter.py
├── scripts/                        # 工具脚本
│   ├── install.sh                 # 安装脚本
│   └── cli_wrapper.py             # 增强CLI
├── docs/                          # 文档
├── .github/workflows/             # CI/CD配置
├── pyproject.toml                # 项目配置
├── setup.py                      # 安装配置
├── requirements.txt              # 依赖文件
├── README.md                     # 说明文档
└── CHANGELOG.md                  # 变更日志

🧪 测试

# 安装测试依赖
pip install pytest pytest-cov

# 运行所有测试
python -m pytest tests/ -v

# 运行测试并生成覆盖率报告
python -m pytest tests/ --cov=src --cov-report=html

# 运行特定测试
python -m pytest tests/test_timestamp_converter.py::TestTimestampConverter -v

🔧 开发指南

代码规范

# 代码格式化
black src/ tests/

# 代码检查
flake8 src/ --max-line-length=120

# 类型检查
mypy src/

# 导入排序
isort src/ tests/

版本控制

# 开发流程
git checkout -b feature/timestamp-feature
# ... 开发代码 ...
git add .
git commit -m "feat: add new timestamp feature"
git push origin feature/timestamp-feature

# 创建发布
git tag v1.0.0
git push origin v1.0.0

📊 性能特点

高性能

• 纯Python实现，无需外部依赖
• 支持批量操作，避免循环开销
• 内存优化，支持大型时间戳列表

时区支持

• 任意时区偏移配置
• 自动处理夏令时（需操作系统支持）
• 内置主要城市时区映射

错误处理

• 全面的异常捕获和用户友好提示
• 无效输入自动检测和恢复
• 详细的错误日志和调试信息

🎯 使用场景

数据分析

# 处理时间序列数据
timestamps = [1774800000000, 1774808640000, 1774817280000]
datetime_strings = converter.batch_convert(timestamps)

日志处理

# 转换日志中的时间戳
log_entry = "2026+Mar+07+00:00:00.000"
timestamp = converter.string_to_ms(log_entry, "%Y+%b+%d+%H:%M:%S.%f")

数据库操作

# 数据库时间戳与Python时间的转换
import sqlite3

# 从数据库读取时间戳
conn = sqlite3.connect('data.db')
cursor = conn.execute('SELECT timestamp FROM logs')
for row in cursor:
    human_time = converter.ms_to_string(row[0])
    print(f"日志时间: {human_time}")

API开发

from flask import Flask, request
from timestamp_converter import ms_to_string

app = Flask(__name__)

@app.route('/api/timestamp/<timestamp>')
def convert_timestamp(timestamp):
    try:
        result = ms_to_string(timestamp)
        return {'timestamp': timestamp, 'datetime': result}
    except Exception as e:
        return {'error': str(e)}, 400

🤝 贡献指南

1. Fork 项目
2. 创建功能分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m 'feat: add amazing feature')
4. 推送分支 (git push origin feature/amazing-feature)
5. 创建 Pull Request

开发规范

• 代码符合PEP 8规范
• 添加适当的单元测试
• 更新相关文档
• 确保向后兼容性

📄 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。

🙏 致谢

• Python Datetime 模块
• Pytest 测试框架
• Black 代码格式化工具
• OpenClaw 社区

📞 联系方式

• 项目地址: https://github.com/openclaw/timestamp-converter
• 问题反馈: GitHub Issues
• 讨论群组: OpenClaw Discord

🔗 相关项目

• OpenClaw - 智能助手平台
• Python-CLI-Template - Python CLI项目模板
• TimeUtils - 时间处理工具集

---

🦞 由OpenClaw Assistant创建 | 2026-04-01