arxivscanner 0.1.0__tar.gz

arxivscanner-0.1.0/MANIFEST.in

@@ -0,0 +1 @@
+recursive-include tests *.py *.xml

arxivscanner-0.1.0/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: arxivscanner
+Version: 0.1.0
+Summary: Fetch and display new arXiv papers for a domain or subdomain, from the terminal.
+Author-email: Subham <shubham.divakar@gmail.com>
+Project-URL: Homepage, https://github.com/shubham10divakar/arxivscanner
+Project-URL: Issues, https://github.com/shubham10divakar/arxivscanner/issues
+Keywords: arxiv,papers,research,rss,cli
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# arXiv Scanner
+
+A command-line tool that fetches and shows new arXiv papers for a chosen **domain** (archive, for example `cs`) and **subdomain** (category, for example `cs.CV`).
+
+It uses only the Python standard library, so there is nothing to `pip install`. It needs Python 3.9 or later and runs on Windows, macOS and Linux.
+
+## Installation
+
+Install from GitHub with pip:
+
+```bash
+pip install git+https://github.com/shubham10divakar/arxivscanner.git
+arxivscanner --list        # check it works: prints every known domain and subdomain
+```
+
+This installs an `arxivscanner` command. `python -m arxivscanner …` works the same way. Use `python3 -m pip` on macOS or Linux if `pip` points at an older Python.
+
+To work on the code instead, clone the repo and install it in editable mode:
+
+```bash
+git clone https://github.com/shubham10divakar/arxivscanner.git
+cd arxivscanner
+pip install -e .
+```
+
+Without installing, `python run.py …` from the repo folder also works.
+
+## How to use it
+
+### 1. Interactive mode (easiest)
+
+Run the tool with no arguments and answer the prompts:
+
+```bash
+arxivscanner
+```
+
+1. **Pick a domain.** Type its number (for example `1` for `cs`).
+2. **Pick one or more subdomains.** Type numbers such as `8` or `8,23`, or type `0` for the whole domain. You can also type arXiv codes directly (`cs.CV cs.LG`).
+3. **Pick a mode.** `1` shows today's announcement. `2` shows papers submitted in the last N days, and asks for N.
+
+### 2. Command-line flags
+
+Pass `-c` with one or more codes to skip the prompts:
+
+```bash
+arxivscanner -c cs.CV                          # today's Computer Vision list
+arxivscanner -c cs.CV --type new               # only brand-new submissions (no cross-lists or updates)
+arxivscanner -c cs.CV cs.LG --short            # two subdomains, abstracts trimmed
+arxivscanner -c cs                             # the whole Computer Science domain
+arxivscanner -c cs.CV --mode recent --days 3   # everything submitted in the last 3 days
+arxivscanner -c cs.CV --md cv.md --json cv.json   # also save the results to files
+arxivscanner --from-file saved_feed.xml        # parse a previously saved RSS/API XML file offline
+```
+
+| Flag | Meaning | Default |
+|---|---|---|
+| `-c, --cats CODE …` | Domain(s) or subdomain(s), such as `cs.CV cs.LG`, `cs` or `quant-ph`. Leave it out to get the interactive picker. | — |
+| `--mode today\|recent` | `today` is today's announcement (RSS). `recent` is everything submitted in the last `--days` days (API). | `today` |
+| `--days N` | Window size for `--mode recent`, in whole UTC days, including today. | `3` |
+| `--max N` | Maximum number of papers for `--mode recent`. | `500` |
+| `--type T …` | Keep only these announcement types (today mode): `new`, `cross`, `replace`, `replace-cross`. | all |
+| `--short` | Trim each abstract to about 300 characters. | off |
+| `--json FILE` | Also save the results as JSON (all fields plus the abs and PDF URLs). | — |
+| `--md FILE` | Also save the results as a Markdown reading list. | — |
+| `--from-file XML` | Parse a saved RSS or API XML file instead of fetching. | — |
+| `--list` | Print every built-in domain and subdomain, then exit. | — |
+| `--no-color` | Plain output, for example when piping to a file. `NO_COLOR` is also respected. | — |
+| `--version` | Show the version. | — |
+
+### Which mode should I use?
+
+| Mode | Source | Answers | Notes |
+|---|---|---|---|
+| `today` (default) | `rss.arxiv.org/rss/<cats>` | "What did arXiv announce today?" | Matches arXiv's daily "new" listing. Each paper is tagged `new`, `cross` (cross-listed from another category), `replace` or `replace-cross` (an updated version of an older paper). |
+| `recent` | `export.arxiv.org/api/query` | "What was submitted in the last N days?" | Filters on submission date (UTC). Also includes author comments (page counts, venue) and journal refs. Capped by `--max`. |
+
+**When is there something new?** arXiv announces Sunday to Thursday at 20:00 US Eastern time, which is about **05:30 IST the next morning**. There are no announcements on Friday or Saturday nights US Eastern, so the Saturday and Sunday (IST) feeds are empty. On those days, use `--mode recent --days 3`. `cs.CV` usually has 150–300 papers per announcement.
+
+### Example output
+
+```
+arXiv · cs.CV (Computer Vision and Pattern Recognition)
+Announcement: Mon, 28 Sep 2026 00:00:00 -0400
+3 papers  new: 1  cross: 1  replace: 1
+
+  1. 2609.00001v1 [new]
+     Sample Paper A: Looped Vision Transformers for Fine-Grained Recognition
+     Alice Author, Bob Builder, Chandra Kumar
+     cs.CV, cs.LG · 2026-09-28
+     We study looped vision transformers and show strong results on fine-grained benchmarks.
+     https://arxiv.org/abs/2609.00001  https://arxiv.org/pdf/2609.00001
+```
+
+### Codes
+
+Run `arxivscanner --list` to see all built-in codes. They cover cs, eess, stat, math, q-bio, q-fin, econ, astro-ph, cond-mat, physics, nlin, quant-ph, gr-qc, hep-th and hep-ph. Any other valid arXiv code also works, even if it isn't in the list. Some common ones:
+
+| Code | Subject |
+|---|---|
+| `cs.CV` | Computer Vision and Pattern Recognition |
+| `cs.LG` | Machine Learning |
+| `cs.CL` | Computation and Language (NLP) |
+| `cs.AI` | Artificial Intelligence |
+| `cs.RO` | Robotics |
+| `eess.IV` | Image and Video Processing |
+| `stat.ML` | Machine Learning (Statistics) |
+
+### Rate limiting
+
+The arXiv API sometimes rate-limits in bursts, answering `406` or `429` for a few minutes. The tool retries with back-off for up to about 4 minutes per request and waits 3 seconds between pages, as arXiv's terms ask. If a later page still fails, it keeps the papers it already fetched and prints a warning. If the first request fails, wait a few minutes and run the command again. The RSS feed (`today` mode) is rarely affected.
+
+## Development
+
+```bash
+python -m unittest discover -s tests     # offline tests, using the XML fixtures in tests/fixtures
+python -m build                          # builds dist/arxivscanner-<version>.tar.gz and .whl (pip install build)
+```
+
+The version lives in `arxivscanner/__init__.py` (`__version__`).
+
+## Design
+
+```
+arxivscanner ──► cli.py ──► fetchers.py ──► arXiv (RSS / API)
+             │             │
+             │             └─► models.Paper   (one normalised record)
+             ├─► taxonomy.py  (domain → subdomain names, picker)
+             └─► display.py   (terminal view, JSON / Markdown export)
+```
+
+| Module | Role |
+|---|---|
+| `taxonomy.py` | Built-in map of domains and subdomains, plus the interactive picker. |
+| `models.py` | `Paper` dataclass: id, version, title, authors, abstract, categories, primary category, announce type, dates, comment, journal ref, DOI, abs and PDF URLs. |
+| `fetchers.py` | Two sources, one output type. `fetch_today()` reads the RSS feed. `fetch_recent()` pages through the API. Also handles retries with back-off, the 3 s delay between API calls, de-duplication and type filtering. |
+| `display.py` | Colour terminal output (works in Windows 10+ consoles too) plus `export_json` and `export_markdown`. |
+| `cli.py` | Flags and the interactive picker. `--from-file` parses a saved XML file offline. |
+
+## Roadmap
+
+- **0.1** (current) Fetch, display and export by domain and subdomain.
+- **0.2** Remember papers already seen (a local SQLite or JSON file) so each run shows only unseen papers.
+- **0.3** Keyword or interest filtering and ranking (title and abstract match, later embeddings).
+- **0.4** Daily automation (a scheduled task or cron) and a digest by email, Telegram or HTML.
+- **0.5** Dashboard view with bookmarking.

arxivscanner-0.1.0/README.md

@@ -0,0 +1,146 @@
+# arXiv Scanner
+
+A command-line tool that fetches and shows new arXiv papers for a chosen **domain** (archive, for example `cs`) and **subdomain** (category, for example `cs.CV`).
+
+It uses only the Python standard library, so there is nothing to `pip install`. It needs Python 3.9 or later and runs on Windows, macOS and Linux.
+
+## Installation
+
+Install from GitHub with pip:
+
+```bash
+pip install git+https://github.com/shubham10divakar/arxivscanner.git
+arxivscanner --list        # check it works: prints every known domain and subdomain
+```
+
+This installs an `arxivscanner` command. `python -m arxivscanner …` works the same way. Use `python3 -m pip` on macOS or Linux if `pip` points at an older Python.
+
+To work on the code instead, clone the repo and install it in editable mode:
+
+```bash
+git clone https://github.com/shubham10divakar/arxivscanner.git
+cd arxivscanner
+pip install -e .
+```
+
+Without installing, `python run.py …` from the repo folder also works.
+
+## How to use it
+
+### 1. Interactive mode (easiest)
+
+Run the tool with no arguments and answer the prompts:
+
+```bash
+arxivscanner
+```
+
+1. **Pick a domain.** Type its number (for example `1` for `cs`).
+2. **Pick one or more subdomains.** Type numbers such as `8` or `8,23`, or type `0` for the whole domain. You can also type arXiv codes directly (`cs.CV cs.LG`).
+3. **Pick a mode.** `1` shows today's announcement. `2` shows papers submitted in the last N days, and asks for N.
+
+### 2. Command-line flags
+
+Pass `-c` with one or more codes to skip the prompts:
+
+```bash
+arxivscanner -c cs.CV                          # today's Computer Vision list
+arxivscanner -c cs.CV --type new               # only brand-new submissions (no cross-lists or updates)
+arxivscanner -c cs.CV cs.LG --short            # two subdomains, abstracts trimmed
+arxivscanner -c cs                             # the whole Computer Science domain
+arxivscanner -c cs.CV --mode recent --days 3   # everything submitted in the last 3 days
+arxivscanner -c cs.CV --md cv.md --json cv.json   # also save the results to files
+arxivscanner --from-file saved_feed.xml        # parse a previously saved RSS/API XML file offline
+```
+
+| Flag | Meaning | Default |
+|---|---|---|
+| `-c, --cats CODE …` | Domain(s) or subdomain(s), such as `cs.CV cs.LG`, `cs` or `quant-ph`. Leave it out to get the interactive picker. | — |
+| `--mode today\|recent` | `today` is today's announcement (RSS). `recent` is everything submitted in the last `--days` days (API). | `today` |
+| `--days N` | Window size for `--mode recent`, in whole UTC days, including today. | `3` |
+| `--max N` | Maximum number of papers for `--mode recent`. | `500` |
+| `--type T …` | Keep only these announcement types (today mode): `new`, `cross`, `replace`, `replace-cross`. | all |
+| `--short` | Trim each abstract to about 300 characters. | off |
+| `--json FILE` | Also save the results as JSON (all fields plus the abs and PDF URLs). | — |
+| `--md FILE` | Also save the results as a Markdown reading list. | — |
+| `--from-file XML` | Parse a saved RSS or API XML file instead of fetching. | — |
+| `--list` | Print every built-in domain and subdomain, then exit. | — |
+| `--no-color` | Plain output, for example when piping to a file. `NO_COLOR` is also respected. | — |
+| `--version` | Show the version. | — |
+
+### Which mode should I use?
+
+| Mode | Source | Answers | Notes |
+|---|---|---|---|
+| `today` (default) | `rss.arxiv.org/rss/<cats>` | "What did arXiv announce today?" | Matches arXiv's daily "new" listing. Each paper is tagged `new`, `cross` (cross-listed from another category), `replace` or `replace-cross` (an updated version of an older paper). |
+| `recent` | `export.arxiv.org/api/query` | "What was submitted in the last N days?" | Filters on submission date (UTC). Also includes author comments (page counts, venue) and journal refs. Capped by `--max`. |
+
+**When is there something new?** arXiv announces Sunday to Thursday at 20:00 US Eastern time, which is about **05:30 IST the next morning**. There are no announcements on Friday or Saturday nights US Eastern, so the Saturday and Sunday (IST) feeds are empty. On those days, use `--mode recent --days 3`. `cs.CV` usually has 150–300 papers per announcement.
+
+### Example output
+
+```
+arXiv · cs.CV (Computer Vision and Pattern Recognition)
+Announcement: Mon, 28 Sep 2026 00:00:00 -0400
+3 papers  new: 1  cross: 1  replace: 1
+
+  1. 2609.00001v1 [new]
+     Sample Paper A: Looped Vision Transformers for Fine-Grained Recognition
+     Alice Author, Bob Builder, Chandra Kumar
+     cs.CV, cs.LG · 2026-09-28
+     We study looped vision transformers and show strong results on fine-grained benchmarks.
+     https://arxiv.org/abs/2609.00001  https://arxiv.org/pdf/2609.00001
+```
+
+### Codes
+
+Run `arxivscanner --list` to see all built-in codes. They cover cs, eess, stat, math, q-bio, q-fin, econ, astro-ph, cond-mat, physics, nlin, quant-ph, gr-qc, hep-th and hep-ph. Any other valid arXiv code also works, even if it isn't in the list. Some common ones:
+
+| Code | Subject |
+|---|---|
+| `cs.CV` | Computer Vision and Pattern Recognition |
+| `cs.LG` | Machine Learning |
+| `cs.CL` | Computation and Language (NLP) |
+| `cs.AI` | Artificial Intelligence |
+| `cs.RO` | Robotics |
+| `eess.IV` | Image and Video Processing |
+| `stat.ML` | Machine Learning (Statistics) |
+
+### Rate limiting
+
+The arXiv API sometimes rate-limits in bursts, answering `406` or `429` for a few minutes. The tool retries with back-off for up to about 4 minutes per request and waits 3 seconds between pages, as arXiv's terms ask. If a later page still fails, it keeps the papers it already fetched and prints a warning. If the first request fails, wait a few minutes and run the command again. The RSS feed (`today` mode) is rarely affected.
+
+## Development
+
+```bash
+python -m unittest discover -s tests     # offline tests, using the XML fixtures in tests/fixtures
+python -m build                          # builds dist/arxivscanner-<version>.tar.gz and .whl (pip install build)
+```
+
+The version lives in `arxivscanner/__init__.py` (`__version__`).
+
+## Design
+
+```
+arxivscanner ──► cli.py ──► fetchers.py ──► arXiv (RSS / API)
+             │             │
+             │             └─► models.Paper   (one normalised record)
+             ├─► taxonomy.py  (domain → subdomain names, picker)
+             └─► display.py   (terminal view, JSON / Markdown export)
+```
+
+| Module | Role |
+|---|---|
+| `taxonomy.py` | Built-in map of domains and subdomains, plus the interactive picker. |
+| `models.py` | `Paper` dataclass: id, version, title, authors, abstract, categories, primary category, announce type, dates, comment, journal ref, DOI, abs and PDF URLs. |
+| `fetchers.py` | Two sources, one output type. `fetch_today()` reads the RSS feed. `fetch_recent()` pages through the API. Also handles retries with back-off, the 3 s delay between API calls, de-duplication and type filtering. |
+| `display.py` | Colour terminal output (works in Windows 10+ consoles too) plus `export_json` and `export_markdown`. |
+| `cli.py` | Flags and the interactive picker. `--from-file` parses a saved XML file offline. |
+
+## Roadmap
+
+- **0.1** (current) Fetch, display and export by domain and subdomain.
+- **0.2** Remember papers already seen (a local SQLite or JSON file) so each run shows only unseen papers.
+- **0.3** Keyword or interest filtering and ranking (title and abstract match, later embeddings).
+- **0.4** Daily automation (a scheduled task or cron) and a digest by email, Telegram or HTML.
+- **0.5** Dashboard view with bookmarking.

arxivscanner-0.1.0/arxivscanner/__init__.py

@@ -0,0 +1,3 @@
+"""arXiv Scanner: fetch and display new arXiv papers for a domain / subdomain."""
+
+__version__ = "0.1.0"

arxivscanner-0.1.0/arxivscanner/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

arxivscanner-0.1.0/arxivscanner/cli.py

@@ -0,0 +1,101 @@
+"""Command-line entry point and interactive picker."""
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+from typing import List, Optional
+
+from . import __version__, display, taxonomy
+from .fetchers import ANNOUNCE_TYPES, FetchError, fetch_recent, fetch_today, filter_types, parse_file
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="arxivscanner",
+        description="Fetch and display new arXiv papers for a domain (e.g. cs) or subdomain (e.g. cs.CV).",
+    )
+    p.add_argument("-c", "--cats", nargs="+", metavar="CODE",
+                   help="domain(s) or subdomain(s), e.g. cs.CV cs.LG or cs. Omit for the interactive picker.")
+    p.add_argument("--mode", choices=("today", "recent"), default="today",
+                   help="today = today's announcement (RSS, default); recent = submitted in the last N days (API)")
+    p.add_argument("--days", type=int, default=3, help="window for --mode recent (default 3)")
+    p.add_argument("--max", type=int, default=500, dest="max_results",
+                   help="cap on papers for --mode recent (default 500)")
+    p.add_argument("--type", nargs="+", choices=ANNOUNCE_TYPES, dest="types",
+                   help="keep only these announce types (today mode), e.g. --type new cross")
+    p.add_argument("--short", action="store_true", help="trim abstracts")
+    p.add_argument("--json", metavar="FILE", help="also save results as JSON")
+    p.add_argument("--md", metavar="FILE", help="also save results as Markdown")
+    p.add_argument("--from-file", metavar="XML", help="parse a saved RSS/API XML file instead of fetching")
+    p.add_argument("--list", action="store_true", help="show known domains and subdomains, then exit")
+    p.add_argument("--no-color", action="store_true", help="disable colour output")
+    p.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    return p
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    args = build_parser().parse_args(argv)
+    display.setup_output(color=False if args.no_color else None)
+
+    if args.list:
+        print(taxonomy.format_listing())
+        return 0
+
+    try:
+        if args.from_file:
+            papers, meta = parse_file(Path(args.from_file).read_bytes())
+            cats = args.cats or sorted({p.primary_category for p in papers if p.primary_category})
+            mode = "today" if "pub_date" in meta else "file"
+        else:
+            cats, mode, days = _resolve_target(args)
+            bad = [cat for cat in cats if not taxonomy.is_valid_code(cat)]
+            if bad:
+                print(f"Not a valid arXiv code: {', '.join(bad)} (try --list)", file=sys.stderr)
+                return 2
+            if mode == "today":
+                print(f"Fetching today's announcement for {' + '.join(cats)} …", file=sys.stderr)
+                papers, meta = fetch_today(cats)
+            else:
+                if args.days < 1:
+                    print("--days must be at least 1", file=sys.stderr)
+                    return 2
+                print(f"Querying the arXiv API for {' + '.join(cats)}, last {days} day(s) …", file=sys.stderr)
+                papers, meta = fetch_recent(cats, days=days, max_results=args.max_results)
+    except (KeyboardInterrupt, EOFError):
+        print("\nCancelled.", file=sys.stderr)
+        return 130
+    except (FetchError, OSError) as e:
+        print(f"Error: {e}", file=sys.stderr)
+        return 1
+
+    if args.types:
+        papers = filter_types(papers, set(args.types))
+
+    display.print_header(cats, mode, meta, papers)
+    if not papers:
+        if mode == "today":
+            print("No papers in this feed. arXiv does not announce on Friday/Saturday nights (US Eastern),\n"
+                  "so weekend feeds are empty; try --mode recent --days 3.")
+        else:
+            print("No papers found.")
+        return 0
+    display.print_papers(papers, short=args.short)
+
+    title = f"arXiv {' + '.join(cats)} — {meta.get('pub_date') or meta.get('end', '')[:10] or mode}"
+    if args.json:
+        display.export_json(papers, args.json, meta={**meta, "categories": cats, "mode": mode})
+        print(f"Saved JSON → {args.json}", file=sys.stderr)
+    if args.md:
+        display.export_markdown(papers, args.md, title=title)
+        print(f"Saved Markdown → {args.md}", file=sys.stderr)
+    return 0
+
+
+def _resolve_target(args: argparse.Namespace):
+    if args.cats:
+        return args.cats, args.mode, args.days
+    cats = taxonomy.pick_categories()
+    mode, days = taxonomy.pick_mode()
+    print()
+    return cats, mode, days

arxivscanner-0.1.0/arxivscanner/display.py

@@ -0,0 +1,133 @@
+"""Colour terminal output plus JSON / Markdown export."""
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import sys
+import textwrap
+from collections import Counter
+from pathlib import Path
+from typing import List, Optional, Sequence
+
+from .models import Paper
+from .taxonomy import describe
+
+_COLORS = {
+    "bold": "1", "dim": "2", "red": "31", "green": "32", "yellow": "33",
+    "blue": "34", "magenta": "35", "cyan": "36",
+}
+TYPE_COLOR = {"new": "green", "cross": "cyan", "replace": "yellow", "replace-cross": "magenta"}
+
+_use_color = False
+
+
+def _enable_windows_vt() -> bool:
+    """Turn on ANSI escape handling in Windows 10+ consoles."""
+    try:
+        import ctypes
+        kernel32 = ctypes.windll.kernel32
+        handle = kernel32.GetStdHandle(-11)  # STD_OUTPUT_HANDLE
+        mode = ctypes.c_uint32()
+        if not kernel32.GetConsoleMode(handle, ctypes.byref(mode)):
+            return False
+        return bool(kernel32.SetConsoleMode(handle, mode.value | 0x0004))  # ENABLE_VIRTUAL_TERMINAL_PROCESSING
+    except Exception:
+        return False
+
+
+def setup_output(color: Optional[bool] = None) -> None:
+    """Make stdout UTF-8 safe and decide whether to use colour."""
+    global _use_color
+    for stream in (sys.stdout, sys.stderr):
+        try:
+            stream.reconfigure(encoding="utf-8", errors="replace")
+        except (AttributeError, ValueError):
+            pass
+    if color is None:
+        color = sys.stdout.isatty() and "NO_COLOR" not in os.environ
+    if color and os.name == "nt":
+        color = _enable_windows_vt()
+    _use_color = bool(color)
+
+
+def c(text: str, *styles: str) -> str:
+    if not _use_color or not styles:
+        return text
+    codes = ";".join(_COLORS[s] for s in styles)
+    return f"\033[{codes}m{text}\033[0m"
+
+
+def _width() -> int:
+    return max(60, min(shutil.get_terminal_size((100, 24)).columns, 120))
+
+
+def _authors(authors: Sequence[str], limit: int = 6) -> str:
+    if len(authors) <= limit:
+        return ", ".join(authors)
+    return ", ".join(authors[:limit]) + f", … (+{len(authors) - limit})"
+
+
+def print_header(cats: Sequence[str], mode: str, meta: dict, papers: List[Paper]) -> None:
+    names = ", ".join(f"{cat} ({describe(cat)})" if describe(cat) else cat for cat in cats)
+    print(c(f"arXiv · {names}", "bold"))
+    if mode == "today":
+        when = meta.get("pub_date") or "unknown date"
+        print(c(f"Announcement: {when}", "dim"))
+    elif mode == "recent":
+        print(c(f"Submitted {meta.get('start', '')[:10]} → {meta.get('end', '')[:10]} (UTC); "
+                f"{meta.get('total', 0)} matched on arXiv", "dim"))
+    if meta.get("warning"):
+        print(c(f"Warning: {meta['warning']}", "yellow"))
+    counts = Counter(p.announce_type for p in papers if p.announce_type)
+    summary = "  ".join(c(f"{k}: {v}", TYPE_COLOR.get(k, "bold")) for k, v in counts.most_common())
+    print(f"{len(papers)} papers  {summary}\n")
+
+
+def print_papers(papers: List[Paper], short: bool = False) -> None:
+    w = _width()
+    for i, p in enumerate(papers, 1):
+        tag = f"[{p.announce_type}]" if p.announce_type else ""
+        head = f"{i:>3}. {p.arxiv_id}{p.version} "
+        print(c(head, "bold") + c(tag, TYPE_COLOR.get(p.announce_type, "dim")))
+        indent = "     "
+        for line in textwrap.wrap(p.title, w - len(indent)):
+            print(indent + c(line, "bold", "blue"))
+        if p.authors:
+            print(textwrap.fill(_authors(p.authors), w, initial_indent=indent, subsequent_indent=indent))
+        meta = [", ".join(p.categories)]
+        if p.published:
+            meta.append(p.published[:10])
+        if p.comment:
+            meta.append(p.comment)
+        print(indent + c(textwrap.shorten(" · ".join(meta), w * 2 - len(indent), placeholder=" …"), "dim"))
+        if p.abstract:
+            abstract = textwrap.shorten(p.abstract, 300, placeholder=" …") if short else p.abstract
+            print(textwrap.fill(abstract, w, initial_indent=indent, subsequent_indent=indent))
+        print(indent + c(p.abs_url, "cyan") + "  " + c(p.pdf_url, "dim"))
+        print()
+
+
+def export_json(papers: List[Paper], path: str, meta: Optional[dict] = None) -> None:
+    doc = {"meta": meta or {}, "count": len(papers), "papers": [p.to_dict() for p in papers]}
+    Path(path).write_text(json.dumps(doc, ensure_ascii=False, indent=2), encoding="utf-8")
+
+
+def export_markdown(papers: List[Paper], path: str, title: str = "arXiv papers") -> None:
+    out = [f"# {title}", "", f"{len(papers)} papers", ""]
+    for i, p in enumerate(papers, 1):
+        tag = f" `{p.announce_type}`" if p.announce_type else ""
+        out.append(f"## {i}. {p.title}")
+        out.append("")
+        out.append(f"[{p.arxiv_id}{p.version}]({p.abs_url}) · [PDF]({p.pdf_url}){tag} · {', '.join(p.categories)}")
+        out.append("")
+        if p.authors:
+            out.append(f"*{', '.join(p.authors)}*")
+            out.append("")
+        if p.comment:
+            out.append(f"> {p.comment}")
+            out.append("")
+        if p.abstract:
+            out.append(p.abstract)
+            out.append("")
+    Path(path).write_text("\n".join(out), encoding="utf-8")