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.
