terrahour 1.0.0__tar.gz

terrahour-1.0.0/LICENSE

@@ -0,0 +1,30 @@
+MIT License
+
+Copyright (c) 2026 Alessio Coci
+
+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.
+
+----------------------------------------------------------------------
+
+The bundled data files under terrahour/data/ have their own licences:
+
+* cities.txt.gz is derived from GeoNames (https://www.geonames.org/),
+  licensed under Creative Commons Attribution 4.0 (CC BY 4.0).
+* land_mask.bin.gz is rasterised from Natural Earth (https://www.naturalearthdata.com/),
+  which is in the public domain.

terrahour-1.0.0/PKG-INFO

@@ -0,0 +1,213 @@
+Metadata-Version: 2.4
+Name: terrahour
+Version: 1.0.0
+Summary: World clock, world map and 24-hour meeting planner for the terminal
+Author: Alessio Coci
+License: MIT
+Project-URL: Homepage, https://github.com/ACoci86/terrahour
+Project-URL: Issues, https://github.com/ACoci86/terrahour/issues
+Keywords: world clock,time zones,tui,terminal,timezone,meeting planner,tmux
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pillow; extra == "dev"
+Dynamic: license-file
+
+# terrahour
+
+![tests](https://github.com/ACoci86/terrahour/actions/workflows/tests.yml/badge.svg)
+
+A world clock for the terminal, with a map that shows where it is daytime and a 24-hour
+timeline that shows when your cities are at work.
+
+| Main view: the day and night map above a timeline per city |
+| --- |
+| ![terrahour main view](https://raw.githubusercontent.com/ACoci86/terrahour/main/docs/main.png) |
+
+| A quick tour: scrubbing time, exchanges, DST radar, ambient view |
+| --- |
+| ![demo](https://raw.githubusercontent.com/ACoci86/terrahour/main/docs/demo.gif) |
+
+## What it does
+
+* **Map with day and night.** The world is drawn in braille dots, shaded by sunlight, and
+  coloured by time zone. Every city you track gets a marker. Zoom with `+` `-` or the mouse
+  wheel, drag to pan.
+* **A timeline per city.** Each row is a 24-hour bar with the working hours lit up. The
+  overlap row at the bottom shows the window when everybody is at their desk.
+* **Scrub through time.** Arrow keys move in 15-minute steps, `g` jumps to any time
+  ("15:30", "3pm", "+2h", "2026-10-05 09:00"), `r` snaps back to live.
+* **DST radar.** `D` lists the next clock change for every city and, more usefully, whether
+  the gap between you and them is about to shift by an hour.
+* **Stock exchanges.** `M` swaps the city list for the ten biggest exchanges with their real
+  trading sessions, lunch breaks included.
+* **Alerts.** `A` sets a daily reminder in another city's time, a ping when an office or
+  exchange opens or closes, or a plain timer. They ring the bell and send a desktop
+  notification while the app is open.
+* **Weather**, if you want it. `W` shows the current temperature next to each city
+  (Open-Meteo, needs network, off by default).
+* **Ambient view.** `V` turns the whole terminal into a big clock over the map that cycles
+  through your cities. Nice on a spare monitor.
+* **Fits anywhere.** Below about 76 columns it switches to a compact layout that works in a
+  tmux split. `--line` prints a one-liner for a status bar.
+* **Six themes** (midnight, nord, dracula, light, mono, colorblind), 12 or 24 hour clock,
+  mouse support, and about 6,000 cities built in with online lookup for the rest.
+
+| Exchanges | Compact layout for a tmux split |
+| --- | --- |
+| ![markets view](https://raw.githubusercontent.com/ACoci86/terrahour/main/docs/markets.png) | ![compact view](https://raw.githubusercontent.com/ACoci86/terrahour/main/docs/compact.png) |
+
+| DST radar | Adding a city |
+| --- | --- |
+| ![DST radar](https://raw.githubusercontent.com/ACoci86/terrahour/main/docs/radar.png) | ![add city](https://raw.githubusercontent.com/ACoci86/terrahour/main/docs/add-city.png) |
+
+| Ambient view | Light theme |
+| --- | --- |
+| ![ambient view](https://raw.githubusercontent.com/ACoci86/terrahour/main/docs/ambient.png) | ![light theme](https://raw.githubusercontent.com/ACoci86/terrahour/main/docs/theme-light.png) |
+
+## Install
+
+You need Python 3.9 or newer, a terminal with truecolor support (almost all of them these
+days) and a UTF-8 locale. Developed on Linux. macOS is covered by the automated tests, but I
+have not tried it by hand. On Windows use WSL, the app relies on a Unix terminal.
+
+```sh
+pipx install git+https://github.com/ACoci86/terrahour
+```
+
+Then run `terrahour`. If your shell cannot find the command, run `pipx ensurepath` once and
+open a new terminal.
+
+or, without pipx, in a virtual environment (recent Debian and Ubuntu refuse a plain
+`pip install` outside one):
+
+```sh
+python3 -m venv .venv && . .venv/bin/activate
+pip install git+https://github.com/ACoci86/terrahour
+terrahour
+```
+
+The command is available whenever that environment is active.
+
+or just clone it and run it in place, there is nothing to build:
+
+```sh
+git clone https://github.com/ACoci86/terrahour
+cd terrahour
+python -m terrahour
+```
+
+## Usage
+
+```sh
+terrahour                                  # your saved cities (a sensible default set the first time)
+terrahour Europe/Berlin "Home=America/Chicago" Naples   # a one-off set of zones or city names, not saved
+terrahour --markets                        # start in the exchange view
+terrahour --at 2026-10-05T09:00Z           # start frozen at a given time
+terrahour --theme nord --12h
+terrahour --ambient                        # straight into the screensaver view
+terrahour --reset                          # forget saved cities and settings
+```
+
+Press `?` inside the app for the full list of keys. The ones you will use most:
+
+| Key | Action |
+| --- | --- |
+| `←` `→` | scrub 15 minutes (Shift: 1 hour, PgUp/PgDn: 1 day) |
+| `g` | go to a time, `r` back to live |
+| `↑` `↓` `j` `k` | select a city, Shift moves it up or down the list |
+| `a` `d` | add or remove a city |
+| `*` | mark the selected city as home (offsets are then relative to it) |
+| `Enter` | focus the selected city, dims the others |
+| `M` `D` `A` `W` | exchanges, DST radar, alerts, weather |
+| `+` `-` `[` `]` `0` | zoom the map, zoom the timeline, reset |
+| `T` `t` `c` `V` | theme, 12/24h, compact layout, ambient view |
+| `q` | quit |
+
+Everything you change in the app (cities, theme, home, working hours, alerts) is saved to
+`~/.config/terrahour/config.json`. Zones given on the command line are session-only and
+leave that file alone.
+
+## Status bars and scripts
+
+```sh
+$ terrahour --line
+SF 07:30 · NY 10:30 · LON 14:30 · UTC 14:30 · DUB 18:30 · MUM 20:00 · SIN 22:30 · TOK 23:30 · SYD 01:30+1
+
+$ terrahour --watch            # the same line, updating in place (good in a small tmux pane)
+$ terrahour --tmux             # with tmux colour codes, for your status-right
+$ terrahour --json --at 2026-03-18T14:30Z | jq '.cities[] | select(.open)'
+```
+
+The JSON includes local time, UTC offset, whether the city is inside working hours, minutes
+until that changes, and the next clock change. `--once --size 120x40` prints a single frame of
+the full UI, which is how the screenshots above were made.
+
+## Network
+
+Two features talk to the internet, and both are optional:
+
+* While you type in the "add city" box, names that are not in the built-in list are looked up
+  through the Open-Meteo geocoding API.
+* Weather, when you turn it on with `W`, comes from the Open-Meteo forecast API.
+
+Set `TERRAHOUR_OFFLINE=1` to switch both off. Nothing else leaves your machine.
+
+## How it is put together
+
+It is a single Python package with no third-party dependencies. The pieces:
+
+| Module | What it does |
+| --- | --- |
+| `cli.py` | argument parsing and the non-interactive modes |
+| `app.py` | the terminal loop: raw mode, input tokens, redraw only the lines that changed |
+| `keys.py` | every key and mouse event ends up here |
+| `compose.py`, `draw.py`, `overlays.py`, `ambient.py` | turn the state into a frame |
+| `canvas.py` | a character grid with colours that renders to ANSI escapes |
+| `clock.py` | offsets, formatting, open/closed status, DST transitions, overlap |
+| `astro.py` | sun position, sunrise and sunset |
+| `worldmap.py` | the land mask, braille rasterisation, zoom and pan |
+| `places.py`, `geocode.py` | the city database, search, and the online lookup |
+| `state.py` | the State object and the config file |
+| `alerts.py`, `weather.py` | what the names say |
+| `themes.py` | colours; every module reads them through the active theme object `C` |
+| `data/` | the city list, the land mask and the exchange list, with [their own README](https://github.com/ACoci86/terrahour/blob/main/terrahour/data/README.md) |
+
+The map is a 0.25 degree land mask folded into a summed-area table, so any zoom level can ask
+"how much of this box is land?" in constant time, and the braille cells come straight out of
+that. Sun position uses the usual NOAA approximation, good to a few minutes.
+
+## Development
+
+```sh
+python -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+The tests do not need a terminal or the network: they compose frames in memory and drive the
+app through the same key handler the terminal loop uses. `tools/screenshots.py` regenerates
+everything in `docs/` (it needs Pillow and the DejaVu fonts).
+
+## Data and credits
+
+* City list derived from [GeoNames](https://www.geonames.org/) (CC BY 4.0).
+* Land mask rasterised from [Natural Earth](https://www.naturalearthdata.com/) (public domain).
+* Geocoding and weather from [Open-Meteo](https://open-meteo.com/) (CC BY 4.0).
+* Time zone rules come from your operating system's tz database through Python's `zoneinfo`.
+
+## License
+
+MIT. See [LICENSE](https://github.com/ACoci86/terrahour/blob/main/LICENSE).

terrahour-1.0.0/README.md

@@ -0,0 +1,186 @@
+# terrahour
+
+![tests](https://github.com/ACoci86/terrahour/actions/workflows/tests.yml/badge.svg)
+
+A world clock for the terminal, with a map that shows where it is daytime and a 24-hour
+timeline that shows when your cities are at work.
+
+| Main view: the day and night map above a timeline per city |
+| --- |
+| ![terrahour main view](https://raw.githubusercontent.com/ACoci86/terrahour/main/docs/main.png) |
+
+| A quick tour: scrubbing time, exchanges, DST radar, ambient view |
+| --- |
+| ![demo](https://raw.githubusercontent.com/ACoci86/terrahour/main/docs/demo.gif) |
+
+## What it does
+
+* **Map with day and night.** The world is drawn in braille dots, shaded by sunlight, and
+  coloured by time zone. Every city you track gets a marker. Zoom with `+` `-` or the mouse
+  wheel, drag to pan.
+* **A timeline per city.** Each row is a 24-hour bar with the working hours lit up. The
+  overlap row at the bottom shows the window when everybody is at their desk.
+* **Scrub through time.** Arrow keys move in 15-minute steps, `g` jumps to any time
+  ("15:30", "3pm", "+2h", "2026-10-05 09:00"), `r` snaps back to live.
+* **DST radar.** `D` lists the next clock change for every city and, more usefully, whether
+  the gap between you and them is about to shift by an hour.
+* **Stock exchanges.** `M` swaps the city list for the ten biggest exchanges with their real
+  trading sessions, lunch breaks included.
+* **Alerts.** `A` sets a daily reminder in another city's time, a ping when an office or
+  exchange opens or closes, or a plain timer. They ring the bell and send a desktop
+  notification while the app is open.
+* **Weather**, if you want it. `W` shows the current temperature next to each city
+  (Open-Meteo, needs network, off by default).
+* **Ambient view.** `V` turns the whole terminal into a big clock over the map that cycles
+  through your cities. Nice on a spare monitor.
+* **Fits anywhere.** Below about 76 columns it switches to a compact layout that works in a
+  tmux split. `--line` prints a one-liner for a status bar.
+* **Six themes** (midnight, nord, dracula, light, mono, colorblind), 12 or 24 hour clock,
+  mouse support, and about 6,000 cities built in with online lookup for the rest.
+
+| Exchanges | Compact layout for a tmux split |
+| --- | --- |
+| ![markets view](https://raw.githubusercontent.com/ACoci86/terrahour/main/docs/markets.png) | ![compact view](https://raw.githubusercontent.com/ACoci86/terrahour/main/docs/compact.png) |
+
+| DST radar | Adding a city |
+| --- | --- |
+| ![DST radar](https://raw.githubusercontent.com/ACoci86/terrahour/main/docs/radar.png) | ![add city](https://raw.githubusercontent.com/ACoci86/terrahour/main/docs/add-city.png) |
+
+| Ambient view | Light theme |
+| --- | --- |
+| ![ambient view](https://raw.githubusercontent.com/ACoci86/terrahour/main/docs/ambient.png) | ![light theme](https://raw.githubusercontent.com/ACoci86/terrahour/main/docs/theme-light.png) |
+
+## Install
+
+You need Python 3.9 or newer, a terminal with truecolor support (almost all of them these
+days) and a UTF-8 locale. Developed on Linux. macOS is covered by the automated tests, but I
+have not tried it by hand. On Windows use WSL, the app relies on a Unix terminal.
+
+```sh
+pipx install git+https://github.com/ACoci86/terrahour
+```
+
+Then run `terrahour`. If your shell cannot find the command, run `pipx ensurepath` once and
+open a new terminal.
+
+or, without pipx, in a virtual environment (recent Debian and Ubuntu refuse a plain
+`pip install` outside one):
+
+```sh
+python3 -m venv .venv && . .venv/bin/activate
+pip install git+https://github.com/ACoci86/terrahour
+terrahour
+```
+
+The command is available whenever that environment is active.
+
+or just clone it and run it in place, there is nothing to build:
+
+```sh
+git clone https://github.com/ACoci86/terrahour
+cd terrahour
+python -m terrahour
+```
+
+## Usage
+
+```sh
+terrahour                                  # your saved cities (a sensible default set the first time)
+terrahour Europe/Berlin "Home=America/Chicago" Naples   # a one-off set of zones or city names, not saved
+terrahour --markets                        # start in the exchange view
+terrahour --at 2026-10-05T09:00Z           # start frozen at a given time
+terrahour --theme nord --12h
+terrahour --ambient                        # straight into the screensaver view
+terrahour --reset                          # forget saved cities and settings
+```
+
+Press `?` inside the app for the full list of keys. The ones you will use most:
+
+| Key | Action |
+| --- | --- |
+| `←` `→` | scrub 15 minutes (Shift: 1 hour, PgUp/PgDn: 1 day) |
+| `g` | go to a time, `r` back to live |
+| `↑` `↓` `j` `k` | select a city, Shift moves it up or down the list |
+| `a` `d` | add or remove a city |
+| `*` | mark the selected city as home (offsets are then relative to it) |
+| `Enter` | focus the selected city, dims the others |
+| `M` `D` `A` `W` | exchanges, DST radar, alerts, weather |
+| `+` `-` `[` `]` `0` | zoom the map, zoom the timeline, reset |
+| `T` `t` `c` `V` | theme, 12/24h, compact layout, ambient view |
+| `q` | quit |
+
+Everything you change in the app (cities, theme, home, working hours, alerts) is saved to
+`~/.config/terrahour/config.json`. Zones given on the command line are session-only and
+leave that file alone.
+
+## Status bars and scripts
+
+```sh
+$ terrahour --line
+SF 07:30 · NY 10:30 · LON 14:30 · UTC 14:30 · DUB 18:30 · MUM 20:00 · SIN 22:30 · TOK 23:30 · SYD 01:30+1
+
+$ terrahour --watch            # the same line, updating in place (good in a small tmux pane)
+$ terrahour --tmux             # with tmux colour codes, for your status-right
+$ terrahour --json --at 2026-03-18T14:30Z | jq '.cities[] | select(.open)'
+```
+
+The JSON includes local time, UTC offset, whether the city is inside working hours, minutes
+until that changes, and the next clock change. `--once --size 120x40` prints a single frame of
+the full UI, which is how the screenshots above were made.
+
+## Network
+
+Two features talk to the internet, and both are optional:
+
+* While you type in the "add city" box, names that are not in the built-in list are looked up
+  through the Open-Meteo geocoding API.
+* Weather, when you turn it on with `W`, comes from the Open-Meteo forecast API.
+
+Set `TERRAHOUR_OFFLINE=1` to switch both off. Nothing else leaves your machine.
+
+## How it is put together
+
+It is a single Python package with no third-party dependencies. The pieces:
+
+| Module | What it does |
+| --- | --- |
+| `cli.py` | argument parsing and the non-interactive modes |
+| `app.py` | the terminal loop: raw mode, input tokens, redraw only the lines that changed |
+| `keys.py` | every key and mouse event ends up here |
+| `compose.py`, `draw.py`, `overlays.py`, `ambient.py` | turn the state into a frame |
+| `canvas.py` | a character grid with colours that renders to ANSI escapes |
+| `clock.py` | offsets, formatting, open/closed status, DST transitions, overlap |
+| `astro.py` | sun position, sunrise and sunset |
+| `worldmap.py` | the land mask, braille rasterisation, zoom and pan |
+| `places.py`, `geocode.py` | the city database, search, and the online lookup |
+| `state.py` | the State object and the config file |
+| `alerts.py`, `weather.py` | what the names say |
+| `themes.py` | colours; every module reads them through the active theme object `C` |
+| `data/` | the city list, the land mask and the exchange list, with [their own README](https://github.com/ACoci86/terrahour/blob/main/terrahour/data/README.md) |
+
+The map is a 0.25 degree land mask folded into a summed-area table, so any zoom level can ask
+"how much of this box is land?" in constant time, and the braille cells come straight out of
+that. Sun position uses the usual NOAA approximation, good to a few minutes.
+
+## Development
+
+```sh
+python -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+The tests do not need a terminal or the network: they compose frames in memory and drive the
+app through the same key handler the terminal loop uses. `tools/screenshots.py` regenerates
+everything in `docs/` (it needs Pillow and the DejaVu fonts).
+
+## Data and credits
+
+* City list derived from [GeoNames](https://www.geonames.org/) (CC BY 4.0).
+* Land mask rasterised from [Natural Earth](https://www.naturalearthdata.com/) (public domain).
+* Geocoding and weather from [Open-Meteo](https://open-meteo.com/) (CC BY 4.0).
+* Time zone rules come from your operating system's tz database through Python's `zoneinfo`.
+
+## License
+
+MIT. See [LICENSE](https://github.com/ACoci86/terrahour/blob/main/LICENSE).

terrahour-1.0.0/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["setuptools>=64"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "terrahour"
+dynamic = ["version"]
+description = "World clock, world map and 24-hour meeting planner for the terminal"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Alessio Coci" }]
+keywords = ["world clock", "time zones", "tui", "terminal", "timezone", "meeting planner", "tmux"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Intended Audience :: End Users/Desktop",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: MacOS",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Utilities",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest", "pillow"]
+
+[project.scripts]
+terrahour = "terrahour.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/ACoci86/terrahour"
+Issues = "https://github.com/ACoci86/terrahour/issues"
+
+[tool.setuptools]
+packages = ["terrahour"]
+
+[tool.setuptools.dynamic]
+version = { attr = "terrahour.__version__" }
+
+[tool.setuptools.package-data]
+terrahour = ["data/*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]
+addopts = "-q"

terrahour-1.0.0/setup.cfg

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

terrahour-1.0.0/terrahour/__init__.py

@@ -0,0 +1,6 @@
+"""terrahour: world clock, map and 24-hour planner for the terminal.
+
+Pure standard library (Python 3.9+). Needs a truecolor terminal and a UTF-8 locale.
+"""
+
+__version__ = "1.0.0"

terrahour-1.0.0/terrahour/__main__.py

@@ -0,0 +1,4 @@
+"""Allow ``python -m terrahour``."""
+from .cli import main
+
+main()

terrahour-1.0.0/terrahour/alerts.py

@@ -0,0 +1,110 @@
+"""Alerts: parse what the user typed, check them every second, and notify the desktop."""
+import re
+import shutil
+import subprocess
+import sys
+import time
+from zoneinfo import ZoneInfo
+
+from .clock import fmt_clock, is_open
+from .places import City, markets, search_db
+
+
+def resolve_place(st, name):
+    """Find a city/exchange by name: current rows, exchanges, then the database. -> (name, zone, market) or None."""
+    q = name.strip().lower()
+    if not q:
+        c = st.rows()[st.cursor()]
+        return c.name, c.zone, c.sessions is not None
+    for c in st.cities:
+        if q in c.name.lower():
+            return c.name, c.zone, False
+    for c in markets():
+        if q in c.name.lower():
+            return c.name, c.zone, True
+    res = search_db(name, 1)
+    if res:
+        return res[0]["name"], res[0]["zone"], False
+    return None
+
+
+def parse_alert(text, st):
+    """-> (alert dict | None, error)."""
+    s = text.strip()
+    low = s.lower()
+    m = re.fullmatch(r"in\s+(?:(\d+)\s*h)?\s*(?:(\d+)\s*m?)?", low)
+    if m and (m.group(1) or m.group(2)):
+        secs = int(m.group(1) or 0) * 3600 + int(m.group(2) or 0) * 60
+        if secs <= 0:
+            return None, "Timer must be longer than zero."
+        return {"kind": "timer", "name": "timer", "at": time.time() + secs}, ""
+    m = re.fullmatch(r"(open|close)\s+(.+)", low)
+    if m:
+        p = resolve_place(st, m.group(2))
+        if not p:
+            return None, "Couldn't find %r." % m.group(2)
+        return {"kind": m.group(1), "name": p[0], "zone": p[1], "market": p[2]}, ""
+    m = re.fullmatch(r"(\d{1,2})(?::(\d{2}))?\s*(am|pm)?\s*(.*)", low)
+    if m:
+        hh, mm = int(m.group(1)), int(m.group(2) or 0)
+        if m.group(3):
+            if not 1 <= hh <= 12:
+                return None, "Hour must be 1-12 with am/pm."
+            hh = hh % 12 + (12 if m.group(3) == "pm" else 0)
+        if hh > 23 or mm > 59:
+            return None, "That isn't a valid time."
+        p = resolve_place(st, m.group(4))
+        if not p:
+            return None, "Couldn't find %r." % m.group(4)
+        return {"kind": "time", "name": p[0], "zone": p[1], "m": hh * 60 + mm}, ""
+    return None, "Try: 9am tokyo, open new york, close NYSE, in 25m"
+
+
+def alert_city(a):
+    if a.get("market"):
+        for c in markets():
+            if c.name == a["name"]:
+                return c
+    return City(a["name"], a["zone"], 0, 0, 0)
+
+
+def notify(text):
+    try:
+        if sys.platform == "darwin" and shutil.which("osascript"):
+            subprocess.Popen(["osascript", "-e", 'display notification "%s" with title "terrahour"' % text.replace('"', "'")],
+                             stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+        elif shutil.which("notify-send"):
+            subprocess.Popen(["notify-send", "terrahour", text], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+    except Exception:
+        pass
+
+
+def check_alerts(st, live):
+    """Returns messages for alerts that fired now. Uses real time, not scrubbed time."""
+    fired, keep = [], []
+    for a in st.alerts:
+        try:
+            if a["kind"] == "timer":
+                if time.time() >= a["at"]:
+                    fired.append("Timer finished")
+                    continue
+            elif a["kind"] == "time":
+                loc = live.astimezone(ZoneInfo(a["zone"]))
+                today = loc.date().isoformat()
+                if loc.hour * 60 + loc.minute == a["m"] and a.get("_last") != today:
+                    a["_last"] = today
+                    fired.append("%s in %s" % (fmt_clock(loc, st.h12), a["name"]))
+            else:
+                c = alert_city(a)
+                now_open = is_open(c, live.astimezone(c.tz), st.work)
+                prev = a.get("_state")
+                a["_state"] = now_open
+                if prev is not None and prev != now_open and now_open == (a["kind"] == "open"):
+                    fired.append("%s %s" % (a["name"], "is open" if now_open else "has closed"))
+        except Exception:
+            pass
+        keep.append(a)
+    if len(keep) != len(st.alerts):
+        st.alerts = keep
+        st.aidx = min(st.aidx, max(0, len(keep) - 1))
+    return fired