fly-hour-timer 1.1.2__py3-none-any.whl

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/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.2.dist-info/METADATA

@@ -0,0 +1,147 @@
+Metadata-Version: 2.4
+Name: fly_hour_timer
+Version: 1.1.2
+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/<your-name>/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.2.dist-info/RECORD

@@ -0,0 +1,6 @@
+fly_hour_timer/__init__.py,sha256=rWgT2xQFUWC4kQJFGlz5tK8Y4hlhFkwrur8DlDbyJS4,352
+fly_hour_timer/fly_hour_timer.py,sha256=XIOMrmSSDGEq4m2MKbr1S1jE31Z_n4__IhsQmpV-mj0,5779
+fly_hour_timer-1.1.2.dist-info/METADATA,sha256=_h5zQ8ssbdnBnH6dua0twqbwd24F6QlafSd_Ll1O6gM,4836
+fly_hour_timer-1.1.2.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+fly_hour_timer-1.1.2.dist-info/top_level.txt,sha256=mQA8VEQL6M4lIrgxX3pVW4C98ORt9LiKedvGwKNAzuY,15
+fly_hour_timer-1.1.2.dist-info/RECORD,,

fly_hour_timer-1.1.2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

fly_hour_timer-1.1.2.dist-info/top_level.txt

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