lbd-followback 0.1.0__tar.gz

lbd_followback-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+data/
+output/
+__pycache__/
+*.pyc
+dist/
+*.egg-info/

lbd_followback-0.1.0/.python-version

@@ -0,0 +1 @@
+3.14

lbd_followback-0.1.0/AGENTS.md

@@ -0,0 +1,67 @@
+# AGENTS.md — lbd-followback
+
+## Stack
+
+- Python 3.14+, managed via `uv` (not pip/conda)
+- `letterboxdpy` for scraping (NOT raw requests/BS4 — it handles TLS fingerprinting and retries)
+- `rich` for terminal output
+- `curl-cffi` (transitive via letterboxdpy) — Chrome impersonation, not stdlib `requests`
+
+## Commands
+
+```bash
+lbd-followback <username>                      # after uv tool install .
+uv run python -m lbd_followback <username>     # or via uv
+uv run python main.py <username>               # same, thin wrapper
+uv run python -m lbd_followback <username> -f  # bypass 24h cache
+uv add <pkg>                                   # add dep
+```
+
+No test/lint/typecheck scripts exist.
+
+## Architecture
+
+```
+main.py          → thin wrapper → lbd_followback.__main__.main()
+lbd_followback/
+  __main__.py    → CLI entrypoint (argparse)
+  __init__.py    → re-exports scrape, analyze, generate
+  transport.py   → HTTP session, retry, 429 backoff (depends on curl-cffi)
+  parser.py      → BS4 HTML parsing + number extraction
+  scraper.py     → pagination orchestration (uses transport + parser + cache)
+  cache.py       → JSON disk cache with 24h TTL
+  compare.py     → set math: mutual / not_following_back / not_followed_back
+  report.py      → HTML report generation
+  config.py      → constants (DOMAIN, delay, cache TTL)
+~/.cache/lbd-followback/ → cached JSON (auto-created)
+CWD/<username>_report.html → output (default)
+```
+
+## Key constraints
+
+- **Do not use letterboxdpy.User.get_following() directly** — it paginates internally without inter-page delay, triggering rate limits. Use `scraper.scrape()` which adds 3-4s delay between pages.
+- **DOMAIN** must come from `config.py` (`https://letterboxd.com`), never hardcoded.
+- **Number extraction** uses `parser.extract_number()` (regex), not ad-hoc `re.search`.
+- **429 handling**: exponential backoff 30s→60s→120s in `transport.py`. Do not change without testing against real LBD rate limits.
+- **Cache**: `~/.cache/lbd-followback/`, 24h TTL. Non-existent users are NOT cached (404 returns empty without saving).
+- **No parallel requests** — sequential only. Parallel triggers rate limits immediately.
+- **Entry point**: `lbd-followback = "lbd_followback.__main__:main"` in `[project.scripts]`. Also `python -m lbd_followback` works via `__main__.py`.
+- **Public API** re-exported from `__init__.py`: `scrape`, `analyze`, `generate`.
+- `rich.console.Console` is used for all user-facing output (not `print`).
+
+## Modules & boundaries
+
+| Module | Depends on | Never import |
+|--------|-----------|--------------|
+| transport.py | curl-cffi, bs4, rich | scraper, parser, cache |
+| parser.py | bs4, config | transport, scraper, cache |
+| scraper.py | transport, parser, cache | curl-cffi, bs4 directly |
+| cache.py | config, json, pathlib | scraper, transport, parser |
+| compare.py | nothing | scraper, transport, parser, cache |
+| report.py | config, rich | scraper, transport, parser, cache |
+
+## SOLID notes (applied)
+
+- transport.py abstracts HTTP (swap curl-cffi → httpx by changing one file)
+- parser.py abstracts BS4 (swap to selectolax by changing one file)
+- scraper.py is an orchestrator only — no HTTP or parsing logic