tzclock-cli 0.1.0__py3-none-any.whl

tzclock/__init__.py

@@ -0,0 +1,3 @@
+"""A live timezone clock for the terminal."""
+
+__version__ = "0.1.0"

tzclock/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    main()

tzclock/cli.py

@@ -0,0 +1,173 @@
+#!/usr/bin/env python3
+"""Live system-clock timezone converter. Python 3.9+; macOS/Linux terminal.
+
+Run: tzclock
+     tzclock --zone Asia/Seoul --once
+
+Arrows select a menu item; Enter applies it. / searches all IANA zones.
+Esc leaves search, F returns to favorites, Q quits outside search.
+Uses the machine's clock and installed timezone database; no network access.
+"""
+
+import argparse
+from . import __version__
+from datetime import datetime, timezone
+import sys
+from zoneinfo import ZoneInfo, ZoneInfoNotFoundError, available_timezones
+
+FAVORITES = [
+    "Europe/Warsaw", "Asia/Seoul", "Asia/Taipei", "Asia/Hong_Kong",
+    "Asia/Tokyo", "UTC", "Europe/London", "America/New_York",
+    "America/Los_Angeles", "Australia/Sydney",
+]
+
+
+def clock_lines(zone, now=None):
+    """Convert one aware instant, so all displayed clocks agree."""
+    now = now if now is not None else datetime.now(timezone.utc)
+    if now.tzinfo is None or now.utcoffset() is None:
+        raise ValueError("The source time must be timezone-aware")
+    local = now.astimezone()
+    target = now.astimezone(zone)
+    offset = target.strftime("%z")
+    offset = offset[:3] + ":" + offset[3:]
+    days = (target.date() - local.date()).days
+    day_note = "same date as local" if days == 0 else f"{days:+d} day(s) from local"
+    return [
+        f"System local: {local:%Y-%m-%d  %H:%M:%S %Z}",
+        f"Selected:     {zone.key}",
+        f"              {target:%A, %Y-%m-%d}",
+        f"              {target:%H:%M:%S}  {target.tzname()}  UTC{offset}",
+        f"              {day_note}",
+    ]
+
+
+def terminal_app(screen, initial_zone):
+    import curses
+
+    try:
+        curses.curs_set(0)
+    except curses.error:
+        pass
+    screen.keypad(True)
+    screen.timeout(200)
+    active = ZoneInfo(initial_zone)
+    favorites = list(dict.fromkeys([*FAVORITES, initial_zone]))
+    favorites = [name for name in favorites if zone_exists(name)]
+    all_zones = sorted(available_timezones() | set(favorites))
+    searching = False
+    query = ""
+    index = favorites.index(initial_zone)
+    status = ""
+
+    def put(y, text, style=0):
+        height, width = screen.getmaxyx()
+        if 0 <= y < height and width > 1:
+            try:
+                screen.addnstr(y, 0, text, width - 1, style)
+            except curses.error:
+                pass  # Resizing can race the screen update.
+
+    while True:
+        items = ([z for z in all_zones if query.casefold().replace(" ", "_")
+                  in z.casefold()] if searching else favorites)
+        index = min(max(0, index), max(0, len(items) - 1))
+        height, width = screen.getmaxyx()
+        screen.erase()
+        if height < 16 or width < 48:
+            put(0, "Please resize to at least 48 columns x 16 rows.")
+            put(1, "Esc or Q: quit")
+            screen.refresh()
+            key = screen.getch()
+            if key in (27, ord("q"), ord("Q")):
+                return
+            continue
+        put(0, "TIMEZONE CONVERTER | live system clock", curses.A_BOLD)
+        for row, line in enumerate(clock_lines(active), 2):
+            put(row, line, curses.A_BOLD if row == 5 else 0)
+        put(8, f"Search all timezones: {query}_" if searching else "Quick choices")
+        capacity = height - 13
+        start = max(0, min(index - capacity // 2, len(items) - capacity))
+        for row, name in enumerate(items[start:start + capacity], 9):
+            selected = row - 9 + start == index
+            marker = "*" if name == active.key else " "
+            put(row, f"{marker} {name}", curses.A_REVERSE if selected else 0)
+        if not items:
+            put(9, "No matches. Backspace to edit; Esc for favorites.")
+        put(height - 3, status or f"{len(items)} zones | * = displayed timezone")
+        put(height - 2, "Up/Down: choose   Enter: apply   Esc: favorites" if searching
+            else "Up/Down: choose   Enter: apply   /: search")
+        put(height - 1, "Type to filter (Q is a search character)." if searching
+            else "F: favorites   Q: quit   Refreshes automatically")
+        screen.refresh()
+        try:
+            key = screen.get_wch()
+        except curses.error:
+            continue
+        status = ""
+        if key == curses.KEY_UP:
+            index = max(0, index - 1)
+        elif key == curses.KEY_DOWN:
+            index = min(len(items) - 1, index + 1)
+        elif key == curses.KEY_NPAGE:
+            index = min(len(items) - 1, index + capacity)
+        elif key == curses.KEY_PPAGE:
+            index = max(0, index - capacity)
+        elif key in ("\n", "\r", curses.KEY_ENTER):
+            if items:
+                active = ZoneInfo(items[index])
+                status = f"Now displaying {active.key}"
+        elif key == "\x1b":
+            searching, query, index = False, "", 0
+        elif searching:
+            if key in (curses.KEY_BACKSPACE, "\x7f", "\b"):
+                query, index = query[:-1], 0
+            elif isinstance(key, str) and key.isprintable():
+                query, index = query + key, 0
+        elif key in ("q", "Q"):
+            return
+        elif key == "/":
+            searching, query, index = True, "", 0
+        elif key in ("f", "F"):
+            index = 0
+
+
+def zone_exists(name):
+    try:
+        ZoneInfo(name)
+        return True
+    except ZoneInfoNotFoundError:
+        return False
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__,
+                                     formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser.add_argument("--version", action="version", version=f"tzclock {__version__}")
+    parser.add_argument("--zone", default="Europe/Warsaw", help="Initial IANA timezone")
+    parser.add_argument("--once", action="store_true", help="Print once without a menu")
+    args = parser.parse_args()
+    try:
+        zone = ZoneInfo(args.zone)
+    except (ZoneInfoNotFoundError, ValueError):
+        parser.error(f"Timezone unavailable: {args.zone!r}. Use an IANA name such as "
+                     "Asia/Seoul. If timezone data is missing, install the tzdata package.")
+    if args.once or not (sys.stdin.isatty() and sys.stdout.isatty()):
+        print("\n".join(clock_lines(zone)))
+        return
+    try:
+        import curses
+    except ImportError:
+        parser.exit(1, "Interactive mode requires curses (included in most macOS/Linux "
+                    "Python builds; provided by windows-curses on Windows). Reinstall with pip "
+                    "to restore dependencies, or use --once for plain output.\n")
+    try:
+        curses.wrapper(terminal_app, args.zone)
+    except KeyboardInterrupt:
+        pass
+    except curses.error as exc:
+        parser.exit(1, f"Terminal could not initialize: {exc}. Try --once.\n")
+
+
+if __name__ == "__main__":
+    main()

tzclock_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: tzclock-cli
+Version: 0.1.0
+Summary: A small live timezone clock with a searchable terminal menu
+License-Expression: MIT
+Keywords: timezone,clock,terminal,curses,cli
+Classifier: Programming Language :: Python :: 3
+Classifier: Environment :: Console :: Curses
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: tzdata
+Requires-Dist: windows-curses>=2.4; sys_platform == "win32"
+Dynamic: license-file
+
+# tzclock
+
+A small live timezone converter for the terminal. Reads your system clock and
+shows local time alongside a selected timezone, including the date, UTC offset,
+and date difference. No network requests during use.
+
+## Install
+
+Requires Python 3.9 or newer. Once published to PyPI:
+
+```sh
+python -m pip install tzclock-cli
+tzclock
+```
+
+Use `python3` on macOS/Linux or `py` on Windows if that is your Python launcher.
+For an isolated command-line installation, `pipx install tzclock-cli` also works
+if you already use pipx. In a conda environment, activate it and use the same pip
+command; a separate conda package is not required.
+
+Before publication, install a supplied wheel:
+
+```sh
+python -m pip install ./dist/tzclock_cli-0.1.0-py3-none-any.whl
+```
+
+Pip creates the `tzclock` launcher, including an executable launcher on Windows.
+If your Python scripts directory is not on PATH, use `python -m tzclock` instead.
+No copying into system directories or manually setting executable permissions.
+
+## Use
+
+```sh
+tzclock
+tzclock --zone Asia/Seoul
+tzclock --zone Asia/Seoul --once
+tzclock --version
+python -m tzclock --zone Europe/Warsaw --once
+```
+
+| Key | Action |
+| --- | --- |
+| Up / Down | Choose a timezone |
+| Enter | Apply the highlighted timezone |
+| / | Search all installed IANA timezones |
+| Page Up / Page Down | Scroll a page |
+| Backspace | Edit search |
+| Esc | Leave search and return to favorites |
+| Q | Quit outside search |
+
+During search, Q is a normal letter; press Esc then Q to quit. Ctrl+C also exits.
+Quick choices include Warsaw, Seoul, Taipei, Hong Kong, Tokyo and UTC.
+The menu needs at least 48 columns by 16 rows. Resize the terminal if prompted.
+Redirected output automatically uses the one-shot text mode.
+
+## Platform handling
+
+Dependencies are declared in `pyproject.toml`, not installed by application code:
+
+```toml
+dependencies = [
+  "tzdata",
+  "windows-curses>=2.4; sys_platform == 'win32'",
+]
+```
+
+Pip installs `windows-curses` only on Windows. macOS and Linux use their Python
+build's standard curses module. The small `tzdata` package is installed on all
+platforms as a fallback when no system timezone database is available. Python's
+zoneinfo normally uses system timezone data first. DST rules come from that
+database; keep your system and dependencies updated.
+
+Interactive Windows support depends on a windows-curses wheel being available
+for your Python version and architecture. Conventional CPython installations
+are the intended target; not every Python implementation or platform is promised.
+On minimal Unix Python builds without curses, use `--once` or a Python build
+with curses support. No administrator privileges are needed inside a virtual
+environment.
+
+If you previously copied a standalone `tzclock` into `/usr/local/bin`, that old
+file may take precedence. Check `command -v tzclock` (Windows: `where tzclock`).
+Use `python -m tzclock --version` to verify the installed package directly.
+
+## Development
+
+```sh
+python -m pip install -e .
+python -m unittest discover -s tests -v
+```
+
+See PUBLISH.md for the short release procedure. MIT licensed.

tzclock_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+tzclock/__init__.py,sha256=ESEuEuO5-qaTrbWNWl-VMfw0E9lQZwql6Md7Derm5io,69
+tzclock/__main__.py,sha256=MSmt_5Xg84uHqzTN38JwgseJK8rsJn_11A8WD99VtEo,61
+tzclock/cli.py,sha256=CZp6t0MNukZZedGgAmk0AOEGW9TMdUtojTJOKQsbGAo,6777
+tzclock_cli-0.1.0.dist-info/licenses/LICENSE,sha256=DR40GeDLCrY9aLFhHPqqE5QWkdQ98lueYJ7iAGuAHl8,1077
+tzclock_cli-0.1.0.dist-info/METADATA,sha256=NE4nymGkUdxygzz3W3HN9fjuSr8qYdjqupGrWK27sUw,3835
+tzclock_cli-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+tzclock_cli-0.1.0.dist-info/entry_points.txt,sha256=L8mkYmv0Tksw7LR1isDVtTfD550n_o0ugPQJU3ziA0A,45
+tzclock_cli-0.1.0.dist-info/top_level.txt,sha256=5qSPqxgTgpuseNg-ufBk_WSMrJbJjMRAt3MtODxWlPc,8
+tzclock_cli-0.1.0.dist-info/RECORD,,

tzclock_cli-0.1.0.dist-info/WHEEL

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

tzclock_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+tzclock = tzclock.cli:main

tzclock_cli-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tzclock contributors
+
+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.

tzclock_cli-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+tzclock