Metadata-Version: 2.4
Name: fly_hour_timer
Version: 1.1.5
Summary: A timezone-free Python time library: represents time as <hour>.<min_sec>
Author: fly
License: MIT
Project-URL: Homepage, https://github.com/fly-ttrr/fly_hour_timer
Project-URL: Repository, https://github.com/fly-ttrr/fly_hour_timer
Project-URL: Issues, https://github.com/fly-ttrr/fly_hour_timer/issues
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** | [简体中文](https://github.com/fly-ttrr/fly_hour_timer/blob/main/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
