Claude Code transcript - page 2/4

# Secrets — never commit
.env

# Local data cache
*.sqlite
*.sqlite-journal
fringe.db

# Python
__pycache__/
*.pyc
.venv/
venv/

#!/usr/bin/env python3
"""fringe — fetch Edinburgh Festival Fringe event data locally and query it
by day, performance start time, and distance from the city centre.

Zero dependencies: uses only the Python standard library.

Usage:
    python3 fringe.py fetch                 # download/refresh the local cache
    python3 fringe.py search --day 2026-08-15 --before 20:00 --max-distance 3km
    python3 fringe.py info                  # show what's in the cache

Credentials are read from a .env file (or the environment):
    FRINGE_API_KEY=...
    FRINGE_API_SECRET=...
"""

import argparse
import hashlib
import hmac
import json
import math
import os
import sqlite3
import sys
import urllib.parse
import urllib.request
from datetime import datetime

API_DOMAIN = "https://api.edinburghfestivalcity.com"
DEFAULT_YEAR = 2026
DEFAULT_FESTIVAL = "fringe"
PAGE_SIZE = 100  # API maximum

# Rough centre of the Old Town / Royal Mile — a sensible "middle of town".
DEFAULT_CENTRE = (55.9497, -3.1875)

HERE = os.path.dirname(os.path.abspath(__file__))
DB_PATH = os.path.join(HERE, "fringe.db")
ENV_PATH = os.path.join(HERE, ".env")


# --------------------------------------------------------------------------- #
# Config / credentials
# --------------------------------------------------------------------------- #
def load_env(path=ENV_PATH):
    """Load KEY=VALUE lines from a .env file into os.environ (without
    clobbering vars already set in the real environment)."""
    if not os.path.exists(path):
        return
    with open(path, encoding="utf-8") as fh:
        for line in fh:
            line = line.strip()
            if not line or line.startswith("#") or "=" not in line:
                continue
            key, _, value = line.partition("=")
            key, value = key.strip(), value.strip().strip('"').strip("'")
            os.environ.setdefault(key, value)


def get_credentials():
    load_env()
    key = os.environ.get("FRINGE_API_KEY", "").strip()
    secret = os.environ.get("FRINGE_API_SECRET", "").strip()
    if not key or not secret:
        sys.exit(
            "error: FRINGE_API_KEY and FRINGE_API_SECRET must be set "
            f"(in the environment or in {ENV_PATH})."
        )
    return key, secret


# --------------------------------------------------------------------------- #
# Signed API requests
# --------------------------------------------------------------------------- #
def signed_url(path, params, key, secret):
    """Build a signed request URL.

    The API signs the full path + query string (including the key, excluding
    the domain) with HMAC-SHA1 keyed by the secret, then the hex signature is
    appended as &signature=...  The signed string must exactly match what is
    sent, so we build the query string once and reuse it verbatim.
    """
    items = list(params.items()) + [("key", key)]
    query = urllib.parse.urlencode(items, quote_via=urllib.parse.quote)
    signed_path = f"{path}?{query}"
    signature = hmac.new(
        secret.encode("utf-8"), signed_path.encode("utf-8"), hashlib.sha1
    ).hexdigest()
    return f"{API_DOMAIN}{signed_path}&signature={signature}"


def api_get(path, params, key, secret):
    url = signed_url(path, params, key, secret)
    req = urllib.request.Request(url, headers={"Accept": "application/json"})
    try:
        with urllib.request.urlopen(req, timeout=60) as resp:
            return json.loads(resp.read().decode("utf-8"))
    except urllib.error.HTTPError as exc:
        body = exc.read().decode("utf-8", "replace")[:500]
        sys.exit(f"error: HTTP {exc.code} from {path}: {body}")
    except urllib.error.URLError as exc:
        sys.exit(f"error: could not reach API: {exc.reason}")


def paged_get(path, params, key, secret):
    """Yield records across all pages of a listing endpoint."""
    offset = 0
    while True:
        page_params = dict(params, size=PAGE_SIZE, **{"from": offset})
        data = api_get(path, page_params, key, secret)
        # The listing endpoints return a JSON array; be tolerant of a dict
        # wrapper just in case.
        if isinstance(data, dict):
            records = data.get("events") or data.get("venues") or data.get("results") or []
        else:
            records = data
        if not records:
            break
        for rec in records:
            yield rec
        if len(records) < PAGE_SIZE:
            break
        offset += PAGE_SIZE


# --------------------------------------------------------------------------- #
# Database
# --------------------------------------------------------------------------- #
SCHEMA = """
CREATE TABLE IF NOT EXISTS events (
    id            TEXT PRIMARY KEY,
    title         TEXT,
    sub_title     TEXT,
    artist        TEXT,
    genre         TEXT,
    genre_tags    TEXT,
    country       TEXT,
    age_category  TEXT,
    status        TEXT,
    description   TEXT,
    url           TEXT,
    website       TEXT,
    venue_id      TEXT,
    venue_name    TEXT,
    latitude      REAL,
    longitude     REAL,
    updated       TEXT,
    raw           TEXT
);

CREATE TABLE IF NOT EXISTS performances (
    perf_id          TEXT PRIMARY KEY,
    event_id         TEXT,
    start            TEXT,
    end              TEXT,
    duration_minutes INTEGER,
    is_at_fixed_time INTEGER,
    price_string     TEXT,
    price            REAL,
    title            TEXT
);

CREATE TABLE IF NOT EXISTS venues (
    id        TEXT PRIMARY KEY,
    name      TEXT,
    address   TEXT,
    post_code TEXT,
    code      TEXT,
    latitude  REAL,
    longitude REAL,
    raw       TEXT
);

CREATE TABLE IF NOT EXISTS meta (key TEXT PRIMARY KEY, value TEXT);

CREATE INDEX IF NOT EXISTS idx_perf_event ON performances(event_id);
CREATE INDEX IF NOT EXISTS idx_perf_start ON performances(start);
"""


def connect():
    conn = sqlite3.connect(DB_PATH)
    conn.row_factory = sqlite3.Row
    conn.executescript(SCHEMA)
    return conn


def _to_float(value):
    try:
        return float(value)
    except (TypeError, ValueError):
        return None


def store_event(conn, ev):
    venue = ev.get("venue") or {}
    pos = venue.get("position") or {}
    lat = _to_float(ev.get("latitude")) or _to_float(pos.get("lat"))
    lon = _to_float(ev.get("longitude")) or _to_float(pos.get("lon"))
    conn.execute(
        """INSERT OR REPLACE INTO events
           (id, title, sub_title, artist, genre, genre_tags, country,
            age_category, status, description, url, website, venue_id,
            venue_name, latitude, longitude, updated, raw)
           VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)""",
        (
            ev.get("id"),
            ev.get("title"),
            ev.get("sub_title"),
            ev.get("artist"),
            ev.get("genre"),
            ", ".join(ev.get("genre_tags") or []) if isinstance(ev.get("genre_tags"), list) else ev.get("genre_tags"),
            ev.get("country"),
            ev.get("age_category"),
            ev.get("status"),
            ev.get("description_teaser") or ev.get("description"),
            ev.get("url"),
            ev.get("website"),
            venue.get("id"),
            venue.get("name"),
            lat,
            lon,
            ev.get("updated"),
            json.dumps(ev),
        ),
    )
    # Refresh this event's performances.
    conn.execute("DELETE FROM performances WHERE event_id = ?", (ev.get("id"),))
    for p in ev.get("performances") or []:
        conn.execute(
            """INSERT OR REPLACE INTO performances
               (perf_id, event_id, start, end, duration_minutes,
                is_at_fixed_time, price_string, price, title)
               VALUES (?,?,?,?,?,?,?,?,?)""",
            (
                p.get("id"),
                ev.get("id"),
                p.get("start"),
                p.get("end"),
                p.get("duration_minutes"),
                1 if p.get("is_at_fixed_time") else 0,
                p.get("price_string"),
                _to_float(p.get("price")),
                p.get("title"),
            ),
        )


def store_venue(conn, v):
    pos = v.get("position") or {}
    conn.execute(
        """INSERT OR REPLACE INTO venues
           (id, name, address, post_code, code, latitude, longitude, raw)
           VALUES (?,?,?,?,?,?,?,?)""",
        (
            v.get("id"),
            v.get("name"),
            v.get("address"),
            v.get("post_code"),
            v.get("code"),
            _to_float(pos.get("lat")),
            _to_float(pos.get("lon")),
            json.dumps(v),
        ),
    )


# --------------------------------------------------------------------------- #
# Commands
# --------------------------------------------------------------------------- #
def cmd_fetch(args):
    key, secret = get_credentials()
    conn = connect()
    base = {"festival": args.festival, "year": args.year}

    print(f"Fetching {args.festival} events for {args.year} …")
    n_events = 0
    for ev in paged_get("/events", base, key, secret):
        store_event(conn, ev)
        n_events += 1
        if n_events % 100 == 0:
            print(f"  {n_events} events …")
            conn.commit()
    conn.commit()

    print(f"Fetching {args.festival} venues for {args.year} …")
    n_venues = 0
    for v in paged_get("/venues", base, key, secret):
        store_venue(conn, v)
        n_venues += 1
    conn.commit()

    conn.execute(
        "INSERT OR REPLACE INTO meta (key, value) VALUES ('last_fetch', ?)",
        (datetime.now().isoformat(timespec="seconds"),),
    )
    conn.execute(
        "INSERT OR REPLACE INTO meta (key, value) VALUES ('festival', ?)",
        (args.festival,),
    )
    conn.execute(
        "INSERT OR REPLACE INTO meta (key, value) VALUES ('year', ?)",
        (str(args.year),),
    )
    conn.commit()
    print(f"Done. {n_events} events, {n_venues} venues cached in {DB_PATH}")
    _print_date_range(conn)
    conn.close()


def _parse_dt(value):
    """Parse an API datetime string tolerantly. Returns a datetime or None."""
    if not value:
        return None
    value = value.strip().replace("T", " ")
    # Drop timezone suffix / fractional seconds if present.
    value = value.split("+")[0].split(".")[0].strip()
    for fmt in ("%Y-%m-%d %H:%M:%S", "%Y-%m-%d %H:%M", "%Y-%m-%d"):
        try:
            return datetime.strptime(value, fmt)
        except ValueError:
            continue
    return None


def _print_date_range(conn):
    row = conn.execute(
        "SELECT MIN(start) AS lo, MAX(start) AS hi, COUNT(*) AS n "
        "FROM performances WHERE start IS NOT NULL AND start != ''"
    ).fetchone()
    if row and row["n"]:
        lo, hi = _parse_dt(row["lo"]), _parse_dt(row["hi"])
        lo_s = lo.date().isoformat() if lo else row["lo"]
        hi_s = hi.date().isoformat() if hi else row["hi"]
        print(f"Performances span {lo_s} → {hi_s} ({row['n']} showings).")


def haversine_km(a, b):
    lat1, lon1 = a
    lat2, lon2 = b
    r = 6371.0
    p1, p2 = math.radians(lat1), math.radians(lat2)
    dp = math.radians(lat2 - lat1)
    dl = math.radians(lon2 - lon1)
    h = math.sin(dp / 2) ** 2 + math.cos(p1) * math.cos(p2) * math.sin(dl / 2) ** 2
    return 2 * r * math.asin(math.sqrt(h))


def _parse_distance(text):
    """Parse '3km' / '2miles' / '1.5mi' / '3' (km) into kilometres."""
    text = text.strip().lower()
    num = ""
    for ch in text:
        if ch.isdigit() or ch == ".":
            num += ch
        else:
            break
    if not num:
        raise argparse.ArgumentTypeError(f"bad distance: {text!r}")
    val = float(num)
    unit = text[len(num):].strip()
    if unit.startswith("mi"):
        return val * 1.609344
    return val  # default km


def _parse_hm(text):
    """Parse 'HH:MM' into minutes-since-midnight."""
    try:
        h, m = text.split(":")
        return int(h) * 60 + int(m)
    except Exception:
        raise argparse.ArgumentTypeError(f"bad time (want HH:MM): {text!r}")


def cmd_search(args):
    conn = connect()
    centre = DEFAULT_CENTRE
    if args.centre:
        try:
            lat, lon = (float(x) for x in args.centre.split(","))
            centre = (lat, lon)
        except Exception:
            sys.exit("error: --centre must be 'lat,lon' e.g. 55.9497,-3.1875")

    max_km = _parse_distance(args.max_distance) if args.max_distance else None
    after = _parse_hm(args.after) if args.after else None
    before = _parse_hm(args.before) if args.before else None

    sql = [
        "SELECT p.start AS start, p.price_string AS price_string,",
        "       p.duration_minutes AS duration_minutes,",
        "       e.title AS title, e.artist AS artist, e.genre AS genre,",
        "       e.age_category AS age_category, e.status AS status,",
        "       e.venue_name AS venue_name, e.latitude AS lat, e.longitude AS lon,",
        "       e.url AS url",
        "FROM performances p JOIN events e ON e.id = p.event_id",
        "WHERE 1=1",
    ]
    params = []
    # Exclude cancelled/deleted by default.
    sql.append("AND (e.status IS NULL OR e.status NOT IN ('cancelled','deleted'))")

    if args.day:
        sql.append("AND substr(p.start,1,10) = ?")
        params.append(args.day)
    if args.date_from:
        sql.append("AND substr(p.start,1,10) >= ?")
        params.append(args.date_from)
    if args.date_to:
        sql.append("AND substr(p.start,1,10) <= ?")
        params.append(args.date_to)
    if args.genre:
        sql.append("AND (lower(e.genre) LIKE ? OR lower(e.genre_tags) LIKE ?)")
        params += [f"%{args.genre.lower()}%", f"%{args.genre.lower()}%"]
    if args.title:
        sql.append("AND lower(e.title) LIKE ?")
        params.append(f"%{args.title.lower()}%")
    if args.artist:
        sql.append("AND lower(e.artist) LIKE ?")
        params.append(f"%{args.artist.lower()}%")

    rows = conn.execute(" ".join(sql), params).fetchall()

    # Post-filter on parsed time + computed distance (not easily done in SQL).
    results = []
    for r in rows:
        dt = _parse_dt(r["start"])
        if dt is None:
            continue
        minutes = dt.hour * 60 + dt.minute
        if after is not None and minutes < after:
            continue
        if before is not None and minutes > before:
            continue
        dist = None
        if r["lat"] is not None and r["lon"] is not None:
            dist = haversine_km(centre, (r["lat"], r["lon"]))
        if max_km is not None:
            if dist is None or dist > max_km:
                continue
        results.append((dt, dist, r))

    if args.sort == "distance":
        results.sort(key=lambda x: (x[1] is None, x[1] if x[1] is not None else 0, x[0]))
    else:
        results.sort(key=lambda x: x[0])

    _print_results(results, limit=args.limit)
    conn.close()


def _print_results(results, limit):
    if not results:
        print("No performances match those filters.")
        return
    total = len(results)
    shown = results[:limit] if limit else results
    for dt, dist, r in shown:
        when = dt.strftime("%a %d %b %H:%M")
        dist_s = f"{dist:4.1f}km" if dist is not None else "   ? km"
        dur = f"{r['duration_minutes']}m" if r["duration_minutes"] else ""
        price = r["price_string"] or ""
        print(f"{when}  {dist_s}  {r['title']}")
        meta = " · ".join(x for x in [r["venue_name"], r["genre"], dur, price] if x)
        if meta:
            print(f"                        {meta}")
    print(f"\n{len(shown)} of {total} matching performances"
          + (f" (showing first {limit})" if limit and total > limit else ""))


def cmd_info(args):
    if not os.path.exists(DB_PATH):
        sys.exit(f"No cache yet. Run:  python3 {os.path.basename(__file__)} fetch")
    conn = connect()
    meta = {row["key"]: row["value"] for row in conn.execute("SELECT key, value FROM meta")}
    n_ev = conn.execute("SELECT COUNT(*) FROM events").fetchone()[0]
    n_pf = conn.execute("SELECT COUNT(*) FROM performances").fetchone()[0]
    n_vn = conn.execute("SELECT COUNT(*) FROM venues").fetchone()[0]
    print(f"Cache: {DB_PATH}")
    print(f"Festival: {meta.get('festival','?')}  Year: {meta.get('year','?')}")
    print(f"Last fetch: {meta.get('last_fetch','never')}")
    print(f"Events: {n_ev}   Performances: {n_pf}   Venues: {n_vn}")
    _print_date_range(conn)
    conn.close()


# --------------------------------------------------------------------------- #
# CLI
# --------------------------------------------------------------------------- #
def build_parser():
    p = argparse.ArgumentParser(
        prog="fringe",
        description="Fetch and query Edinburgh Festival Fringe shows locally.",
    )
    sub = p.add_subparsers(dest="command", required=True)

    f = sub.add_parser("fetch", help="download/refresh the local cache")
    f.add_argument("--festival", default=DEFAULT_FESTIVAL)
    f.add_argument("--year", type=int, default=DEFAULT_YEAR)
    f.set_defaults(func=cmd_fetch)

    s = sub.add_parser("search", help="query the local cache")
    s.add_argument("--day", help="single date YYYY-MM-DD")
    s.add_argument("--date-from", help="earliest date YYYY-MM-DD")
    s.add_argument("--date-to", help="latest date YYYY-MM-DD")
    s.add_argument("--after", help="earliest start time HH:MM")
    s.add_argument("--before", help="latest start time HH:MM (e.g. 20:00)")
    s.add_argument("--max-distance", help="max distance from centre, e.g. 3km or 2miles")
    s.add_argument("--centre", help="centre point 'lat,lon' (default: Royal Mile)")
    s.add_argument("--genre", help="genre substring, e.g. comedy")
    s.add_argument("--title", help="title substring")
    s.add_argument("--artist", help="artist substring")
    s.add_argument("--sort", choices=["time", "distance"], default="time")
    s.add_argument("--limit", type=int, default=50, help="max rows (0 = all)")
    s.set_defaults(func=cmd_search)

    i = sub.add_parser("info", help="show cache contents / date range")
    i.set_defaults(func=cmd_info)

    return p


def main(argv=None):
    args = build_parser().parse_args(argv)
    args.func(args)


if __name__ == "__main__":
    main()

# fringe

A tiny, zero-dependency CLI to copy Edinburgh Festival Fringe event data
locally and query it by the things that actually decide a ticket purchase:
**which day**, **what time it starts**, and **how far the venue is from the
centre of town**.

Only the Python 3 standard library is used — nothing to install.

## Setup

Put your API credentials in a `.env` file next to `fringe.py` (already
gitignored):

```
FRINGE_API_KEY=your_key
FRINGE_API_SECRET=your_secret
```

## Usage

```bash
# Download / refresh the local cache (SQLite: fringe.db)
python3 fringe.py fetch                 # defaults: festival=fringe, year=2026

# What's cached?
python3 fringe.py info

# Find shows: a given day, starting before 8pm, within 3km of the centre
python3 fringe.py search --day 2026-08-15 --before 20:00 --max-distance 3km

# Everything is composable:
python3 fringe.py search \
    --date-from 2026-08-15 --date-to 2026-08-16 \
    --after 12:00 --before 20:00 \
    --max-distance 2km --genre comedy \
    --sort distance
```

### search filters

| flag              | meaning                                        |
|-------------------|------------------------------------------------|
| `--day`           | single date `YYYY-MM-DD`                       |
| `--date-from/-to` | date range                                     |
| `--after`         | earliest start time `HH:MM`                    |
| `--before`        | latest start time `HH:MM` (e.g. `20:00`)       |
| `--max-distance`  | e.g. `3km`, `2miles` — from the centre point   |
| `--centre`        | override centre as `lat,lon` (default: Royal Mile) |
| `--genre`         | substring match, e.g. `comedy`                 |
| `--title`/`--artist` | substring match                             |
| `--sort`          | `time` (default) or `distance`                 |
| `--limit`         | max rows (0 = all)                             |

## How it works

- **Auth**: each request is signed with HMAC-SHA1 over the path+query string
  (including the key), per the Fringe API docs.
- **Storage**: `fringe.db` holds one row per *performance* (the natural grain
  for picking a specific showing), plus events and venues, and the raw JSON.
- **Distance**: haversine from a configurable centre using each venue's
  latitude/longitude from the API — no geocoding needed.

# richhall

Utility for Edinburgh Festival analytics.

A tiny, zero-dependency CLI (`fringe.py`) to copy Edinburgh Festival Fringe
event data locally and query it by the things that actually decide a ticket
purchase: **which day**, **what time it starts**, and **how far the venue is
from the centre of town**.

Only the Python 3 standard library is used — nothing to install.

## Setup

Put your API credentials in a `.env` file next to `fringe.py` (already
gitignored):

```
FRINGE_API_KEY=your_key
FRINGE_API_SECRET=your_secret
```

## Usage

```bash
# Download / refresh the local cache (SQLite: fringe.db)
python3 fringe.py fetch                 # defaults: festival=fringe, year=2026

# What's cached?
python3 fringe.py info

# Find shows: a given day, starting before 8pm, within 3km of the centre
python3 fringe.py search --day 2026-08-15 --before 20:00 --max-distance 3km

# Everything is composable:
python3 fringe.py search \
    --date-from 2026-08-15 --date-to 2026-08-16 \
    --after 12:00 --before 20:00 \
    --max-distance 2km --genre comedy \
    --sort distance
```

### search filters

| flag                 | meaning                                            |
|----------------------|----------------------------------------------------|
| `--day`              | single date `YYYY-MM-DD`                           |
| `--date-from/-to`    | date range                                         |
| `--after`            | earliest start time `HH:MM`                        |
| `--before`           | latest start time `HH:MM` (e.g. `20:00`)           |
| `--max-distance`     | e.g. `3km`, `2miles` — from the centre point       |
| `--centre`           | override centre as `lat,lon` (default: Royal Mile) |
| `--genre`            | substring match, e.g. `comedy`                     |
| `--title`/`--artist` | substring match                                    |
| `--sort`             | `time` (default) or `distance`                     |
| `--limit`            | max rows (0 = all)                                 |

## How it works

- **Auth**: each request is signed with HMAC-SHA1 over the path+query string
  (including the key), per the Fringe API docs.
- **Storage**: `fringe.db` holds one row per *performance* (the natural grain
  for picking a specific showing), plus events and venues, and the raw JSON.
- **Distance**: haversine from a configurable centre using each venue's
  latitude/longitude from the API — no geocoding needed.

import os
from pathlib import Path

API_DOMAIN = "https://api.edinburghfestivalcity.com"
PAGE_SIZE = 100  # API maximum page size

DEFAULT_FESTIVAL = "fringe"
DEFAULT_YEAR = 2026
# Rough centre of the Old Town / Royal Mile — a sensible "middle of town".
DEFAULT_CENTRE = (55.9497, -3.1875)

config_dir_path = str(Path.home() / ".config" / "richhall")
default_config_file_path = os.path.join(config_dir_path, "config.yml")

data_dir_path = str(Path.home() / ".local" / "share" / "richhall")
default_db_path = os.path.join(data_dir_path, "fringe.db")

from dataclasses import dataclass


@dataclass
class CliOptions:
    debug: bool
    quiet: bool


@dataclass
class Config:
    festival: str
    year: int
    centre: tuple
    api_key: str
    api_secret: str
    db_path: str

# Exposing the truth that dependency injection is just a fancy name for global variables

from richhall.types import CliOptions


class d:
    opt: CliOptions = None

import sys

from richhall.di import d


def fatal_error(s: str):
    print(s, file=sys.stderr)
    sys.exit(1)


def debug(s: str):
    if d.opt and d.opt.debug:
        print(s, file=sys.stderr)


def info(s: str):
    if d.opt and d.opt.quiet:
        return
    print(s, file=sys.stderr)


def output(s: str):
    print(s)

import ruamel.yaml


def yaml():
    y = ruamel.yaml.YAML()
    y.preserve_quotes = True
    return y

import os
import re

from richhall import constants
from richhall.factory import yaml
from richhall.log import debug, fatal_error
from richhall.types import Config

_env_var_pattern = re.compile(r"\$\{([^}]+)\}")


def _expand_env_vars(value):
    """Recursively expand ${VAR} / ${VAR:-default} references in config values."""
    if isinstance(value, str):

        def _replace(match):
            expr = match.group(1)
            if ":-" in expr:
                var_name, default = expr.split(":-", 1)
                return os.environ.get(var_name, default)
            if expr not in os.environ:
                fatal_error(f"Environment variable '{expr}' referenced in config is not set")
            return os.environ[expr]

        return _env_var_pattern.sub(_replace, value)
    if isinstance(value, dict):
        return {k: _expand_env_vars(v) for k, v in value.items()}
    if isinstance(value, list):
        return [_expand_env_vars(item) for item in value]
    return value


def _load_dotenv(path):
    """Load KEY=VALUE lines from a .env file into the environment (without
    clobbering vars already set)."""
    if not os.path.exists(path):
        return
    with open(path, encoding="utf-8") as fh:
        for line in fh:
            line = line.strip()
            if not line or line.startswith("#") or "=" not in line:
                continue
            key, _, value = line.partition("=")
            os.environ.setdefault(key.strip(), value.strip().strip('"').strip("'"))


def _parse_centre(text):
    try:
        lat, lon = (float(x) for x in str(text).split(","))
        return (lat, lon)
    except Exception:
        fatal_error(f"Invalid centre '{text}': expected 'lat,lon' e.g. 55.9497,-3.1875")


def get(config_file_name=None) -> Config:
    # Load a project-local .env for developer convenience.
    _load_dotenv(os.path.join(os.getcwd(), ".env"))

    data = {}
    path = config_file_name or constants.default_config_file_path
    if os.path.exists(path):
        data = _expand_env_vars(yaml().load(open(path, "r")) or {})
        debug(f"Loaded config file: {path}")

    api_key = str(data.get("api-key") or os.environ.get("FRINGE_API_KEY", "")).strip()
    api_secret = str(data.get("api-secret") or os.environ.get("FRINGE_API_SECRET", "")).strip()
    centre = _parse_centre(data["centre"]) if data.get("centre") else constants.DEFAULT_CENTRE

    return Config(
        festival=data.get("festival", constants.DEFAULT_FESTIVAL),
        year=int(data.get("year", constants.DEFAULT_YEAR)),
        centre=centre,
        api_key=api_key,
        api_secret=api_secret,
        db_path=os.path.expanduser(data.get("db-path", constants.default_db_path)),
    )


def require_credentials(cfg: Config):
    if not cfg.api_key or not cfg.api_secret:
        fatal_error(
            "FRINGE_API_KEY and FRINGE_API_SECRET must be set "
            "(in the environment, a .env file, or the config file)."
        )

import hashlib
import hmac
import urllib.parse

import requests

from richhall import constants
from richhall.log import fatal_error


def signed_url(path, params, key, secret):
    """Build a signed request URL.

    The API signs the full path + query string (including the key, excluding
    the domain) with HMAC-SHA1 keyed by the secret; the hex signature is then
    appended as &signature=...  The signed string must exactly match what is
    sent, so we build the query string once and reuse it verbatim.
    """
    items = list(params.items()) + [("key", key)]
    query = urllib.parse.urlencode(items, quote_via=urllib.parse.quote)
    signed_path = f"{path}?{query}"
    signature = hmac.new(secret.encode("utf-8"), signed_path.encode("utf-8"), hashlib.sha1).hexdigest()
    return f"{constants.API_DOMAIN}{signed_path}&signature={signature}"


def api_get(path, params, cfg):
    url = signed_url(path, params, cfg.api_key, cfg.api_secret)
    try:
        resp = requests.get(url, headers={"Accept": "application/json"}, timeout=60)
        resp.raise_for_status()
        return resp.json()
    except requests.HTTPError as exc:
        status = exc.response.status_code if exc.response is not None else "?"
        body = exc.response.text[:500] if exc.response is not None else ""
        fatal_error(f"HTTP {status} from {path}: {body}")
    except requests.RequestException as exc:
        fatal_error(f"Could not reach API: {exc}")


def paged_get(path, params, cfg):
    """Yield records across all pages of a listing endpoint."""
    offset = 0
    while True:
        page_params = dict(params, size=constants.PAGE_SIZE, **{"from": offset})
        data = api_get(path, page_params, cfg)
        # Listing endpoints return a JSON array; tolerate a dict wrapper too.
        if isinstance(data, dict):
            records = data.get("events") or data.get("venues") or data.get("results") or []
        else:
            records = data
        if not records:
            break
        for rec in records:
            yield rec
        if len(records) < constants.PAGE_SIZE:
            break
        offset += constants.PAGE_SIZE

import json
import os
import sqlite3

SCHEMA = """
CREATE TABLE IF NOT EXISTS events (
    id            TEXT PRIMARY KEY,
    title         TEXT,
    sub_title     TEXT,
    artist        TEXT,
    genre         TEXT,
    genre_tags    TEXT,
    country       TEXT,
    age_category  TEXT,
    status        TEXT,
    description   TEXT,
    url           TEXT,
    website       TEXT,
    venue_id      TEXT,
    venue_name    TEXT,
    latitude      REAL,
    longitude     REAL,
    updated       TEXT,
    raw           TEXT
);

CREATE TABLE IF NOT EXISTS performances (
    perf_id          TEXT PRIMARY KEY,
    event_id         TEXT,
    start            TEXT,
    end              TEXT,
    duration_minutes INTEGER,
    is_at_fixed_time INTEGER,
    price_string     TEXT,
    price            REAL,
    title            TEXT
);

CREATE TABLE IF NOT EXISTS venues (
    id        TEXT PRIMARY KEY,
    name      TEXT,
    address   TEXT,
    post_code TEXT,
    code      TEXT,
    latitude  REAL,
    longitude REAL,
    raw       TEXT
);

CREATE TABLE IF NOT EXISTS meta (key TEXT PRIMARY KEY, value TEXT);

CREATE INDEX IF NOT EXISTS idx_perf_event ON performances(event_id);
CREATE INDEX IF NOT EXISTS idx_perf_start ON performances(start);
"""


def connect(db_path):
    parent = os.path.dirname(db_path)
    if parent:
        os.makedirs(parent, exist_ok=True)
    conn = sqlite3.connect(db_path)
    conn.row_factory = sqlite3.Row
    conn.executescript(SCHEMA)
    return conn


def to_float(value):
    try:
        return float(value)
    except (TypeError, ValueError):
        return None


def set_meta(conn, key, value):
    conn.execute("INSERT OR REPLACE INTO meta (key, value) VALUES (?, ?)", (key, value))


def get_meta(conn):
    return {row["key"]: row["value"] for row in conn.execute("SELECT key, value FROM meta")}


def performance_date_range(conn):
    """Return (first_date, last_date, count) as YYYY-MM-DD strings."""
    row = conn.execute(
        "SELECT MIN(start) AS lo, MAX(start) AS hi, COUNT(*) AS n "
        "FROM performances WHERE start IS NOT NULL AND start != ''"
    ).fetchone()
    if not row or not row["n"]:
        return (None, None, 0)
    return (str(row["lo"])[:10], str(row["hi"])[:10], row["n"])


def store_event(conn, ev):
    venue = ev.get("venue") or {}
    pos = venue.get("position") or {}
    lat = to_float(ev.get("latitude")) or to_float(pos.get("lat"))
    lon = to_float(ev.get("longitude")) or to_float(pos.get("lon"))
    genre_tags = ev.get("genre_tags")
    if isinstance(genre_tags, list):
        genre_tags = ", ".join(genre_tags)
    conn.execute(
        """INSERT OR REPLACE INTO events
           (id, title, sub_title, artist, genre, genre_tags, country,
            age_category, status, description, url, website, venue_id,
            venue_name, latitude, longitude, updated, raw)
           VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)""",
        (
            ev.get("id"),
            ev.get("title"),
            ev.get("sub_title"),
            ev.get("artist"),
            ev.get("genre"),
            genre_tags,
            ev.get("country"),
            ev.get("age_category"),
            ev.get("status"),
            ev.get("description_teaser") or ev.get("description"),
            ev.get("url"),
            ev.get("website"),
            venue.get("id"),
            venue.get("name"),
            lat,
            lon,
            ev.get("updated"),
            json.dumps(ev),
        ),
    )
    # Refresh this event's performances.
    conn.execute("DELETE FROM performances WHERE event_id = ?", (ev.get("id"),))
    for p in ev.get("performances") or []:
        conn.execute(
            """INSERT OR REPLACE INTO performances
               (perf_id, event_id, start, end, duration_minutes,
                is_at_fixed_time, price_string, price, title)
               VALUES (?,?,?,?,?,?,?,?,?)""",
            (
                p.get("id"),
                ev.get("id"),
                p.get("start"),
                p.get("end"),
                p.get("duration_minutes"),
                1 if p.get("is_at_fixed_time") else 0,
                p.get("price_string"),
                to_float(p.get("price")),
                p.get("title"),
            ),
        )


def store_venue(conn, v):
    pos = v.get("position") or {}
    conn.execute(
        """INSERT OR REPLACE INTO venues
           (id, name, address, post_code, code, latitude, longitude, raw)
           VALUES (?,?,?,?,?,?,?,?)""",
        (
            v.get("id"),
            v.get("name"),
            v.get("address"),
            v.get("post_code"),
            v.get("code"),
            to_float(pos.get("lat")),
            to_float(pos.get("lon")),
            json.dumps(v),
        ),
    )

import math
from datetime import datetime

MILES_TO_KM = 1.609344


def haversine_km(a, b):
    """Great-circle distance in kilometres between two (lat, lon) points."""
    lat1, lon1 = a
    lat2, lon2 = b
    r = 6371.0
    p1, p2 = math.radians(lat1), math.radians(lat2)
    dp = math.radians(lat2 - lat1)
    dl = math.radians(lon2 - lon1)
    h = math.sin(dp / 2) ** 2 + math.cos(p1) * math.cos(p2) * math.sin(dl / 2) ** 2
    return 2 * r * math.asin(math.sqrt(h))


def parse_distance(text):
    """Parse '3km' / '2miles' / '1.5mi' / '3' (km) into kilometres."""
    text = text.strip().lower()
    num = ""
    for ch in text:
        if ch.isdigit() or ch == ".":
            num += ch
        else:
            break
    if not num:
        raise ValueError(f"bad distance: {text!r}")
    val = float(num)
    unit = text[len(num):].strip()
    if unit.startswith("mi"):
        return val * MILES_TO_KM
    return val  # default km


def parse_hm(text):
    """Parse 'HH:MM' into minutes since midnight."""
    try:
        h, m = text.split(":")
        return int(h) * 60 + int(m)
    except Exception:
        raise ValueError(f"bad time (want HH:MM): {text!r}")


def parse_dt(value):
    """Parse an API datetime string tolerantly. Returns a datetime or None."""
    if not value:
        return None
    value = value.strip().replace("T", " ")
    value = value.split("+")[0].split(".")[0].strip()
    for fmt in ("%Y-%m-%d %H:%M:%S", "%Y-%m-%d %H:%M", "%Y-%m-%d"):
        try:
            return datetime.strptime(value, fmt)
        except ValueError:
            continue
    return None

from datetime import datetime

import click

from richhall import api, config, db
from richhall.log import info, output
from richhall.types import Config


@click.command(help="Download or refresh the local cache of events and venues")
@click.pass_context
def command(context):
    cfg: Config = context.obj
    config.require_credentials(cfg)
    conn = db.connect(cfg.db_path)
    base = {"festival": cfg.festival, "year": cfg.year}

    info(f"Fetching {cfg.festival} events for {cfg.year} …")
    n_events = 0
    for ev in api.paged_get("/events", base, cfg):
        db.store_event(conn, ev)
        n_events += 1
        if n_events % 100 == 0:
            info(f"  {n_events} events …")
            conn.commit()
    conn.commit()

    info(f"Fetching {cfg.festival} venues for {cfg.year} …")
    n_venues = 0
    for v in api.paged_get("/venues", base, cfg):
        db.store_venue(conn, v)
        n_venues += 1
    conn.commit()

    db.set_meta(conn, "last_fetch", datetime.now().isoformat(timespec="seconds"))
    db.set_meta(conn, "festival", cfg.festival)
    db.set_meta(conn, "year", str(cfg.year))
    conn.commit()

    output(f"Done. {n_events} events, {n_venues} venues cached in {cfg.db_path}")
    lo, hi, n = db.performance_date_range(conn)
    if n:
        output(f"Performances span {lo} → {hi} ({n} showings).")
    conn.close()

import click

from richhall import db
from richhall.geo import haversine_km, parse_distance, parse_dt, parse_hm
from richhall.log import fatal_error, output
from richhall.types import Config


def _build_query(args):
    sql = [
        "SELECT p.start AS start, p.price_string AS price_string,",
        "       p.duration_minutes AS duration_minutes,",
        "       e.title AS title, e.artist AS artist, e.genre AS genre,",
        "       e.venue_name AS venue_name, e.latitude AS lat, e.longitude AS lon,",
        "       e.url AS url",
        "FROM performances p JOIN events e ON e.id = p.event_id",
        "WHERE 1=1",
        "AND (e.status IS NULL OR e.status NOT IN ('cancelled','deleted'))",
    ]
    params = []
    if args["day"]:
        sql.append("AND substr(p.start,1,10) = ?")
        params.append(args["day"])
    if args["date_from"]:
        sql.append("AND substr(p.start,1,10) >= ?")
        params.append(args["date_from"])
    if args["date_to"]:
        sql.append("AND substr(p.start,1,10) <= ?")
        params.append(args["date_to"])
    if args["genre"]:
        sql.append("AND (lower(e.genre) LIKE ? OR lower(e.genre_tags) LIKE ?)")
        params += [f"%{args['genre'].lower()}%", f"%{args['genre'].lower()}%"]
    if args["title"]:
        sql.append("AND lower(e.title) LIKE ?")
        params.append(f"%{args['title'].lower()}%")
    if args["artist"]:
        sql.append("AND lower(e.artist) LIKE ?")
        params.append(f"%{args['artist'].lower()}%")
    return " ".join(sql), params


def _print_results(results, limit):
    if not results:
        output("No performances match those filters.")
        return
    total = len(results)
    shown = results[:limit] if limit else results
    for dt, dist, r in shown:
        when = dt.strftime("%a %d %b %H:%M")
        dist_s = f"{dist:5.2f}km" if dist is not None else "    ? km"
        dur = f"{r['duration_minutes']}m" if r["duration_minutes"] else ""
        price = r["price_string"] or ""
        output(f"{when}  {dist_s}  {r['title']}")
        meta = " · ".join(x for x in [r["venue_name"], r["genre"], dur, price] if x)
        if meta:
            output(f"                        {meta}")
    tail = f" (showing first {limit})" if limit and total > limit else ""
    output(f"\n{len(shown)} of {total} matching performances{tail}")


@click.command(help="Query the local cache for shows matching your constraints")
@click.option("--day", metavar="<YYYY-MM-DD>", help="Single date")
@click.option("--date-from", metavar="<YYYY-MM-DD>", help="Earliest date")
@click.option("--date-to", metavar="<YYYY-MM-DD>", help="Latest date")
@click.option("--after", metavar="<HH:MM>", help="Earliest start time")
@click.option("--before", metavar="<HH:MM>", help="Latest start time, e.g. 20:00")
@click.option("--max-distance", metavar="<DIST>", help="Max distance from centre, e.g. 3km or 2miles")
@click.option("--centre", metavar="<LAT,LON>", help="Override centre point (default: config / Royal Mile)")
@click.option("--genre", metavar="<TEXT>", help="Genre substring, e.g. comedy")
@click.option("--title", metavar="<TEXT>", help="Title substring")
@click.option("--artist", metavar="<TEXT>", help="Artist substring")
@click.option("--sort", type=click.Choice(["time", "distance"]), default="time", help="Sort order")
@click.option("--limit", type=int, default=50, help="Max rows (0 = all)")
@click.pass_context
def command(context, day, date_from, date_to, after, before, max_distance, centre, genre, title, artist, sort, limit):
    cfg: Config = context.obj

    centre_point = cfg.centre
    if centre:
        try:
            lat, lon = (float(x) for x in centre.split(","))
            centre_point = (lat, lon)
        except Exception:
            fatal_error("--centre must be 'lat,lon' e.g. 55.9497,-3.1875")

    try:
        max_km = parse_distance(max_distance) if max_distance else None
        after_min = parse_hm(after) if after else None
        before_min = parse_hm(before) if before else None
    except ValueError as exc:
        fatal_error(str(exc))

    conn = db.connect(cfg.db_path)
    sql, params = _build_query(
        dict(day=day, date_from=date_from, date_to=date_to, genre=genre, title=title, artist=artist)
    )
    rows = conn.execute(sql, params).fetchall()

    # Post-filter on parsed start time and computed distance.
    results = []
    for r in rows:
        dt = parse_dt(r["start"])
        if dt is None:
            continue
        minutes = dt.hour * 60 + dt.minute
        if after_min is not None and minutes < after_min:
            continue
        if before_min is not None and minutes > before_min:
            continue
        dist = None
        if r["lat"] is not None and r["lon"] is not None:
            dist = haversine_km(centre_point, (r["lat"], r["lon"]))
        if max_km is not None and (dist is None or dist > max_km):
            continue
        results.append((dt, dist, r))

    if sort == "distance":
        results.sort(key=lambda x: (x[1] is None, x[1] if x[1] is not None else 0, x[0]))
    else:
        results.sort(key=lambda x: x[0])

    _print_results(results, limit)
    conn.close()

import os

import click

from richhall import db
from richhall.log import fatal_error, output
from richhall.types import Config


@click.command(help="Show what is in the local cache")
@click.pass_context
def command(context):
    cfg: Config = context.obj
    if not os.path.exists(cfg.db_path):
        fatal_error(f"No cache yet at {cfg.db_path}. Run:  richhall fetch")

    conn = db.connect(cfg.db_path)
    meta = db.get_meta(conn)
    n_ev = conn.execute("SELECT COUNT(*) FROM events").fetchone()[0]
    n_pf = conn.execute("SELECT COUNT(*) FROM performances").fetchone()[0]
    n_vn = conn.execute("SELECT COUNT(*) FROM venues").fetchone()[0]

    output(f"Cache: {cfg.db_path}")
    output(f"Festival: {meta.get('festival', '?')}  Year: {meta.get('year', '?')}")
    output(f"Last fetch: {meta.get('last_fetch', 'never')}")
    output(f"Events: {n_ev}   Performances: {n_pf}   Venues: {n_vn}")
    lo, hi, n = db.performance_date_range(conn)
    if n:
        output(f"Performances span {lo} → {hi} ({n} showings).")
    conn.close()

import os

import click

from richhall import config as config_mod
from richhall import constants
from richhall.di import d
from richhall.log import output
from richhall.subcommands import fetch, info, search
from richhall.types import CliOptions

CLICK_CONTEXT_SETTINGS = dict(help_option_names=["-h", "--help"])


@click.group(context_settings=CLICK_CONTEXT_SETTINGS)
@click.option("--debug", is_flag=True, default=False, help="Enable debug output")
@click.option("--quiet", is_flag=True, default=False, help="Suppress non-essential output")
@click.option("--config-file", metavar="<PATH>", help=f"Config file (default {constants.default_config_file_path})")
@click.pass_context
def main(context, debug, quiet, config_file):
    d.opt = CliOptions(debug=debug, quiet=quiet)
    if context.invoked_subcommand == "version":
        return
    context.obj = config_mod.get(config_file)


@main.command()
def version():
    try:
        version_file = os.path.join(os.path.dirname(__file__), "version.txt")
        with open(version_file) as f:
            output(f.read().strip())
    except FileNotFoundError:
        output("dev")


main.add_command(fetch.command, "fetch")
main.add_command(search.command, "search")
main.add_command(info.command, "info")

[project]
name = "richhall"
version = "0.1.0"
description = "Utility for Edinburgh Festival analytics"
readme = "README.md"
requires-python = ">=3.10"
authors = [
    { name = "David Boreham" },
]
classifiers = [
    "Programming Language :: Python :: 3.10",
    "Operating System :: OS Independent",
]
dependencies = [
    "click>=8.1.7",
    "requests>=2.32.4",
    "ruamel.yaml>=0.17.32",
]

[project.scripts]
richhall = "richhall.main:main"

[project.urls]
Homepage = "https://github.com/stirlingbridge/richhall"

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.pytest.ini_options]
addopts = "-q"

[dependency-groups]
dev = [
    "ruff",
    "pytest",
]

[tool.ruff]
line-length = 132

[tool.ruff.lint]
select = ["E", "F", "W", "C90"]
ignore = ["E203"]

[tool.ruff.lint.mccabe]
max-complexity = 25

# Setup dev environment
dev:
	uv sync

build:
	./sh/build-package.sh

test:
	uv run pytest tests/ -v

lint:
	uv run ruff check richhall/
	uv run ruff format --check richhall/

#!/bin/bash
uv sync

#!/bin/bash

if [[ "$1" == "--fix" ]]; then
  uv run ruff format richhall/
  uv run ruff check --fix richhall/
else
  uv run ruff format --check richhall/
  uv run ruff check richhall/
fi

#!/bin/bash
# Emit a version string for the build (git describe, or a fallback).
git describe --tags --always --dirty 2>/dev/null || echo dev

#!/bin/bash
set -e
mkdir -p ./build
./sh/make-release-tag.sh > ./richhall/version.txt
uvx shiv -c richhall -o build/richhall .

include README.md

. .venv/bin/activate

# Secrets — never commit
.env

# Byte-compiled / optimized files
__pycache__/
*.py[cod]

# Egg / build artifacts
*.egg-info/
build

# Virtual environments
.venv
dev

# Generated at build time
richhall/version.txt

# Local data cache (usually lives in ~/.local/share/richhall)
*.sqlite
*.sqlite-journal
fringe.db

import hashlib
import hmac

from richhall.api import signed_url


def test_signed_url_orders_key_last_and_signs_path_query():
    """The signature must cover the exact path+query that is sent, with the
    access key included last, per the Fringe API docs."""
    url = signed_url("/events", {"festival": "jazz"}, "KEY", "SECRET")

    expected_query = "/events?festival=jazz&key=KEY"
    expected_sig = hmac.new(b"SECRET", expected_query.encode(), hashlib.sha1).hexdigest()
    assert url == "https://api.edinburghfestivalcity.com" + expected_query + "&signature=" + expected_sig


def test_signed_url_url_encodes_parameters():
    url = signed_url("/events", {"title": "a b&c"}, "KEY", "SECRET")
    # Space and ampersand in the value must be percent-encoded before signing.
    assert "title=a%20b%26c" in url
    assert url.count("&signature=") == 1

import math

import pytest

from richhall.geo import haversine_km, parse_distance, parse_dt, parse_hm


def test_haversine_zero_distance():
    assert haversine_km((55.9497, -3.1875), (55.9497, -3.1875)) == 0


def test_haversine_one_degree_latitude_is_about_111km():
    d = haversine_km((0, 0), (1, 0))
    assert 111.0 < d < 111.5


def test_parse_distance_units():
    assert parse_distance("3km") == pytest.approx(3.0)
    assert parse_distance("5") == pytest.approx(5.0)  # bare number = km
    assert parse_distance("2miles") == pytest.approx(3.218688)
    assert parse_distance("1.5mi") == pytest.approx(2.414016)


def test_parse_distance_rejects_garbage():
    with pytest.raises(ValueError):
        parse_distance("soon")


def test_parse_hm():
    assert parse_hm("20:00") == 1200
    assert parse_hm("09:30") == 570


def test_parse_hm_rejects_garbage():
    with pytest.raises(ValueError):
        parse_hm("8pm")


def test_parse_dt_handles_iso_and_space_forms():
    assert parse_dt("2026-08-15T19:30:00").hour == 19
    assert parse_dt("2026-08-15 19:30:00").minute == 30
    assert parse_dt("2026-08-15").day == 15
    assert parse_dt("") is None
    assert parse_dt("not-a-date") is None

# CLAUDE.md

## Project Overview

CLI tool (`richhall`) for selecting Edinburgh Festival Fringe shows to attend.
It copies event and venue data locally via the Fringe API, then filters by the
criteria that actually decide a ticket purchase: **which day**, **performance
start time**, and **distance of the venue from the centre of town**.

- **Org**: Stirlingbridge (`github.com/stirlingbridge/richhall`)
- **Python**: >=3.10

## Tech Stack

- **CLI framework**: Click
- **HTTP**: requests (signed HMAC-SHA1 requests to the Fringe API)
- **Storage**: SQLite (`~/.local/share/richhall/fringe.db`), one row per performance
- **Config**: ruamel.yaml (`~/.config/richhall/config.yml`, optional) + `.env`
- **Build tooling**: uv (deps), hatchling (build backend), shiv (zipapp packaging)

## Project Structure

```
richhall/               # Main package
  main.py               # Click group entry point
  config.py             # Config file + .env loading, ${ENV} expansion
  constants.py          # API domain, XDG paths, defaults (festival/year/centre)
  di.py                 # Dependency injection / globals (d.opt)
  log.py                # fatal_error / debug / info / output helpers
  types.py              # CliOptions, Config dataclasses
  factory.py            # ruamel.yaml factory
  api.py                # Request signing + paginated fetch
  db.py                 # SQLite schema + upserts
  geo.py                # haversine + distance/time/date parsing
  subcommands/          # Click subcommands
    fetch.py            # download/refresh the cache
    search.py           # query with day/time/distance filters
    info.py             # show cache contents
sh/                     # Shell scripts (build, lint, dev-setup, release-tag)
tests/                  # pytest unit tests
pyproject.toml          # Project metadata and dependencies
```

## Credentials

The Fringe API needs an access key + secret (HMAC-SHA1 signing). Provide them via:
- environment: `FRINGE_API_KEY`, `FRINGE_API_SECRET`, or
- a project-local `.env` file (gitignored), or
- `~/.config/richhall/config.yml` as `api-key` / `api-secret` (supports `${ENV}`).

## Development Commands

```bash
uv sync                     # Install dependencies (creates .venv)
uv run richhall --help      # Run CLI in development
uv run richhall fetch       # Download/refresh the local cache
uv run pytest tests/        # Run tests
./sh/lint.sh --fix          # Auto-format with ruff, then lint
./sh/build-package.sh       # Build shiv executable to build/richhall
make dev | build | test | lint
```

## Code Style

- **Linter & Formatter**: ruff (line length 132, max complexity 25, E203 ignored)
- Config in `pyproject.toml` under `[tool.ruff]`

# richhall

Utility for Edinburgh Festival analytics.

A CLI (`richhall`) to copy Edinburgh Festival Fringe event data locally and
query it by the things that actually decide a ticket purchase: **which day**,
**what time it starts**, and **how far the venue is from the centre of town**.

## Setup

```bash
uv sync                     # create .venv and install dependencies
```

Provide your Fringe API credentials in any of these (checked in this order):

- environment variables `FRINGE_API_KEY` / `FRINGE_API_SECRET`
- a project-local `.env` file (gitignored):
  ```
  FRINGE_API_KEY=your_key
  FRINGE_API_SECRET=your_secret
  ```
- `~/.config/richhall/config.yml` (`api-key` / `api-secret`, `${ENV}` supported)

## Usage

```bash
# Download / refresh the local cache (SQLite in ~/.local/share/richhall)
uv run richhall fetch                 # defaults: festival=fringe, year=2026

# What's cached?
uv run richhall info

# Find shows: a given day, starting before 8pm, within 3km of the centre
uv run richhall search --day 2026-08-15 --before 20:00 --max-distance 3km

# Everything is composable:
uv run richhall search \
    --date-from 2026-08-15 --date-to 2026-08-16 \
    --after 12:00 --before 20:00 \
    --max-distance 2km --genre comedy \
    --sort distance
```

### search filters

| flag                 | meaning                                            |
|----------------------|----------------------------------------------------|
| `--day`              | single date `YYYY-MM-DD`                           |
| `--date-from/-to`    | date range                                         |
| `--after`            | earliest start time `HH:MM`                        |
| `--before`           | latest start time `HH:MM` (e.g. `20:00`)           |
| `--max-distance`     | e.g. `3km`, `2miles` — from the centre point       |
| `--centre`           | override centre as `lat,lon` (default: Royal Mile) |
| `--genre`            | substring match, e.g. `comedy`                     |
| `--title`/`--artist` | substring match                                    |
| `--sort`             | `time` (default) or `distance`                     |
| `--limit`            | max rows (0 = all)                                 |

### optional config

`~/.config/richhall/config.yml` can set defaults so you don't repeat flags:

```yaml
festival: fringe
year: 2026
centre: "55.9497,-3.1875"    # your preferred "middle of town"
# api-key: ${FRINGE_API_KEY}
# api-secret: ${FRINGE_API_SECRET}
```

## How it works

- **Auth**: each request is signed with HMAC-SHA1 over the path+query string
  (including the key), per the Fringe API docs.
- **Storage**: SQLite holds one row per *performance* (the natural grain for
  picking a specific showing), plus events and venues, and the raw JSON.
- **Distance**: haversine from a configurable centre using each venue's
  latitude/longitude from the API — no geocoding needed.

## Development

```bash
make dev      # uv sync
make test     # pytest
make lint     # ruff check + format check
make build    # shiv single-file executable -> build/richhall
```

See `CLAUDE.md` for the full project layout.