fly-hour-timer 1.1.3__tar.gz

fly_hour_timer-1.1.3/PKG-INFO

@@ -0,0 +1,147 @@
+Metadata-Version: 2.4
+Name: fly_hour_timer
+Version: 1.1.3
+Summary: A timezone-free Python time library: represents time as <hour>.<min_sec>
+Author: fly
+License: MIT
+Keywords: time,timezone-free,hour-timer,ai-bot,unix-time
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# fly_hour_timer
+
+**English** | [简体中文](README_zh.md)
+
+A timezone-free Python time library that represents time as **`<hour>.<min_sec>`**.
+
+The core idea: express time as `<hour>.<min_sec>`, where the **hour is simply
+`unix_time // 3600`** (whole hours elapsed since the unix epoch) and `<min_sec>`
+is the minutes and seconds inside that hour. Because everything is derived
+directly from the absolute unix time, the string is fully timezone-free and
+identical on any machine anywhere — especially friendly for AI bots that
+exchange timestamps across regions.
+
+- No third-party dependency, pure standard library (`datetime` / `time` only)
+- Fully timezone-free by construction
+- Python >= 3.8
+
+## Installation
+
+```bash
+pip install fly_hour_timer
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/fly-ttrr/fly_hour_timer.git
+cd fly_hour_timer
+pip install .
+```
+
+## Quick Start
+
+`fly_hour_timer` is a static tool — no instance configuration required:
+
+```python
+from fly_hour_timer import fly_hour_timer
+
+fly_hour_timer.hour()             # '277777'    -> hour (unix_time // 3600), str
+fly_hour_timer.min_sec()          # '4640'      -> minutes + seconds, str
+fly_hour_timer.hour_timer()       # '277777.4640'  -> <hour>.<min_sec>
+fly_hour_timer.hour_timer_short() # '777.4640'  -> <last 3 digits of hour>.<min_sec>
+```
+
+With an explicit unix time (seconds):
+
+```python
+from fly_hour_timer import FlyHourTimer
+
+FlyHourTimer.hour_timer(1_000_000_000)          # '277777.4640'
+FlyHourTimer.hour_timer_short(1_000_000_000)    # '777.4640'
+```
+
+## API
+
+| Method | Description | Returns |
+| --- | --- | --- |
+| `hour(unix_time=None)` | Whole hours since the epoch, `unix_time // 3600` | `str` |
+| `min_sec(unix_time=None)` | Minutes + seconds inside the hour, 4 digits (`'0102'` = 01m02s) | `str` |
+| `hour_timer(unix_time=None)` | `<hour>.<min_sec>` | `str` |
+| `hour_timer_short(unix_time=None)` | `<last 3 digits of hour>.<min_sec>` | `str` |
+| `hour_timer_to_time(hour_timer)` | Parse `<hour>.<min_sec>` back into a UTC `time.struct_time` | `time.struct_time` |
+
+### Parameters
+
+- **`unix_time`** — unix time in seconds (`int` / `float` / numeric `str`).
+  Omit to use the current time.
+
+## How it works
+
+Given a unix time in seconds:
+
+```
+hour    = unix_time // 3600        # whole hours since the epoch
+rem     = unix_time - hour * 3600  # seconds left inside the hour (0..3599)
+min_sec = "%02d%02d" % (rem // 60, rem % 60)
+```
+
+- `hour_timer()`  -> `f"{hour}.{min_sec}"`
+- `hour_timer_short()` -> `f"{hour % 1000:03d}.{min_sec}"` — the last 3 digits
+  of the hour roll over roughly every 1000 hours (~41.7 days), giving a compact,
+  timezone-free time id for logs and bot conversations.
+
+No timezone parameter is needed: the hour count and the leftover minutes/seconds
+come straight from the absolute unix time, so the result is the same everywhere.
+
+## Reverse Conversion: `hour_timer_to_time()`
+
+Since `<hour>` already encodes the total elapsed hours since the epoch (and thus
+the full date), the conversion back is complete and needs no "today" anchor. It
+returns a UTC `time.struct_time`:
+
+```python
+from fly_hour_timer import FlyHourTimer
+
+st = FlyHourTimer.hour_timer_to_time("277777.4640")
+# time.struct_time(... 2001, 9, 9, 1, 46, 40 ...)
+st.tm_hour, st.tm_min, st.tm_sec   # (1, 46, 40)
+```
+
+It is the exact inverse of `hour_timer()` for the clock fields, and raises
+`ValueError` on malformed or out-of-range input (e.g. minutes `>= 60`).
+
+> Note: pass the **full** `hour_timer()` string here. A short string like
+> `'777.4640'` (from `hour_timer_short()`) has lost the high-order hour digits,
+> so it reconstructs a different (much earlier) instant.
+
+## Examples
+
+```python
+>>> from fly_hour_timer import FlyHourTimer
+>>> FlyHourTimer.hour_timer(0)
+'0.0000'
+>>> FlyHourTimer.hour_timer(1_000_000_000)
+'277777.4640'
+>>> FlyHourTimer.hour_timer_short(1_000_000_000)
+'777.4640'
+```
+
+Run `python examples.py` in this repository for a live demo.
+
+## Tests
+
+```bash
+python tests/test_fly_hour_timer.py
+```
+
+## License
+
+MIT

fly_hour_timer-1.1.3/README.md

@@ -0,0 +1,130 @@
+# fly_hour_timer
+
+**English** | [简体中文](README_zh.md)
+
+A timezone-free Python time library that represents time as **`<hour>.<min_sec>`**.
+
+The core idea: express time as `<hour>.<min_sec>`, where the **hour is simply
+`unix_time // 3600`** (whole hours elapsed since the unix epoch) and `<min_sec>`
+is the minutes and seconds inside that hour. Because everything is derived
+directly from the absolute unix time, the string is fully timezone-free and
+identical on any machine anywhere — especially friendly for AI bots that
+exchange timestamps across regions.
+
+- No third-party dependency, pure standard library (`datetime` / `time` only)
+- Fully timezone-free by construction
+- Python >= 3.8
+
+## Installation
+
+```bash
+pip install fly_hour_timer
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/fly-ttrr/fly_hour_timer.git
+cd fly_hour_timer
+pip install .
+```
+
+## Quick Start
+
+`fly_hour_timer` is a static tool — no instance configuration required:
+
+```python
+from fly_hour_timer import fly_hour_timer
+
+fly_hour_timer.hour()             # '277777'    -> hour (unix_time // 3600), str
+fly_hour_timer.min_sec()          # '4640'      -> minutes + seconds, str
+fly_hour_timer.hour_timer()       # '277777.4640'  -> <hour>.<min_sec>
+fly_hour_timer.hour_timer_short() # '777.4640'  -> <last 3 digits of hour>.<min_sec>
+```
+
+With an explicit unix time (seconds):
+
+```python
+from fly_hour_timer import FlyHourTimer
+
+FlyHourTimer.hour_timer(1_000_000_000)          # '277777.4640'
+FlyHourTimer.hour_timer_short(1_000_000_000)    # '777.4640'
+```
+
+## API
+
+| Method | Description | Returns |
+| --- | --- | --- |
+| `hour(unix_time=None)` | Whole hours since the epoch, `unix_time // 3600` | `str` |
+| `min_sec(unix_time=None)` | Minutes + seconds inside the hour, 4 digits (`'0102'` = 01m02s) | `str` |
+| `hour_timer(unix_time=None)` | `<hour>.<min_sec>` | `str` |
+| `hour_timer_short(unix_time=None)` | `<last 3 digits of hour>.<min_sec>` | `str` |
+| `hour_timer_to_time(hour_timer)` | Parse `<hour>.<min_sec>` back into a UTC `time.struct_time` | `time.struct_time` |
+
+### Parameters
+
+- **`unix_time`** — unix time in seconds (`int` / `float` / numeric `str`).
+  Omit to use the current time.
+
+## How it works
+
+Given a unix time in seconds:
+
+```
+hour    = unix_time // 3600        # whole hours since the epoch
+rem     = unix_time - hour * 3600  # seconds left inside the hour (0..3599)
+min_sec = "%02d%02d" % (rem // 60, rem % 60)
+```
+
+- `hour_timer()`  -> `f"{hour}.{min_sec}"`
+- `hour_timer_short()` -> `f"{hour % 1000:03d}.{min_sec}"` — the last 3 digits
+  of the hour roll over roughly every 1000 hours (~41.7 days), giving a compact,
+  timezone-free time id for logs and bot conversations.
+
+No timezone parameter is needed: the hour count and the leftover minutes/seconds
+come straight from the absolute unix time, so the result is the same everywhere.
+
+## Reverse Conversion: `hour_timer_to_time()`
+
+Since `<hour>` already encodes the total elapsed hours since the epoch (and thus
+the full date), the conversion back is complete and needs no "today" anchor. It
+returns a UTC `time.struct_time`:
+
+```python
+from fly_hour_timer import FlyHourTimer
+
+st = FlyHourTimer.hour_timer_to_time("277777.4640")
+# time.struct_time(... 2001, 9, 9, 1, 46, 40 ...)
+st.tm_hour, st.tm_min, st.tm_sec   # (1, 46, 40)
+```
+
+It is the exact inverse of `hour_timer()` for the clock fields, and raises
+`ValueError` on malformed or out-of-range input (e.g. minutes `>= 60`).
+
+> Note: pass the **full** `hour_timer()` string here. A short string like
+> `'777.4640'` (from `hour_timer_short()`) has lost the high-order hour digits,
+> so it reconstructs a different (much earlier) instant.
+
+## Examples
+
+```python
+>>> from fly_hour_timer import FlyHourTimer
+>>> FlyHourTimer.hour_timer(0)
+'0.0000'
+>>> FlyHourTimer.hour_timer(1_000_000_000)
+'277777.4640'
+>>> FlyHourTimer.hour_timer_short(1_000_000_000)
+'777.4640'
+```
+
+Run `python examples.py` in this repository for a live demo.
+
+## Tests
+
+```bash
+python tests/test_fly_hour_timer.py
+```
+
+## License
+
+MIT

fly_hour_timer-1.1.3/README_zh.md

@@ -0,0 +1,127 @@
+# fly_hour_timer
+
+[English](README.md) | **简体中文**
+
+一个「无时区干扰」的 Python 时间库，用 **`<小时>.<分秒>`** 表示时间。
+
+核心思想：用 `<小时>.<分秒>` 表达时间，其中**小时就是 `unix_time // 3600`**
+（自 unix 纪元以来经过的整小时数），`<分秒>` 是该小时内的分钟和秒。因为一切都
+直接由绝对的 unix 时间推导而来，所以这个字符串完全与时区无关，在任何机器、任何
+地域得到的结果都一致——尤其适合在不同地域之间交换时间戳的 AI Bot 使用。
+
+- 无第三方依赖，纯标准库（仅用到 `datetime` / `time`）
+- 与生俱来的时区无关
+- 支持 Python >= 3.8
+
+## 安装
+
+```bash
+pip install fly_hour_timer
+```
+
+或从源码安装：
+
+```bash
+git clone https://github.com/fly-ttrr/fly_hour_timer.git
+cd fly_hour_timer
+pip install .
+```
+
+## 快速开始
+
+`fly_hour_timer` 是一个静态工具，无需创建或配置实例：
+
+```python
+from fly_hour_timer import fly_hour_timer
+
+fly_hour_timer.hour()             # '277777'      -> 小时（unix_time // 3600），str
+fly_hour_timer.min_sec()          # '4640'        -> 分秒，str
+fly_hour_timer.hour_timer()       # '277777.4640' -> <小时>.<分秒>
+fly_hour_timer.hour_timer_short() # '777.4640'    -> <小时后三位>.<分秒>
+```
+
+传入指定的 unix 时间（秒）：
+
+```python
+from fly_hour_timer import FlyHourTimer
+
+FlyHourTimer.hour_timer(1_000_000_000)          # '277777.4640'
+FlyHourTimer.hour_timer_short(1_000_000_000)    # '777.4640'
+```
+
+## API
+
+| 方法 | 说明 | 返回类型 |
+| --- | --- | --- |
+| `hour(unix_time=None)` | 自纪元以来的整小时数，即 `unix_time // 3600` | `str` |
+| `min_sec(unix_time=None)` | 该小时内的分 + 秒拼接的 4 位（`'0102'` 表示 01 分 02 秒） | `str` |
+| `hour_timer(unix_time=None)` | `<小时>.<分秒>` | `str` |
+| `hour_timer_short(unix_time=None)` | `<小时后三位>.<分秒>` | `str` |
+| `hour_timer_to_time(hour_timer)` | 将 `<小时>.<分秒>` 解析回 UTC 的 `time.struct_time` | `time.struct_time` |
+
+### 参数说明
+
+- **`unix_time`** —— unix 时间，单位为秒（`int` / `float` / 数字字符串）。
+  不传则使用当前时间。
+
+## 原理
+
+给定以秒为单位的 unix 时间：
+
+```
+小时   = unix_time // 3600          # 自纪元以来的整小时数
+余秒   = unix_time - 小时 * 3600     # 该小时内剩余的秒数（0..3599）
+分秒   = "%02d%02d" % (余秒 // 60, 余秒 % 60)
+```
+
+- `hour_timer()`  -> `f"{小时}.{分秒}"`
+- `hour_timer_short()` -> `f"{小时 % 1000:03d}.{分秒}"`——小时后三位大约每
+  1000 小时（约 41.7 天）滚动一轮，是一个紧凑、与时区无关的时间标识，适合用于
+  日志与 Bot 对话。
+
+不需要任何时区参数：小时数与该小时内的分秒都直接来自绝对的 unix 时间，因此
+无论在哪台机器、哪个时区，结果都完全一致。
+
+## 逆向转换：`hour_timer_to_time()`
+
+由于 `<小时>` 已经编码了自纪元以来的累计小时数（因而也包含了完整日期），逆向
+转换是完备的，不需要「今天」作为锚点。它返回一个 UTC 的 `time.struct_time`：
+
+```python
+from fly_hour_timer import FlyHourTimer
+
+st = FlyHourTimer.hour_timer_to_time("277777.4640")
+# time.struct_time(... 2001, 9, 9, 1, 46, 40 ...)
+st.tm_hour, st.tm_min, st.tm_sec   # (1, 46, 40)
+```
+
+它对时钟字段而言是 `hour_timer()` 的精确逆运算；当输入格式非法或越界（例如
+分钟 `>= 60`）时会抛出 `ValueError`。
+
+> 注意：请传入**完整的** `hour_timer()` 字符串。像 `'777.4640'`（来自
+> `hour_timer_short()`）这样的短字符串已经丢弃了高位小时数字，因此会重构成
+> 一个不同的（更早的）时刻。
+
+## 示例
+
+```python
+>>> from fly_hour_timer import FlyHourTimer
+>>> FlyHourTimer.hour_timer(0)
+'0.0000'
+>>> FlyHourTimer.hour_timer(1_000_000_000)
+'277777.4640'
+>>> FlyHourTimer.hour_timer_short(1_000_000_000)
+'777.4640'
+```
+
+在本仓库运行 `python examples.py` 可查看实时演示。
+
+## 测试
+
+```bash
+python tests/test_fly_hour_timer.py
+```
+
+## 许可证
+
+MIT

fly_hour_timer-1.1.3/fly_hour_timer/__init__.py

@@ -0,0 +1,10 @@
+"""fly_hour_timer - a timezone-free time library: <hour>.<min_sec>"""
+
+from .fly_hour_timer import FlyHourTimer
+
+#: The static tool (alias of the :class:`FlyHourTimer` class). Call the methods
+#: directly, e.g. ``fly_hour_timer.hour_timer()``.
+fly_hour_timer = FlyHourTimer
+
+__all__ = ["FlyHourTimer", "fly_hour_timer"]
+__version__ = "0.3.0"

fly_hour_timer-1.1.3/fly_hour_timer/fly_hour_timer.py

@@ -0,0 +1,157 @@
+"""Core static utility of the fly_hour_timer library.
+
+Time representation: <hour>.<min_sec>
+
+The "hour" is simply ``unix_time // 3600`` -- the number of whole hours elapsed
+since the unix epoch. ``<min_sec>`` is the minutes and seconds inside that
+hour. Because everything is derived directly from the absolute unix time, the
+string is fully timezone-free and identical on any machine anywhere.
+"""
+
+import time as _time
+from datetime import datetime, timezone as dt_timezone
+
+__all__ = ["FlyHourTimer"]
+
+
+class FlyHourTimer:
+    """Static time tool: represents time as ``<hour>.<min_sec>``.
+
+    All methods are static; no instance is required.
+
+    >>> FlyHourTimer.hour_timer(1_000_000_000)   # 2001-09-09 01:46:40 UTC
+    '277777.4640'
+    >>> FlyHourTimer.hour_timer_short(1_000_000_000)
+    '777.4640'
+    >>> FlyHourTimer.hour_timer(0)               # the epoch
+    '0.0000'
+    """
+
+    # ------------------------------------------------------------------
+    # public API
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def hour(unix_time=None):
+        """Return the hour: whole hours elapsed since the unix epoch.
+
+        Equivalent to ``unix_time // 3600``.
+
+        Args:
+            unix_time: unix time in seconds (int/float/numeric str).
+                Defaults to the current time when omitted.
+
+        Returns:
+            str: e.g. ``'277777'``.
+        """
+        hours, _, _ = FlyHourTimer._split(unix_time)
+        return str(hours)
+
+    @staticmethod
+    def min_sec(unix_time=None):
+        """Return the ``<min_sec>`` part: minutes and seconds inside the hour.
+
+        Args:
+            unix_time: unix time in seconds, defaults to the current time.
+
+        Returns:
+            str: 4 digits ``MMSS``, e.g. ``'0102'`` means 01 min 02 sec.
+        """
+        _, minute, second = FlyHourTimer._split(unix_time)
+        return f"{minute:02d}{second:02d}"
+
+    @staticmethod
+    def hour_timer(unix_time=None):
+        """Return time as ``<hour>.<min_sec>``, where hour = ``unix_time // 3600``.
+
+        Args:
+            unix_time: unix time in seconds, defaults to the current time.
+
+        Returns:
+            str: e.g. ``'277777.4640'``.
+        """
+        hours, minute, second = FlyHourTimer._split(unix_time)
+        return f"{hours}.{minute:02d}{second:02d}"
+
+    @staticmethod
+    def hour_timer_short(unix_time=None):
+        """Return time as ``<last 3 digits of hour>.<min_sec>``.
+
+        The last 3 digits of the hour roll over roughly every 1000 hours
+        (~41.7 days), giving a compact, timezone-free time id for logs and
+        bot conversations.
+
+        Args:
+            unix_time: unix time in seconds, defaults to the current time.
+
+        Returns:
+            str: e.g. hour ``277777`` -> ``'777.4640'``.
+        """
+        hours, minute, second = FlyHourTimer._split(unix_time)
+        return f"{hours % 1000:03d}.{minute:02d}{second:02d}"
+
+    @staticmethod
+    def hour_timer_to_time(hour_timer):
+        """Convert a ``<hour>.<min_sec>`` string into a ``time.struct_time``.
+
+        Because ``<hour>`` already encodes the total elapsed hours since the
+        epoch (and therefore the date), this is a complete, timezone-free
+        inverse of :meth:`hour_timer` -- no "today" anchor is needed. The
+        result is UTC based (``time.gmtime``).
+
+        Args:
+            hour_timer: the ``<hour>.<min_sec>`` string, e.g.
+                ``'277777.4640'``.
+
+        Returns:
+            time.struct_time: UTC struct_time reconstructed from the string.
+
+        Raises:
+            ValueError: if ``hour_timer`` is malformed or out of range.
+        """
+        hours, minute, second = FlyHourTimer._parse_hour_timer(hour_timer)
+        unix_time = hours * 3600 + minute * 60 + second
+        return _time.gmtime(unix_time)
+
+    # ------------------------------------------------------------------
+    # internals
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _split(unix_time):
+        """Split a unix time into (total_hours, minute, second)."""
+        if unix_time is None:
+            ts = datetime.now(dt_timezone.utc).timestamp()
+        else:
+            ts = float(unix_time)
+        hours = int(ts // 3600)
+        rem = ts - hours * 3600  # seconds inside the hour, always in [0, 3600)
+        minute = int(rem // 60)
+        second = int(rem % 60)
+        return hours, minute, second
+
+    @staticmethod
+    def _parse_hour_timer(hour_timer):
+        """Parse ``'<hour>.<min_sec>'`` into (total_hours, minute, second)."""
+        if not isinstance(hour_timer, str):
+            raise ValueError(f"hour_timer must be a str, got {hour_timer!r}")
+        text = hour_timer.strip()
+        if text.count(".") != 1:
+            raise ValueError(
+                f"hour_timer must look like '<hour>.<min_sec>', got {hour_timer!r}"
+            )
+        hour_part, min_sec_part = text.split(".", 1)
+        if not min_sec_part.isdigit() or len(min_sec_part) != 4:
+            raise ValueError(
+                f"hour_timer '<min_sec>' must be 4 digits, got {hour_timer!r}"
+            )
+        try:
+            hours = int(hour_part)
+        except ValueError:
+            raise ValueError(
+                f"hour_timer '<hour>' must be an integer, got {hour_timer!r}"
+            ) from None
+        minute, second = int(min_sec_part[:2]), int(min_sec_part[2:])
+        if not (0 <= minute <= 59 and 0 <= second <= 59):
+            raise ValueError(f"hour_timer '<min_sec>' out of range, got {hour_timer!r}")
+        return hours, minute, second

fly_hour_timer-1.1.3/fly_hour_timer.egg-info/PKG-INFO

@@ -0,0 +1,147 @@
+Metadata-Version: 2.4
+Name: fly_hour_timer
+Version: 1.1.3
+Summary: A timezone-free Python time library: represents time as <hour>.<min_sec>
+Author: fly
+License: MIT
+Keywords: time,timezone-free,hour-timer,ai-bot,unix-time
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# fly_hour_timer
+
+**English** | [简体中文](README_zh.md)
+
+A timezone-free Python time library that represents time as **`<hour>.<min_sec>`**.
+
+The core idea: express time as `<hour>.<min_sec>`, where the **hour is simply
+`unix_time // 3600`** (whole hours elapsed since the unix epoch) and `<min_sec>`
+is the minutes and seconds inside that hour. Because everything is derived
+directly from the absolute unix time, the string is fully timezone-free and
+identical on any machine anywhere — especially friendly for AI bots that
+exchange timestamps across regions.
+
+- No third-party dependency, pure standard library (`datetime` / `time` only)
+- Fully timezone-free by construction
+- Python >= 3.8
+
+## Installation
+
+```bash
+pip install fly_hour_timer
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/fly-ttrr/fly_hour_timer.git
+cd fly_hour_timer
+pip install .
+```
+
+## Quick Start
+
+`fly_hour_timer` is a static tool — no instance configuration required:
+
+```python
+from fly_hour_timer import fly_hour_timer
+
+fly_hour_timer.hour()             # '277777'    -> hour (unix_time // 3600), str
+fly_hour_timer.min_sec()          # '4640'      -> minutes + seconds, str
+fly_hour_timer.hour_timer()       # '277777.4640'  -> <hour>.<min_sec>
+fly_hour_timer.hour_timer_short() # '777.4640'  -> <last 3 digits of hour>.<min_sec>
+```
+
+With an explicit unix time (seconds):
+
+```python
+from fly_hour_timer import FlyHourTimer
+
+FlyHourTimer.hour_timer(1_000_000_000)          # '277777.4640'
+FlyHourTimer.hour_timer_short(1_000_000_000)    # '777.4640'
+```
+
+## API
+
+| Method | Description | Returns |
+| --- | --- | --- |
+| `hour(unix_time=None)` | Whole hours since the epoch, `unix_time // 3600` | `str` |
+| `min_sec(unix_time=None)` | Minutes + seconds inside the hour, 4 digits (`'0102'` = 01m02s) | `str` |
+| `hour_timer(unix_time=None)` | `<hour>.<min_sec>` | `str` |
+| `hour_timer_short(unix_time=None)` | `<last 3 digits of hour>.<min_sec>` | `str` |
+| `hour_timer_to_time(hour_timer)` | Parse `<hour>.<min_sec>` back into a UTC `time.struct_time` | `time.struct_time` |
+
+### Parameters
+
+- **`unix_time`** — unix time in seconds (`int` / `float` / numeric `str`).
+  Omit to use the current time.
+
+## How it works
+
+Given a unix time in seconds:
+
+```
+hour    = unix_time // 3600        # whole hours since the epoch
+rem     = unix_time - hour * 3600  # seconds left inside the hour (0..3599)
+min_sec = "%02d%02d" % (rem // 60, rem % 60)
+```
+
+- `hour_timer()`  -> `f"{hour}.{min_sec}"`
+- `hour_timer_short()` -> `f"{hour % 1000:03d}.{min_sec}"` — the last 3 digits
+  of the hour roll over roughly every 1000 hours (~41.7 days), giving a compact,
+  timezone-free time id for logs and bot conversations.
+
+No timezone parameter is needed: the hour count and the leftover minutes/seconds
+come straight from the absolute unix time, so the result is the same everywhere.
+
+## Reverse Conversion: `hour_timer_to_time()`
+
+Since `<hour>` already encodes the total elapsed hours since the epoch (and thus
+the full date), the conversion back is complete and needs no "today" anchor. It
+returns a UTC `time.struct_time`:
+
+```python
+from fly_hour_timer import FlyHourTimer
+
+st = FlyHourTimer.hour_timer_to_time("277777.4640")
+# time.struct_time(... 2001, 9, 9, 1, 46, 40 ...)
+st.tm_hour, st.tm_min, st.tm_sec   # (1, 46, 40)
+```
+
+It is the exact inverse of `hour_timer()` for the clock fields, and raises
+`ValueError` on malformed or out-of-range input (e.g. minutes `>= 60`).
+
+> Note: pass the **full** `hour_timer()` string here. A short string like
+> `'777.4640'` (from `hour_timer_short()`) has lost the high-order hour digits,
+> so it reconstructs a different (much earlier) instant.
+
+## Examples
+
+```python
+>>> from fly_hour_timer import FlyHourTimer
+>>> FlyHourTimer.hour_timer(0)
+'0.0000'
+>>> FlyHourTimer.hour_timer(1_000_000_000)
+'277777.4640'
+>>> FlyHourTimer.hour_timer_short(1_000_000_000)
+'777.4640'
+```
+
+Run `python examples.py` in this repository for a live demo.
+
+## Tests
+
+```bash
+python tests/test_fly_hour_timer.py
+```
+
+## License
+
+MIT

fly_hour_timer-1.1.3/fly_hour_timer.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+README.md
+README_zh.md
+pyproject.toml
+fly_hour_timer/__init__.py
+fly_hour_timer/fly_hour_timer.py
+fly_hour_timer.egg-info/PKG-INFO
+fly_hour_timer.egg-info/SOURCES.txt
+fly_hour_timer.egg-info/dependency_links.txt
+fly_hour_timer.egg-info/top_level.txt
+tests/test_fly_hour_timer.py

fly_hour_timer-1.1.3/fly_hour_timer.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

fly_hour_timer-1.1.3/fly_hour_timer.egg-info/top_level.txt

@@ -0,0 +1 @@
+fly_hour_timer

fly_hour_timer-1.1.3/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "fly_hour_timer"
+version = "1.1.3"
+description = "A timezone-free Python time library: represents time as <hour>.<min_sec>"
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+keywords = ["time", "timezone-free", "hour-timer", "ai-bot", "unix-time"]
+authors = [{ name = "fly" }]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Utilities",
+]
+
+[tool.pytest.ini_options]
+addopts = "-p no:dash"
+
+[tool.setuptools]
+packages = ["fly_hour_timer"]
+
+[tool.setuptools.data-files]
+"share/fly_hour_timer" = ["README_zh.md"]

fly_hour_timer-1.1.3/setup.cfg

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

fly_hour_timer-1.1.3/tests/test_fly_hour_timer.py

@@ -0,0 +1,124 @@
+"""Unit tests for fly_hour_timer (no third-party dependency needed).
+
+Run:  python tests/test_fly_hour_timer.py
+"""
+
+import os
+import sys
+import time
+import unittest
+from datetime import datetime, timezone as dt_timezone
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from fly_hour_timer import FlyHourTimer, fly_hour_timer
+
+# 2001-09-09 01:46:40 UTC -> 1_000_000_000 // 3600 == 277777 hours
+UNIX_911 = 1_000_000_000
+
+
+class TestStaticMethods(unittest.TestCase):
+    def test_hour(self):
+        self.assertEqual(FlyHourTimer.hour(UNIX_911), "277777")
+
+    def test_hour_epoch(self):
+        self.assertEqual(FlyHourTimer.hour(0), "0")
+
+    def test_min_sec(self):
+        self.assertEqual(FlyHourTimer.min_sec(UNIX_911), "4640")
+
+    def test_min_sec_padding(self):
+        # 1970-01-01 00:01:02 UTC -> 01 min 02 sec
+        self.assertEqual(FlyHourTimer.min_sec(62), "0102")
+
+    def test_hour_timer(self):
+        self.assertEqual(FlyHourTimer.hour_timer(UNIX_911), "277777.4640")
+
+    def test_hour_timer_epoch(self):
+        self.assertEqual(FlyHourTimer.hour_timer(0), "0.0000")
+
+    def test_hour_timer_short(self):
+        self.assertEqual(FlyHourTimer.hour_timer_short(UNIX_911), "777.4640")
+
+    def test_hour_timer_short_epoch(self):
+        self.assertEqual(FlyHourTimer.hour_timer_short(0), "000.0000")
+
+    def test_hour_matches_division(self):
+        # the hour is exactly unix_time // 3600, timezone-free
+        for ts in (0, 3599, 3600, 7199, UNIX_911, 1_700_000_000):
+            self.assertEqual(
+                FlyHourTimer.hour(ts), str(ts // 3600)
+            )
+
+    def test_min_sec_matches_remainder(self):
+        # min_sec reflects the seconds left over after whole hours
+        for ts in (62, 3599, UNIX_911):
+            rem = ts - (ts // 3600) * 3600
+            expected = f"{rem // 60:02d}{rem % 60:02d}"
+            self.assertEqual(FlyHourTimer.min_sec(ts), expected)
+
+    def test_unix_time_float_and_str(self):
+        self.assertEqual(FlyHourTimer.hour_timer(1_000_000_000.0), "277777.4640")
+        self.assertEqual(FlyHourTimer.hour_timer("1000000000"), "277777.4640")
+
+    def test_default_returns_str(self):
+        for value in (
+            FlyHourTimer.hour(),
+            FlyHourTimer.min_sec(),
+            FlyHourTimer.hour_timer(),
+            FlyHourTimer.hour_timer_short(),
+        ):
+            self.assertIsInstance(value, str)
+
+    def test_output_matches_current_time(self):
+        expected = FlyHourTimer.hour_timer(
+            int(datetime.now(dt_timezone.utc).timestamp())
+        )
+        actual = FlyHourTimer.hour_timer()
+        # allow the whole-second boundary to differ between the two reads
+        self.assertEqual(expected.split(".")[0], actual.split(".")[0])
+
+
+class TestHourTimerToTime(unittest.TestCase):
+    def test_returns_struct_time(self):
+        self.assertIsInstance(
+            FlyHourTimer.hour_timer_to_time("277777.4640"), time.struct_time
+        )
+
+    def test_full_round_trip(self):
+        # hour_timer -> hour_timer_to_time reconstructs the exact UTC struct
+        st = FlyHourTimer.hour_timer_to_time(FlyHourTimer.hour_timer(UNIX_911))
+        self.assertEqual(st, time.gmtime(UNIX_911))
+
+    def test_fields(self):
+        st = FlyHourTimer.hour_timer_to_time("277777.4640")
+        self.assertEqual(
+            (st.tm_year, st.tm_mon, st.tm_mday, st.tm_hour, st.tm_min, st.tm_sec),
+            (2001, 9, 9, 1, 46, 40),
+        )
+
+    def test_epoch(self):
+        self.assertEqual(FlyHourTimer.hour_timer_to_time("0.0000"), time.gmtime(0))
+
+    def test_encodes_date_not_today(self):
+        # the hour number carries the date, so it is NOT anchored to today
+        st = FlyHourTimer.hour_timer_to_time("277777.4640")
+        self.assertEqual(st.tm_year, 2001)
+
+    def test_invalid_format_raises(self):
+        for bad in ("", "12", "12.345", "12.34567", "ab.cd", None,
+                    "1.6060", "1.-1.23", "12.34 56"):
+            with self.assertRaises(ValueError):
+                FlyHourTimer.hour_timer_to_time(bad)
+
+
+class TestStaticAlias(unittest.TestCase):
+    def test_alias_is_class(self):
+        self.assertIs(fly_hour_timer, FlyHourTimer)
+
+    def test_alias_call(self):
+        self.assertEqual(fly_hour_timer.hour_timer(UNIX_911), "277777.4640")
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)