rsTimes 0.1.0__tar.gz

rstimes-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jiefu Chen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

rstimes-0.1.0/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: rsTimes
+Version: 0.1.0
+Summary: Integer-based conversions between aware datetimes and Unix milliseconds
+License-Expression: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Dynamic: license-file
+
+# rsTimes
+
+`rsTimes` 0.1.0 是一个纯 Python 日期时间小工具，提供带时区 `datetime`
+与 Unix 毫秒时间戳的双向转换。没有运行时依赖，要求 Python 3.10 或更新版本。
+当前版本没有 Rust 内核，不承诺性能优势或与其他日期时间库兼容。
+
+PyPI 分发名是 `rsTimes`，Python 导入名是 `rstimes`。
+
+## 使用
+
+首次成功发布到 PyPI 后可安装：
+
+```sh
+python -m pip install rsTimes
+```
+
+```python
+from datetime import datetime, timedelta, timezone
+from rstimes import from_unix_ms, to_unix_ms
+
+local_epoch = datetime(1970, 1, 1, 8, tzinfo=timezone(timedelta(hours=8)))
+assert to_unix_ms(local_epoch) == 0
+assert from_unix_ms(0) == datetime(1970, 1, 1, tzinfo=timezone.utc)
+
+before_epoch = datetime(1969, 12, 31, 23, 59, 59, 999999, tzinfo=timezone.utc)
+assert to_unix_ms(before_epoch) == -1
+assert from_unix_ms(-1).isoformat() == "1969-12-31T23:59:59.999000+00:00"
+```
+
+## 转换规则
+
+- `to_unix_ms(value: datetime) -> int`：输入必须带有效 UTC 偏移，
+  转换到 UTC 后用整数计算。微秒余数**向负无穷方向取整**：
+  纪元后 999 微秒得到 `0`，纪元前 1 微秒得到 `-1`。
+- `from_unix_ms(value: int) -> datetime`：只接受整数，拒绝 `bool`、
+  浮点数、字符串等类型；返回 `timezone.utc` 的带时区时间。
+- 毫秒范围为 `-62135596800000` 到 `253402300799999`，含两端，
+  对应 UTC 年份 1–9999。超出范围或时区转换越界抛出 `ValueError`；
+  naive datetime 也抛出 `ValueError`，非法输入类型抛出 `TypeError`。
+- 不使用本机时区、不经过浮点时间戳。毫秒整数可以精确往返；
+  datetime 的不足 1 毫秒部分在转换时会丢失。
+
+## 本地开发与构建
+
+以下命令适用于 macOS/Linux；Windows 可用 `.venv\Scripts\python`。
+
+```sh
+python3 -m venv .venv
+.venv/bin/python -m pip install --index-url https://pypi.org/simple -e ".[test]" build twine
+.venv/bin/python -m pytest
+.venv/bin/python -m build
+.venv/bin/python -m twine check --strict dist/*
+
+.venv/bin/python -m venv .wheel-test
+.wheel-test/bin/python -m pip install --no-deps dist/*.whl
+.wheel-test/bin/python -I -c 'from rstimes import from_unix_ms, to_unix_ms; assert to_unix_ms(from_unix_ms(-1)) == -1'
+```
+
+重新构建前清理旧的 `dist/` 内容，避免混入以前的发布文件。
+CI 配置会在 GitHub 的 Ubuntu runner 上使用 Python 3.10 和 3.13 测试、构建、
+检查元数据，并从 wheel 安装验证导入；这些配置不代表已在所有平台完成测试。
+
+## 发布前需要填写的信息
+
+维护者需要自行填写真实信息：
+
+| 项目 | 当前状态 |
+| --- | --- |
+| GitHub owner | 待填写本人账号或组织名 |
+| GitHub repository | 待填写实际仓库名 |
+| 许可证 | [MIT](LICENSE)，Copyright (c) 2026 Jiefu Chen |
+| 作者与项目 URL | 尚未填写；按实际情况补充，不使用虚构身份或链接 |
+
+本项目采用 [MIT 许可证](LICENSE)，许可证文本随源码与分发包一同提供。
+
+PyPI 将没有功能或空包的占名项目视为无效项目。本版本提供实际的时间转换功能，
+README 和包描述应保持与实际功能一致。
+
+## GitHub → PyPI Trusted Publisher
+
+本地配置已经准备好，以下持久授权和发布操作由维护者完成：
+
+1. 补齐需要的真实元数据；自行把这些文件提交并推送到自己的 GitHub
+   仓库。CI 成功后再准备正式 release。
+2. 在该 GitHub 仓库的 Settings → Environments 中创建名为 `pypi` 的 environment。
+   如有需要，为它配置审批人和允许发布的 tag 规则。
+3. 若 PyPI 尚无该项目，在自己的 PyPI 账号 Publishing 页面添加 **Pending Publisher**，
+   选择 GitHub，准确填写下表。已有项目则在该项目的 Publishing 页面添加 publisher。
+
+   | PyPI 字段 | 必须填写的值 |
+   | --- | --- |
+   | PyPI Project Name（pending 时） | `rsTimes` |
+   | Owner | 实际 GitHub owner，须与仓库所属账号或组织一致 |
+   | Repository name | 实际 GitHub 仓库名 |
+   | Workflow name | `publish.yml`（文件名，不是 workflow 显示名称） |
+   | Environment name | `pypi` |
+
+   Pending Publisher 在首次成功上传前不会创建项目或预留包名；名称也可能已被占用
+   或被 PyPI 保留。首次成功发布后 pending publisher 转为正式 publisher。
+4. 当前 `pyproject.toml` 的版本为 `0.1.0`。在包含上述文件的 commit 上创建 tag
+   `v0.1.0`，再发布对应的 GitHub Release。仅推送 tag 或保存 release 草稿不会触发上传。
+5. `.github/workflows/publish.yml` 只响应 `release: published`，检查 tag 与包版本
+   精确匹配（必须是 `v` 加版本号），随后测试、构建、检查 sdist/wheel 并验证 wheel。
+   只有这些步骤全部成功才会进入发布 job。
+6. 发布 job 使用 `environment: pypi`，仅该 job 有 `id-token: write`。
+   它只下载本次运行的构建产物，使用 PyPA 官方 action 的 OIDC 身份发布，
+   不需要设置 `PYPI_TOKEN` 或用户名/密码 secret。
+
+PyPI 发布是公开且持久的；首次发布前检查 wheel/sdist 内容与真实元数据。
+新版本请先修改 `pyproject.toml`，重新验证，再创建匹配的新 tag/release。
+已经用过的版本和分发文件不能直接覆盖。
+
+官方说明：
+
+- [Python 项目打包](https://packaging.python.org/en/latest/tutorials/packaging-projects/)
+- [创建 Pending Trusted Publisher](https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/)
+- [通过 Trusted Publisher 发布](https://docs.pypi.org/trusted-publishers/using-a-publisher/)
+- [PyPI 名称政策](https://docs.pypi.org/project-management/name-retention/#invalid-projects)

rstimes-0.1.0/README.md

@@ -0,0 +1,118 @@
+# rsTimes
+
+`rsTimes` 0.1.0 是一个纯 Python 日期时间小工具，提供带时区 `datetime`
+与 Unix 毫秒时间戳的双向转换。没有运行时依赖，要求 Python 3.10 或更新版本。
+当前版本没有 Rust 内核，不承诺性能优势或与其他日期时间库兼容。
+
+PyPI 分发名是 `rsTimes`，Python 导入名是 `rstimes`。
+
+## 使用
+
+首次成功发布到 PyPI 后可安装：
+
+```sh
+python -m pip install rsTimes
+```
+
+```python
+from datetime import datetime, timedelta, timezone
+from rstimes import from_unix_ms, to_unix_ms
+
+local_epoch = datetime(1970, 1, 1, 8, tzinfo=timezone(timedelta(hours=8)))
+assert to_unix_ms(local_epoch) == 0
+assert from_unix_ms(0) == datetime(1970, 1, 1, tzinfo=timezone.utc)
+
+before_epoch = datetime(1969, 12, 31, 23, 59, 59, 999999, tzinfo=timezone.utc)
+assert to_unix_ms(before_epoch) == -1
+assert from_unix_ms(-1).isoformat() == "1969-12-31T23:59:59.999000+00:00"
+```
+
+## 转换规则
+
+- `to_unix_ms(value: datetime) -> int`：输入必须带有效 UTC 偏移，
+  转换到 UTC 后用整数计算。微秒余数**向负无穷方向取整**：
+  纪元后 999 微秒得到 `0`，纪元前 1 微秒得到 `-1`。
+- `from_unix_ms(value: int) -> datetime`：只接受整数，拒绝 `bool`、
+  浮点数、字符串等类型；返回 `timezone.utc` 的带时区时间。
+- 毫秒范围为 `-62135596800000` 到 `253402300799999`，含两端，
+  对应 UTC 年份 1–9999。超出范围或时区转换越界抛出 `ValueError`；
+  naive datetime 也抛出 `ValueError`，非法输入类型抛出 `TypeError`。
+- 不使用本机时区、不经过浮点时间戳。毫秒整数可以精确往返；
+  datetime 的不足 1 毫秒部分在转换时会丢失。
+
+## 本地开发与构建
+
+以下命令适用于 macOS/Linux；Windows 可用 `.venv\Scripts\python`。
+
+```sh
+python3 -m venv .venv
+.venv/bin/python -m pip install --index-url https://pypi.org/simple -e ".[test]" build twine
+.venv/bin/python -m pytest
+.venv/bin/python -m build
+.venv/bin/python -m twine check --strict dist/*
+
+.venv/bin/python -m venv .wheel-test
+.wheel-test/bin/python -m pip install --no-deps dist/*.whl
+.wheel-test/bin/python -I -c 'from rstimes import from_unix_ms, to_unix_ms; assert to_unix_ms(from_unix_ms(-1)) == -1'
+```
+
+重新构建前清理旧的 `dist/` 内容，避免混入以前的发布文件。
+CI 配置会在 GitHub 的 Ubuntu runner 上使用 Python 3.10 和 3.13 测试、构建、
+检查元数据，并从 wheel 安装验证导入；这些配置不代表已在所有平台完成测试。
+
+## 发布前需要填写的信息
+
+维护者需要自行填写真实信息：
+
+| 项目 | 当前状态 |
+| --- | --- |
+| GitHub owner | 待填写本人账号或组织名 |
+| GitHub repository | 待填写实际仓库名 |
+| 许可证 | [MIT](LICENSE)，Copyright (c) 2026 Jiefu Chen |
+| 作者与项目 URL | 尚未填写；按实际情况补充，不使用虚构身份或链接 |
+
+本项目采用 [MIT 许可证](LICENSE)，许可证文本随源码与分发包一同提供。
+
+PyPI 将没有功能或空包的占名项目视为无效项目。本版本提供实际的时间转换功能，
+README 和包描述应保持与实际功能一致。
+
+## GitHub → PyPI Trusted Publisher
+
+本地配置已经准备好，以下持久授权和发布操作由维护者完成：
+
+1. 补齐需要的真实元数据；自行把这些文件提交并推送到自己的 GitHub
+   仓库。CI 成功后再准备正式 release。
+2. 在该 GitHub 仓库的 Settings → Environments 中创建名为 `pypi` 的 environment。
+   如有需要，为它配置审批人和允许发布的 tag 规则。
+3. 若 PyPI 尚无该项目，在自己的 PyPI 账号 Publishing 页面添加 **Pending Publisher**，
+   选择 GitHub，准确填写下表。已有项目则在该项目的 Publishing 页面添加 publisher。
+
+   | PyPI 字段 | 必须填写的值 |
+   | --- | --- |
+   | PyPI Project Name（pending 时） | `rsTimes` |
+   | Owner | 实际 GitHub owner，须与仓库所属账号或组织一致 |
+   | Repository name | 实际 GitHub 仓库名 |
+   | Workflow name | `publish.yml`（文件名，不是 workflow 显示名称） |
+   | Environment name | `pypi` |
+
+   Pending Publisher 在首次成功上传前不会创建项目或预留包名；名称也可能已被占用
+   或被 PyPI 保留。首次成功发布后 pending publisher 转为正式 publisher。
+4. 当前 `pyproject.toml` 的版本为 `0.1.0`。在包含上述文件的 commit 上创建 tag
+   `v0.1.0`，再发布对应的 GitHub Release。仅推送 tag 或保存 release 草稿不会触发上传。
+5. `.github/workflows/publish.yml` 只响应 `release: published`，检查 tag 与包版本
+   精确匹配（必须是 `v` 加版本号），随后测试、构建、检查 sdist/wheel 并验证 wheel。
+   只有这些步骤全部成功才会进入发布 job。
+6. 发布 job 使用 `environment: pypi`，仅该 job 有 `id-token: write`。
+   它只下载本次运行的构建产物，使用 PyPA 官方 action 的 OIDC 身份发布，
+   不需要设置 `PYPI_TOKEN` 或用户名/密码 secret。
+
+PyPI 发布是公开且持久的；首次发布前检查 wheel/sdist 内容与真实元数据。
+新版本请先修改 `pyproject.toml`，重新验证，再创建匹配的新 tag/release。
+已经用过的版本和分发文件不能直接覆盖。
+
+官方说明：
+
+- [Python 项目打包](https://packaging.python.org/en/latest/tutorials/packaging-projects/)
+- [创建 Pending Trusted Publisher](https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/)
+- [通过 Trusted Publisher 发布](https://docs.pypi.org/trusted-publishers/using-a-publisher/)
+- [PyPI 名称政策](https://docs.pypi.org/project-management/name-retention/#invalid-projects)

rstimes-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["setuptools>=77.0.3"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "rsTimes"
+version = "0.1.0"
+description = "Integer-based conversions between aware datetimes and Unix milliseconds"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+dependencies = []
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Typing :: Typed",
+]
+# Authors and repository URLs await the maintainer's decision.
+
+[project.optional-dependencies]
+test = ["pytest>=8"]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+include-package-data = false
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["rstimes"]
+
+[tool.setuptools.package-data]
+rstimes = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"

rstimes-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

rstimes-0.1.0/src/rsTimes.egg-info/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: rsTimes
+Version: 0.1.0
+Summary: Integer-based conversions between aware datetimes and Unix milliseconds
+License-Expression: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Dynamic: license-file
+
+# rsTimes
+
+`rsTimes` 0.1.0 是一个纯 Python 日期时间小工具，提供带时区 `datetime`
+与 Unix 毫秒时间戳的双向转换。没有运行时依赖，要求 Python 3.10 或更新版本。
+当前版本没有 Rust 内核，不承诺性能优势或与其他日期时间库兼容。
+
+PyPI 分发名是 `rsTimes`，Python 导入名是 `rstimes`。
+
+## 使用
+
+首次成功发布到 PyPI 后可安装：
+
+```sh
+python -m pip install rsTimes
+```
+
+```python
+from datetime import datetime, timedelta, timezone
+from rstimes import from_unix_ms, to_unix_ms
+
+local_epoch = datetime(1970, 1, 1, 8, tzinfo=timezone(timedelta(hours=8)))
+assert to_unix_ms(local_epoch) == 0
+assert from_unix_ms(0) == datetime(1970, 1, 1, tzinfo=timezone.utc)
+
+before_epoch = datetime(1969, 12, 31, 23, 59, 59, 999999, tzinfo=timezone.utc)
+assert to_unix_ms(before_epoch) == -1
+assert from_unix_ms(-1).isoformat() == "1969-12-31T23:59:59.999000+00:00"
+```
+
+## 转换规则
+
+- `to_unix_ms(value: datetime) -> int`：输入必须带有效 UTC 偏移，
+  转换到 UTC 后用整数计算。微秒余数**向负无穷方向取整**：
+  纪元后 999 微秒得到 `0`，纪元前 1 微秒得到 `-1`。
+- `from_unix_ms(value: int) -> datetime`：只接受整数，拒绝 `bool`、
+  浮点数、字符串等类型；返回 `timezone.utc` 的带时区时间。
+- 毫秒范围为 `-62135596800000` 到 `253402300799999`，含两端，
+  对应 UTC 年份 1–9999。超出范围或时区转换越界抛出 `ValueError`；
+  naive datetime 也抛出 `ValueError`，非法输入类型抛出 `TypeError`。
+- 不使用本机时区、不经过浮点时间戳。毫秒整数可以精确往返；
+  datetime 的不足 1 毫秒部分在转换时会丢失。
+
+## 本地开发与构建
+
+以下命令适用于 macOS/Linux；Windows 可用 `.venv\Scripts\python`。
+
+```sh
+python3 -m venv .venv
+.venv/bin/python -m pip install --index-url https://pypi.org/simple -e ".[test]" build twine
+.venv/bin/python -m pytest
+.venv/bin/python -m build
+.venv/bin/python -m twine check --strict dist/*
+
+.venv/bin/python -m venv .wheel-test
+.wheel-test/bin/python -m pip install --no-deps dist/*.whl
+.wheel-test/bin/python -I -c 'from rstimes import from_unix_ms, to_unix_ms; assert to_unix_ms(from_unix_ms(-1)) == -1'
+```
+
+重新构建前清理旧的 `dist/` 内容，避免混入以前的发布文件。
+CI 配置会在 GitHub 的 Ubuntu runner 上使用 Python 3.10 和 3.13 测试、构建、
+检查元数据，并从 wheel 安装验证导入；这些配置不代表已在所有平台完成测试。
+
+## 发布前需要填写的信息
+
+维护者需要自行填写真实信息：
+
+| 项目 | 当前状态 |
+| --- | --- |
+| GitHub owner | 待填写本人账号或组织名 |
+| GitHub repository | 待填写实际仓库名 |
+| 许可证 | [MIT](LICENSE)，Copyright (c) 2026 Jiefu Chen |
+| 作者与项目 URL | 尚未填写；按实际情况补充，不使用虚构身份或链接 |
+
+本项目采用 [MIT 许可证](LICENSE)，许可证文本随源码与分发包一同提供。
+
+PyPI 将没有功能或空包的占名项目视为无效项目。本版本提供实际的时间转换功能，
+README 和包描述应保持与实际功能一致。
+
+## GitHub → PyPI Trusted Publisher
+
+本地配置已经准备好，以下持久授权和发布操作由维护者完成：
+
+1. 补齐需要的真实元数据；自行把这些文件提交并推送到自己的 GitHub
+   仓库。CI 成功后再准备正式 release。
+2. 在该 GitHub 仓库的 Settings → Environments 中创建名为 `pypi` 的 environment。
+   如有需要，为它配置审批人和允许发布的 tag 规则。
+3. 若 PyPI 尚无该项目，在自己的 PyPI 账号 Publishing 页面添加 **Pending Publisher**，
+   选择 GitHub，准确填写下表。已有项目则在该项目的 Publishing 页面添加 publisher。
+
+   | PyPI 字段 | 必须填写的值 |
+   | --- | --- |
+   | PyPI Project Name（pending 时） | `rsTimes` |
+   | Owner | 实际 GitHub owner，须与仓库所属账号或组织一致 |
+   | Repository name | 实际 GitHub 仓库名 |
+   | Workflow name | `publish.yml`（文件名，不是 workflow 显示名称） |
+   | Environment name | `pypi` |
+
+   Pending Publisher 在首次成功上传前不会创建项目或预留包名；名称也可能已被占用
+   或被 PyPI 保留。首次成功发布后 pending publisher 转为正式 publisher。
+4. 当前 `pyproject.toml` 的版本为 `0.1.0`。在包含上述文件的 commit 上创建 tag
+   `v0.1.0`，再发布对应的 GitHub Release。仅推送 tag 或保存 release 草稿不会触发上传。
+5. `.github/workflows/publish.yml` 只响应 `release: published`，检查 tag 与包版本
+   精确匹配（必须是 `v` 加版本号），随后测试、构建、检查 sdist/wheel 并验证 wheel。
+   只有这些步骤全部成功才会进入发布 job。
+6. 发布 job 使用 `environment: pypi`，仅该 job 有 `id-token: write`。
+   它只下载本次运行的构建产物，使用 PyPA 官方 action 的 OIDC 身份发布，
+   不需要设置 `PYPI_TOKEN` 或用户名/密码 secret。
+
+PyPI 发布是公开且持久的；首次发布前检查 wheel/sdist 内容与真实元数据。
+新版本请先修改 `pyproject.toml`，重新验证，再创建匹配的新 tag/release。
+已经用过的版本和分发文件不能直接覆盖。
+
+官方说明：
+
+- [Python 项目打包](https://packaging.python.org/en/latest/tutorials/packaging-projects/)
+- [创建 Pending Trusted Publisher](https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/)
+- [通过 Trusted Publisher 发布](https://docs.pypi.org/trusted-publishers/using-a-publisher/)
+- [PyPI 名称政策](https://docs.pypi.org/project-management/name-retention/#invalid-projects)

rstimes-0.1.0/src/rsTimes.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+src/rsTimes.egg-info/PKG-INFO
+src/rsTimes.egg-info/SOURCES.txt
+src/rsTimes.egg-info/dependency_links.txt
+src/rsTimes.egg-info/requires.txt
+src/rsTimes.egg-info/top_level.txt
+src/rstimes/__init__.py
+src/rstimes/py.typed
+tests/test_rstimes.py

rstimes-0.1.0/src/rsTimes.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

rstimes-0.1.0/src/rsTimes.egg-info/requires.txt

@@ -0,0 +1,3 @@
+
+[test]
+pytest>=8

rstimes-0.1.0/src/rsTimes.egg-info/top_level.txt

@@ -0,0 +1 @@
+rstimes

rstimes-0.1.0/src/rstimes/__init__.py

@@ -0,0 +1,47 @@
+"""Exact conversions between aware datetimes and Unix milliseconds."""
+
+from datetime import datetime, timedelta, timezone
+
+__all__ = ["to_unix_ms", "from_unix_ms"]
+
+_EPOCH = datetime(1970, 1, 1, tzinfo=timezone.utc)
+
+
+def to_unix_ms(value: datetime) -> int:
+    """Return Unix milliseconds, flooring any sub-millisecond remainder.
+
+    ``value`` must be timezone-aware and representable in UTC. For example,
+    one microsecond before the epoch returns -1, not 0. All arithmetic is
+    integer-based; the host's local timezone is never used.
+
+    Raises:
+        TypeError: If value is not a datetime.
+        ValueError: If value is naive or outside the supported UTC range.
+    """
+    if not isinstance(value, datetime):
+        raise TypeError("value must be a datetime")
+    if value.utcoffset() is None:
+        raise ValueError("value must be timezone-aware")
+    try:
+        delta = value.astimezone(timezone.utc) - _EPOCH
+    except OverflowError as exc:
+        raise ValueError("value is outside the supported UTC datetime range") from exc
+    return (delta.days * 86_400 + delta.seconds) * 1_000 + delta.microseconds // 1_000
+
+
+def from_unix_ms(value: int) -> datetime:
+    """Return a UTC-aware datetime for integer Unix milliseconds.
+
+    Negative values represent instants before 1970-01-01T00:00:00Z.
+    The accepted range is -62135596800000 through 253402300799999, inclusive.
+
+    Raises:
+        TypeError: If value is not an int, or is a bool.
+        ValueError: If value is outside Python's datetime range (years 1–9999).
+    """
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise TypeError("value must be an int, not bool or another type")
+    try:
+        return _EPOCH + timedelta(microseconds=value * 1_000)
+    except OverflowError as exc:
+        raise ValueError("value is outside the supported UTC datetime range") from exc

rstimes-0.1.0/tests/test_rstimes.py

@@ -0,0 +1,91 @@
+from datetime import date, datetime, timedelta, timezone, tzinfo
+from decimal import Decimal
+
+import pytest
+
+from rstimes import from_unix_ms, to_unix_ms
+
+EPOCH = datetime(1970, 1, 1, tzinfo=timezone.utc)
+MIN_MS = -62_135_596_800_000
+MAX_MS = 253_402_300_799_999
+
+
+@pytest.mark.parametrize(
+    ("microseconds", "milliseconds"),
+    [(-1001, -2), (-1000, -1), (-999, -1), (-1, -1),
+     (0, 0), (1, 0), (999, 0), (1000, 1), (1001, 1)],
+)
+def test_floor_submillisecond_precision(microseconds, milliseconds):
+    assert to_unix_ms(EPOCH + timedelta(microseconds=microseconds)) == milliseconds
+
+
+@pytest.mark.parametrize(
+    "offset", [timedelta(hours=8), timedelta(hours=-7),
+               timedelta(hours=5, minutes=30, microseconds=500)],
+)
+def test_offset_datetimes_represent_the_same_instant(offset):
+    value = (EPOCH + offset).replace(tzinfo=timezone(offset))
+    assert to_unix_ms(value) == 0
+
+
+@pytest.mark.parametrize("milliseconds", [MIN_MS, -86_400_001, -1001, -1, 0, 1,
+                                          1_700_000_000_123, MAX_MS])
+def test_integer_roundtrip_and_utc_result(milliseconds):
+    result = from_unix_ms(milliseconds)
+    assert result.tzinfo is timezone.utc
+    assert to_unix_ms(result) == milliseconds
+
+
+def test_negative_millisecond_has_expected_date():
+    assert from_unix_ms(-1) == datetime(1969, 12, 31, 23, 59, 59, 999000,
+                                      tzinfo=timezone.utc)
+
+
+def test_datetime_limits_and_far_future_precision():
+    assert from_unix_ms(MIN_MS) == datetime.min.replace(tzinfo=timezone.utc)
+    assert from_unix_ms(MAX_MS) == datetime(9999, 12, 31, 23, 59, 59, 999000,
+                                          tzinfo=timezone.utc)
+    assert to_unix_ms(datetime.max.replace(tzinfo=timezone.utc)) == MAX_MS
+    assert to_unix_ms(datetime(9999, 12, 31, 23, 59, 59, 998999,
+                              tzinfo=timezone.utc)) == MAX_MS - 1
+
+
+@pytest.mark.parametrize("value", [None, True, False, 1, 1.5, "1970-01-01",
+                                   date(1970, 1, 1), object()])
+def test_to_unix_ms_rejects_non_datetime(value):
+    with pytest.raises(TypeError):
+        to_unix_ms(value)
+
+
+class NoOffset(tzinfo):
+    def utcoffset(self, value):
+        return None
+
+
+@pytest.mark.parametrize("value", [datetime(1970, 1, 1),
+                                   datetime(1970, 1, 1, tzinfo=NoOffset())])
+def test_to_unix_ms_rejects_naive_datetime(value):
+    with pytest.raises(ValueError, match="timezone-aware"):
+        to_unix_ms(value)
+
+
+@pytest.mark.parametrize("value", [None, True, False, 1.0, "1", Decimal("1"),
+                                   EPOCH, object()])
+def test_from_unix_ms_rejects_non_integer_and_bool(value):
+    with pytest.raises(TypeError):
+        from_unix_ms(value)
+
+
+@pytest.mark.parametrize("value", [MIN_MS - 1, MAX_MS + 1, -(10**100), 10**100])
+def test_from_unix_ms_rejects_out_of_range_integer(value):
+    with pytest.raises(ValueError, match="range"):
+        from_unix_ms(value)
+
+
+@pytest.mark.parametrize("value", [
+    datetime.min.replace(tzinfo=timezone(timedelta(hours=1))),
+    datetime.max.replace(tzinfo=timezone(timedelta(hours=-1))),
+])
+def test_to_unix_ms_rejects_out_of_range_utc_conversion(value):
+    with pytest.raises(ValueError, match="range"):
+        to_unix_ms(value)