transitlog 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
transitlog/__init__.py ADDED
@@ -0,0 +1,31 @@
1
+ # SPDX-License-Identifier: MIT
2
+ # Copyright (C) 2026 Amol Venkataraman
3
+ """Download and summarise your own transit-card trip and purchase history.
4
+
5
+ Provided AS IS, without warranty of any kind; see LICENSE and DISCLAIMER.md.
6
+ """
7
+ __version__ = "0.1.0"
8
+
9
+ from .clipper import ClipperClient
10
+ from .config import ConfigError, Credentials, resolve_credentials
11
+ from .errors import LoginFailed, TransitError, UnsafeRequest
12
+ from .models import Card, Order, Trip
13
+ from .presto import PrestoClient
14
+ from .report import build_report, render_report
15
+
16
+ __all__ = [
17
+ "Card",
18
+ "ClipperClient",
19
+ "ConfigError",
20
+ "Credentials",
21
+ "LoginFailed",
22
+ "Order",
23
+ "PrestoClient",
24
+ "TransitError",
25
+ "Trip",
26
+ "UnsafeRequest",
27
+ "__version__",
28
+ "build_report",
29
+ "render_report",
30
+ "resolve_credentials",
31
+ ]
transitlog/__main__.py ADDED
@@ -0,0 +1,7 @@
1
+ # SPDX-License-Identifier: MIT
2
+ # Copyright (C) 2026 Amol Venkataraman
3
+ import sys
4
+
5
+ from .cli import main
6
+
7
+ sys.exit(main())
transitlog/cli.py ADDED
@@ -0,0 +1,433 @@
1
+ # SPDX-License-Identifier: MIT
2
+ # Copyright (C) 2026 Amol Venkataraman
3
+ """`transitlog` command-line interface. Run `transitlog --help`."""
4
+ from __future__ import annotations
5
+
6
+ import argparse
7
+ import csv
8
+ import getpass
9
+ import json
10
+ import logging
11
+ import os
12
+ import sys
13
+ import textwrap
14
+ from datetime import date, datetime, timedelta
15
+ from pathlib import Path
16
+ from typing import Any
17
+
18
+ from . import __version__
19
+ from .clipper import TZ as CLIPPER_TZ
20
+ from .clipper import ClipperClient
21
+ from .config import (
22
+ CONFIG_FILE,
23
+ ConfigError,
24
+ default_password_file,
25
+ resolve_credentials,
26
+ write_password_file,
27
+ )
28
+ from .errors import TransitError
29
+ from .models import Order, Trip
30
+ from .presto import TZ as PRESTO_TZ
31
+ from .presto import PrestoClient
32
+ from .report import build_report, render_report
33
+
34
+ # Each provider: its client class, local timezone (for default "today"/range) and
35
+ # whether it offers per-order PDF receipts and monthly statement PDFs.
36
+ # "client" is the client class; _run resolves it through this module's namespace
37
+ # at call time, so tests can monkeypatch `cli.ClipperClient` / `cli.PrestoClient`.
38
+ PROVIDERS: dict[str, dict[str, Any]] = {
39
+ "clipper": {"client": ClipperClient, "tz": CLIPPER_TZ, "receipts": True,
40
+ "help": "Clipper card (SF Bay Area): clippercard.com account",
41
+ "desc": "Clipper card (SF Bay Area). Needs a clippercard.com account "
42
+ "with the card registered to it."},
43
+ "presto": {"client": PrestoClient, "tz": PRESTO_TZ, "receipts": False,
44
+ "help": "PRESTO card (Ontario): prestocard.ca account",
45
+ "desc": "PRESTO card (Ontario, Metrolinx). Needs a prestocard.ca account "
46
+ "with the card registered to it."},
47
+ }
48
+
49
+ GLOBAL_DEFAULTS: dict[str, Any] = {
50
+ "username": None, "password_file": None, "timeout": 30, "config": str(CONFIG_FILE),
51
+ "json": False, "debug": False,
52
+ }
53
+ DEFAULT_DAYS = 365
54
+ MAX_CELL = 40
55
+ TRIP_FIELDS = ["trip_id", "start_time", "operator", "start_location", "end_time", "end_location", "fare",
56
+ "product", "tap", "transfer", "transfer_credit", "account_id"]
57
+ ORDER_FIELDS = ["order_id", "time", "amount", "products", "payment", "payment_ref", "status", "order_type",
58
+ "account_id"]
59
+ DISCLAIMER_SHORT = ("Provided AS IS, without warranty of any kind, under the MIT License. "
60
+ "Written with AI assistance: review the code before running it. See DISCLAIMER.md.")
61
+
62
+
63
+ # --------------------------------------------------------------------------- output
64
+
65
+ def print_json(obj: Any) -> None:
66
+ print(json.dumps(obj, indent=2, default=str))
67
+
68
+
69
+ def print_table(rows: list[dict[str, Any]], columns: list[str], right: frozenset[str] = frozenset()) -> None:
70
+ if not rows:
71
+ print("(none)")
72
+ return
73
+
74
+ def cell(value: Any) -> str:
75
+ text = "" if value is None else str(value)
76
+ return text if len(text) <= MAX_CELL else text[: MAX_CELL - 1] + "…"
77
+
78
+ table = [[cell(row.get(c)) for c in columns] for row in rows]
79
+ widths = [max(len(c), *(len(r[i]) for r in table)) for i, c in enumerate(columns)]
80
+
81
+ def line(cells: list[str]) -> str:
82
+ return " ".join(v.rjust(w) if c in right else v.ljust(w)
83
+ for v, w, c in zip(cells, widths, columns, strict=True)).rstrip()
84
+ print(line([c.upper() for c in columns]))
85
+ for r in table:
86
+ print(line(r))
87
+
88
+
89
+ def flat(record: Trip | Order) -> dict[str, Any]:
90
+ """A record as one CSV/table row: lists joined with "; ", money as fixed two decimals.
91
+
92
+ The free-form `extra` dict is dropped here (it has no fixed column); it is kept
93
+ only in JSON output, via `to_dict()`, so no source data is lost.
94
+ """
95
+ row = record.to_dict()
96
+ row.pop("extra", None)
97
+ for k, v in list(row.items()):
98
+ if isinstance(v, list):
99
+ row[k] = "; ".join(str(x) for x in v)
100
+ for k in ("fare", "amount", "transfer_credit"):
101
+ if k in row:
102
+ value = getattr(record, k, None)
103
+ row[k] = f"{value:.2f}" if value is not None else ""
104
+ if "transfer" in row:
105
+ row["transfer"] = "yes" if getattr(record, "transfer", False) else ""
106
+ if row.get("tap") is None and "tap" in row:
107
+ row["tap"] = ""
108
+ return row
109
+
110
+
111
+ def write_records(path: Path, records: list[Trip] | list[Order], fields: list[str]) -> None:
112
+ if path.suffix.lower() == ".json":
113
+ path.write_text(json.dumps([r.to_dict() for r in records], indent=2) + "\n")
114
+ return
115
+ with path.open("w", newline="", encoding="utf-8") as f:
116
+ w = csv.DictWriter(f, fieldnames=fields, extrasaction="ignore")
117
+ w.writeheader()
118
+ w.writerows(flat(r) for r in records)
119
+
120
+
121
+ def short_time(value: str | None) -> str | None:
122
+ return value[:16].replace("T", " ") if value else value
123
+
124
+
125
+ def note(message: str) -> None:
126
+ print(message, file=sys.stderr)
127
+
128
+
129
+ # --------------------------------------------------------------------------- dates
130
+
131
+ def parse_date(value: str) -> date:
132
+ try:
133
+ return date.fromisoformat(value)
134
+ except ValueError:
135
+ raise argparse.ArgumentTypeError(f"{value!r} is not a date like 2026-05-31") from None
136
+
137
+
138
+ def resolve_range(a: argparse.Namespace) -> tuple[date, date]:
139
+ tz = PROVIDERS[a.provider]["tz"]
140
+ until = a.until or datetime.now(tz).date()
141
+ since = a.since or until - timedelta(days=(a.days or DEFAULT_DAYS) - 1)
142
+ return since, until
143
+
144
+
145
+ # --------------------------------------------------------------------------- commands
146
+
147
+ def cmd_cards(c: ClipperClient, a: argparse.Namespace) -> int:
148
+ cards = c.cards()
149
+ if a.json:
150
+ print_json([x.to_dict() for x in cards])
151
+ return 0
152
+ rows = [{**x.to_dict(), "card": x.label,
153
+ "cash_balance": f"${x.cash_balance:.2f}" if x.cash_balance is not None else None,
154
+ "passes": ", ".join(x.passes) or None, "autoload": "on" if x.autoload else "off",
155
+ "activated": (x.activated or "")[:10] or None} for x in cards]
156
+ print_table(rows, ["card", "card_number", "account_id", "rider_class", "status", "cash_balance", "passes",
157
+ "autoload", "activated"], {"cash_balance"})
158
+ return 0
159
+
160
+
161
+ def _emit_records(records: list[Trip] | list[Order], a: argparse.Namespace, fields: list[str],
162
+ columns: list[str], money: str) -> None:
163
+ if a.output:
164
+ write_records(Path(a.output), records, fields)
165
+ note(f"saved {len(records)} record(s) to {a.output}")
166
+ elif a.json:
167
+ print_json([r.to_dict() for r in records])
168
+ else:
169
+ rows = [flat(r) for r in records]
170
+ for row in rows:
171
+ for k in ("start_time", "end_time", "time"):
172
+ if k in row:
173
+ row[k] = short_time(row[k])
174
+ print_table(rows, columns, {money})
175
+
176
+
177
+ def cmd_trips(c: ClipperClient, a: argparse.Namespace) -> int:
178
+ since, until = resolve_range(a)
179
+ trips = c.trips(since, until, a.card)
180
+ _emit_records(trips, a, TRIP_FIELDS,
181
+ ["start_time", "operator", "start_location", "end_location", "fare", "product", "tap",
182
+ "transfer"], "fare")
183
+ return 0
184
+
185
+
186
+ def cmd_orders(c: ClipperClient, a: argparse.Namespace) -> int:
187
+ since, until = resolve_range(a)
188
+ orders = c.orders(since, until, a.card)
189
+ _emit_records(orders, a, ORDER_FIELDS, ["time", "order_id", "amount", "products", "payment"], "amount")
190
+ return 0
191
+
192
+
193
+ def save_receipts(c: ClipperClient, orders: list[Order], directory: Path) -> tuple[int, int, int]:
194
+ """Save each order's receipt. Returns (saved, already there, failed); failures become client warnings."""
195
+ directory.mkdir(parents=True, exist_ok=True)
196
+ saved = skipped = failed = 0
197
+ for o in orders:
198
+ path = directory / f"clipper-receipt-{o.time:%Y-%m-%d}-{o.order_id}.pdf"
199
+ if path.exists():
200
+ skipped += 1
201
+ continue
202
+ try:
203
+ pdf = c.receipt(o.order_id)
204
+ except TransitError as e: # Clipper fails to generate some receipts (seen on its oldest orders)
205
+ c.warnings.append(f"no receipt for order {o.order_id} ({o.time:%Y-%m-%d}): {e}")
206
+ failed += 1
207
+ continue
208
+ path.write_bytes(pdf)
209
+ saved += 1
210
+ return saved, skipped, failed
211
+
212
+
213
+ def cmd_receipts(c: ClipperClient, a: argparse.Namespace) -> int:
214
+ since, until = resolve_range(a)
215
+ saved, skipped, failed = save_receipts(c, c.orders(since, until, a.card), Path(a.dir))
216
+ extra = []
217
+ if skipped:
218
+ extra.append(f"{skipped} already there")
219
+ if failed:
220
+ extra.append(f"{failed} unavailable")
221
+ note(f"saved {saved} receipt(s) to {a.dir}" + (f" ({', '.join(extra)})" if extra else ""))
222
+ return 0
223
+
224
+
225
+ def save_statements(c: ClipperClient, since: date, until: date, card: str | None, directory: Path) -> int:
226
+ directory.mkdir(parents=True, exist_ok=True)
227
+ count = 0
228
+ for card_obj, start, end, pdf in c.statements(since, until, card):
229
+ last4 = (card_obj.card_number or card_obj.account_id)[-4:]
230
+ (directory / f"clipper-trips-{last4}-{start}_{end}.pdf").write_bytes(pdf)
231
+ count += 1
232
+ return count
233
+
234
+
235
+ def cmd_statements(c: ClipperClient, a: argparse.Namespace) -> int:
236
+ since, until = resolve_range(a)
237
+ count = save_statements(c, since, until, a.card, Path(a.dir))
238
+ note(f"saved {count} statement PDF(s) to {a.dir}")
239
+ return 0
240
+
241
+
242
+ def cmd_report(c: ClipperClient, a: argparse.Namespace) -> int:
243
+ since, until = resolve_range(a)
244
+ cards = c.select_cards(a.card)
245
+ report = build_report(c.trips(since, until, a.card), c.orders(since, until, a.card), since, until, cards)
246
+ if a.json:
247
+ print_json(report)
248
+ else:
249
+ print(render_report(report))
250
+ return 0
251
+
252
+
253
+ def cmd_export(c: ClipperClient, a: argparse.Namespace) -> int:
254
+ since, until = resolve_range(a)
255
+ out = Path(a.dir)
256
+ out.mkdir(parents=True, exist_ok=True)
257
+ cards = c.select_cards(a.card)
258
+ trips = c.trips(since, until, a.card)
259
+ orders = c.orders(since, until, a.card)
260
+ (out / "cards.json").write_text(json.dumps([x.to_dict() for x in cards], indent=2) + "\n")
261
+ for name, records, fields in (("trips", trips, TRIP_FIELDS), ("orders", orders, ORDER_FIELDS)):
262
+ write_records(out / f"{name}.csv", records, fields)
263
+ write_records(out / f"{name}.json", records, fields)
264
+ report = build_report(trips, orders, since, until, cards)
265
+ (out / "report.txt").write_text(render_report(report) + "\n")
266
+ (out / "report.json").write_text(json.dumps(report, indent=2, default=str) + "\n")
267
+ summary = f"{len(cards)} card(s), {len(trips)} trip(s), {len(orders)} order(s)"
268
+ if PROVIDERS[a.provider]["receipts"] and not getattr(a, "no_receipts", False):
269
+ saved, skipped, failed = save_receipts(c, orders, out / "receipts")
270
+ summary += f", {saved + skipped} receipt(s)" + (f" ({failed} unavailable)" if failed else "")
271
+ if getattr(a, "statements", False):
272
+ summary += f", {save_statements(c, since, until, a.card, out / 'statements')} statement PDF(s)"
273
+ note(f"exported {summary} for {since} to {until} into {out}")
274
+ return 0
275
+
276
+
277
+ # --------------------------------------------------------------------------- parser
278
+
279
+ def _add_global_options(p: argparse.ArgumentParser) -> None:
280
+ S = argparse.SUPPRESS # so options work before or after the subcommand
281
+ g = p.add_argument_group("account/output")
282
+ g.add_argument("--username", default=S, help="account email (default: config file or $TRANSITLOG_CLIPPER_USERNAME)")
283
+ g.add_argument("--password-file", default=S,
284
+ help="file whose first line is the password (default: ~/.config/transitlog/clipper.password)")
285
+ g.add_argument("--config", default=S, help="config file (default: ~/.config/transitlog/config.ini)")
286
+ g.add_argument("--timeout", type=int, default=S, help="request timeout in seconds (default: 30)")
287
+ g.add_argument("--json", action="store_true", default=S, help="machine-readable JSON output")
288
+ g.add_argument("--debug", action="store_true", default=S, help="log each request and raw errors to stderr")
289
+
290
+
291
+ def _add_range(p: argparse.ArgumentParser, card: bool = True) -> None:
292
+ g = p.add_argument_group("which history")
293
+ g.add_argument("--since", type=parse_date, metavar="YYYY-MM-DD",
294
+ help=f"first day (default: {DEFAULT_DAYS} days ago)")
295
+ g.add_argument("--until", type=parse_date, metavar="YYYY-MM-DD",
296
+ help="last day (default: today, in the provider's local time)")
297
+ g.add_argument("--days", type=int, metavar="N", help="the last N days, ending --until (ignored with --since)")
298
+ if card:
299
+ g.add_argument("--card", metavar="ID",
300
+ help="one card: account number, card number or last 4 digits (default: all)")
301
+
302
+
303
+ def build_parser() -> argparse.ArgumentParser:
304
+ parser = argparse.ArgumentParser(
305
+ prog="transitlog",
306
+ description="Download and summarise your own transit-card history. Read-only: it never buys, "
307
+ "loads, disputes or changes anything.",
308
+ epilog=textwrap.fill("Set a password with `transitlog <provider> set-password` (stored in "
309
+ "~/.config/transitlog/<provider>.password, mode 600) or set "
310
+ "$TRANSITLOG_<PROVIDER>_PASSWORD. Providers: " + ", ".join(PROVIDERS) + ".")
311
+ + "\n\n" + textwrap.fill(DISCLAIMER_SHORT),
312
+ formatter_class=argparse.RawDescriptionHelpFormatter)
313
+ parser.add_argument("--version", action="version",
314
+ version=f"%(prog)s {__version__}\n{textwrap.fill(DISCLAIMER_SHORT)}")
315
+ _add_global_options(parser)
316
+ providers = parser.add_subparsers(dest="provider", required=True, metavar="PROVIDER")
317
+ for name, spec in PROVIDERS.items():
318
+ _add_provider(providers, name, spec)
319
+ return parser
320
+
321
+
322
+ def _add_provider(providers: Any, name: str, spec: dict[str, Any]) -> None:
323
+ prov = providers.add_parser(name, help=spec["help"], description=spec["desc"])
324
+ _add_global_options(prov)
325
+ sub = prov.add_subparsers(dest="command", required=True, metavar="COMMAND")
326
+
327
+ def add(cmd: str, func, help_text: str, login: bool = True) -> argparse.ArgumentParser:
328
+ p = sub.add_parser(cmd, help=help_text, description=help_text)
329
+ _add_global_options(p)
330
+ p.set_defaults(func=func, login=login)
331
+ return p
332
+
333
+ add("cards", cmd_cards, "cards on the account, with balance and status")
334
+
335
+ for cmd, func, what in (("trips", cmd_trips, "trip history"),
336
+ ("orders", cmd_orders, "purchases: cash-value loads, passes, card fees")):
337
+ p = add(cmd, func, what)
338
+ _add_range(p)
339
+ p.add_argument("-o", "--output", metavar="FILE", help="save as CSV, or JSON if FILE ends in .json")
340
+
341
+ if spec["receipts"]:
342
+ p = add("receipts", cmd_receipts, "download a PDF receipt for every order (skips ones already saved)")
343
+ _add_range(p)
344
+ p.add_argument("-d", "--dir", default=f"{name}-receipts",
345
+ help=f"output directory (default: ./{name}-receipts)")
346
+
347
+ p = add("statements", cmd_statements, "download the provider's official trip-history PDFs (one per month)")
348
+ _add_range(p)
349
+ p.add_argument("-d", "--dir", default=f"{name}-statements",
350
+ help=f"output directory (default: ./{name}-statements)")
351
+
352
+ p = add("report", cmd_report, "usage summary: trips by operator/month/weekday, top stations, spending, pass value")
353
+ _add_range(p)
354
+
355
+ p = add("export", cmd_export, "everything into one folder: cards, trips and orders (CSV+JSON), report, receipts")
356
+ _add_range(p)
357
+ p.add_argument("-d", "--dir", default=f"{name}-export", help=f"output directory (default: ./{name}-export)")
358
+ if spec["receipts"]:
359
+ p.add_argument("--no-receipts", action="store_true", help="skip the per-order PDF receipts")
360
+ p.add_argument("--statements", action="store_true", help="also save the official trip-history PDFs")
361
+
362
+ p = add("set-password", None, f"save the {name} password to the password file (mode 600)", login=False)
363
+ p.add_argument("--file", default=str(default_password_file(name)),
364
+ help=f"where to store it (default: ~/.config/transitlog/{name}.password)")
365
+
366
+
367
+ def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
368
+ """Parse and validate everything that can be checked before logging in."""
369
+ parser = build_parser()
370
+ args = parser.parse_args(argv)
371
+ for name, default in GLOBAL_DEFAULTS.items():
372
+ if not hasattr(args, name):
373
+ setattr(args, name, default)
374
+ if getattr(args, "days", None) is not None and args.days < 1:
375
+ parser.error("--days must be at least 1")
376
+ if getattr(args, "since", None) and getattr(args, "until", None) and args.since > args.until:
377
+ parser.error("--since is after --until")
378
+ return args
379
+
380
+
381
+ def _run(args: argparse.Namespace, logger: logging.Logger | None) -> int:
382
+ if args.command == "set-password":
383
+ first = getpass.getpass(f"{args.provider.capitalize()} password: ")
384
+ if not first or first != getpass.getpass("Again: "):
385
+ note("error: passwords empty or did not match")
386
+ return 2
387
+ print(f"saved to {write_password_file(first, args.file)}")
388
+ return 0
389
+
390
+ credentials = resolve_credentials(args.provider, args.username, args.password_file, args.config)
391
+ # Re-read the class from this module so tests can monkeypatch it by name.
392
+ client_cls = getattr(sys.modules[__name__], PROVIDERS[args.provider]["client"].__name__)
393
+ with client_cls(credentials, timeout=args.timeout, logger=logger) as client:
394
+ code = args.func(client, args)
395
+ for warning in client.warnings:
396
+ note(f"warning: {warning}")
397
+ return code
398
+
399
+
400
+ def main(argv: list[str] | None = None) -> int:
401
+ args = parse_args(argv)
402
+ logging.basicConfig(level=logging.DEBUG if args.debug else logging.WARNING,
403
+ format="%(levelname)s %(name)s: %(message)s")
404
+ logger = logging.getLogger("transitlog") if args.debug else None
405
+ if not args.debug:
406
+ logging.getLogger("urllib3").setLevel(logging.WARNING)
407
+ try:
408
+ code = _run(args, logger)
409
+ sys.stdout.flush() # surface a closed pipe here rather than during interpreter shutdown
410
+ return code
411
+ except ConfigError as e:
412
+ note(f"error: {e}")
413
+ return 2
414
+ except TransitError as e:
415
+ note(f"error: {e}")
416
+ if args.debug and e.raw is not None:
417
+ note(f"raw error: {e.raw!r}")
418
+ return 1
419
+ except BrokenPipeError: # output piped into e.g. `head`, which exited early
420
+ devnull = os.open(os.devnull, os.O_WRONLY)
421
+ os.dup2(devnull, sys.stdout.fileno())
422
+ return 0
423
+ except KeyboardInterrupt:
424
+ return 130
425
+ except Exception as e:
426
+ if args.debug:
427
+ raise
428
+ note(f"error: {type(e).__name__}: {e} (re-run with --debug for details)")
429
+ return 1
430
+
431
+
432
+ if __name__ == "__main__":
433
+ sys.exit(main())