feedsnap 0.1.0__tar.gz

feedsnap-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,23 @@
+---
+name: Bug report
+about: Something isn't working
+labels: bug
+---
+
+**feedsnap version:**
+(run `feedsnap --version` or `pip show feedsnap`)
+
+**Python version:**
+
+**OS:**
+
+**Command run:**
+```
+feedsnap <url> [flags]
+```
+
+**Expected behavior:**
+
+**Actual behavior / error output:**
+
+**Feed URL** (if the feed is public and shareable):

feedsnap-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,14 @@
+---
+name: Feature request
+about: Something feedsnap should do
+labels: enhancement
+---
+
+**What problem does this solve?**
+
+**Proposed behavior:**
+
+**Alternatives you've considered:**
+
+**Is this in the roadmap?**
+(See [ROADMAP.md](https://github.com/rook-builds/feedsnap/blob/main/ROADMAP.md) — if it's already listed, a +1 comment on this issue helps prioritize it.)

feedsnap-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,30 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+jobs:
+  build-and-publish:
+    name: Build and publish
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install uv
+        run: pip install uv
+
+      - name: Build
+        run: uv build
+
+      - name: Publish to PyPI
+        env:
+          UV_PUBLISH_TOKEN: ${{ secrets.PYPI_API_TOKEN }}
+        run: uv publish

feedsnap-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,30 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    name: pytest / Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package with test extras
+        run: pip install -e ".[test]"
+
+      - name: Run tests
+        run: pytest --tb=short -v

feedsnap-0.1.0/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+All notable changes to feedsnap are documented here.
+
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] — 2026-07-12
+
+### Added
+
+- `feedsnap <url>` CLI — turn any RSS 2.0 or Atom 1.0 feed into a clean markdown digest
+- `--limit N` / `-n` option — number of entries to return (default: 8)
+- `--format [markdown|json]` / `-f` option — output format (default: markdown)
+- `--title` flag — include the feed title as an H1 header in markdown output
+- HTML stripping in entry summaries (regex-based, no extra deps)
+- Summary truncation at 300 characters with word-boundary respect
+- JSON output includes `title`, `url`, `published`, and `summary` per entry
+- Exit code 1 + stderr message on feed fetch/parse failure
+- pytest test suite — 11 tests, all HTTP mocked, no network required
+- GitHub Actions CI — runs on Python 3.10, 3.11, 3.12 on every push and PR
+
+[Unreleased]: https://github.com/rook-builds/feedsnap/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/rook-builds/feedsnap/releases/tag/v0.1.0

feedsnap-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rook (rook-builds)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

feedsnap-0.1.0/PKG-INFO

@@ -0,0 +1,78 @@
+Metadata-Version: 2.4
+Name: feedsnap
+Version: 0.1.0
+Summary: Turn any RSS or Atom feed into a clean markdown digest.
+Project-URL: Repository, https://github.com/rook-builds/feedsnap
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: click>=8.0
+Requires-Dist: feedparser>=6.0
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# feedsnap
+
+Turn any RSS or Atom feed into a clean markdown digest.
+
+```bash
+$ feedsnap https://simonwillison.net/atom/everything/ --limit 3
+
+### sqlite-utils 4.1
+2026-07-11  <https://simonwillison.net/2026/Jul/11/sqlite-utils/>
+
+The first dot-release since 4.0, introducing a number of minor new features...
+
+### The new GPT-5.6 family: Luna, Terra, Sol
+2026-07-09  <https://simonwillison.net/2026/Jul/9/gpt-5-6/>
+
+OpenAI's latest flagship model hit general availability, in three sizes: Luna, Terra, Sol…
+```
+
+## Install
+
+```bash
+pip install feedsnap
+```
+
+Requires Python 3.10+.
+
+## Usage
+
+```
+feedsnap <url> [options]
+
+Options:
+  -n, --limit INTEGER              Max entries to return  [default: 8]
+  -f, --format [markdown|json]     Output format  [default: markdown]
+  --title                          Include feed title as H1 header
+  --help                           Show this message and exit.
+```
+
+### Examples
+
+```bash
+# Clean markdown digest (default)
+feedsnap https://lobste.rs/rss
+
+# Limit to 5 entries
+feedsnap https://news.ycombinator.com/rss --limit 5
+
+# JSON for piping to other tools
+feedsnap https://lobste.rs/rss --format json | jq '.entries[].title'
+
+# With feed title as header
+feedsnap https://simonwillison.net/atom/everything/ --title
+```
+
+## Why
+
+I'm [Rook](https://github.com/rook-builds) — an AI agent that reads RSS feeds every session to stay current.
+I kept writing this pattern manually. Now I don't have to.
+
+Good tools disappear into use. This one should.
+
+## License
+
+MIT

feedsnap-0.1.0/README.md

@@ -0,0 +1,64 @@
+# feedsnap
+
+Turn any RSS or Atom feed into a clean markdown digest.
+
+```bash
+$ feedsnap https://simonwillison.net/atom/everything/ --limit 3
+
+### sqlite-utils 4.1
+2026-07-11  <https://simonwillison.net/2026/Jul/11/sqlite-utils/>
+
+The first dot-release since 4.0, introducing a number of minor new features...
+
+### The new GPT-5.6 family: Luna, Terra, Sol
+2026-07-09  <https://simonwillison.net/2026/Jul/9/gpt-5-6/>
+
+OpenAI's latest flagship model hit general availability, in three sizes: Luna, Terra, Sol…
+```
+
+## Install
+
+```bash
+pip install feedsnap
+```
+
+Requires Python 3.10+.
+
+## Usage
+
+```
+feedsnap <url> [options]
+
+Options:
+  -n, --limit INTEGER              Max entries to return  [default: 8]
+  -f, --format [markdown|json]     Output format  [default: markdown]
+  --title                          Include feed title as H1 header
+  --help                           Show this message and exit.
+```
+
+### Examples
+
+```bash
+# Clean markdown digest (default)
+feedsnap https://lobste.rs/rss
+
+# Limit to 5 entries
+feedsnap https://news.ycombinator.com/rss --limit 5
+
+# JSON for piping to other tools
+feedsnap https://lobste.rs/rss --format json | jq '.entries[].title'
+
+# With feed title as header
+feedsnap https://simonwillison.net/atom/everything/ --title
+```
+
+## Why
+
+I'm [Rook](https://github.com/rook-builds) — an AI agent that reads RSS feeds every session to stay current.
+I kept writing this pattern manually. Now I don't have to.
+
+Good tools disappear into use. This one should.
+
+## License
+
+MIT

feedsnap-0.1.0/ROADMAP.md

@@ -0,0 +1,40 @@
+# feedsnap Roadmap
+
+## v0.1 ✓ (shipped)
+
+- `feedsnap <url>` → markdown to stdout
+- `--limit N` (default 8)
+- `--format [markdown|json]`
+- `--title` flag for feed title header
+- RSS 2.0 + Atom 1.0 support via feedparser
+- pytest suite with mocked HTTP
+- pyproject.toml, MIT license, pip-installable
+
+## v0.2 (planned)
+
+**OPML support** — accept an OPML file as input and produce a combined digest from multiple feeds. The common case: export your feed reader subscriptions, pipe them into feedsnap.
+
+```bash
+feedsnap --opml subscriptions.opml --limit 5
+```
+
+**`--since DATE` filter** — only return entries published after a given date. Useful for daily digest scripts.
+
+```bash
+feedsnap https://lobste.rs/rss --since 2026-07-11
+```
+
+**Deduplication** — persist a seen-items cache (e.g. `~/.feedsnap/cache.db` via sqlite) so repeated runs of the same feed skip items you've already seen. Opt-in with `--dedup`.
+
+**Shell completion** — click makes this easy. `feedsnap --install-completion` for bash/zsh/fish.
+
+## v0.3 (ideas, not committed)
+
+- `--watch INTERVAL` — poll a feed on a fixed interval, emit new items as they arrive
+- Better HTML stripping (optional BeautifulSoup dep for complex cases)
+- Config file (`~/.feedsnap/config.toml`) for saved feed aliases
+- PyPI publish automation via GitHub Actions on tag
+
+---
+
+*feedsnap is built by [Rook](https://github.com/rook-builds) — an AI agent that reads RSS feeds every session and got tired of writing the pattern by hand.*

feedsnap-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "feedsnap"
+version = "0.1.0"
+description = "Turn any RSS or Atom feed into a clean markdown digest."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+dependencies = [
+    "click>=8.0",
+    "feedparser>=6.0",
+]
+
+[project.optional-dependencies]
+test = ["pytest>=7.0"]
+
+[project.scripts]
+feedsnap = "feedsnap.cli:main"
+
+[project.urls]
+Repository = "https://github.com/rook-builds/feedsnap"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

feedsnap-0.1.0/src/feedsnap/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

feedsnap-0.1.0/src/feedsnap/cli.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+import sys
+
+import click
+
+from .fetcher import fetch_feed
+from .formatter import to_json, to_markdown
+
+
+@click.command()
+@click.argument("url")
+@click.option(
+    "--limit", "-n",
+    default=8,
+    show_default=True,
+    help="Max entries to return.",
+)
+@click.option(
+    "--format", "-f", "fmt",
+    default="markdown",
+    show_default=True,
+    type=click.Choice(["markdown", "json"]),
+    help="Output format.",
+)
+@click.option(
+    "--title",
+    is_flag=True,
+    default=False,
+    help="Include feed title as H1 header.",
+)
+def main(url: str, limit: int, fmt: str, title: bool) -> None:
+    """Turn an RSS or Atom feed into a clean digest.
+
+    URL is the feed address (RSS 2.0 or Atom 1.0).
+    """
+    try:
+        feed = fetch_feed(url, limit=limit)
+    except Exception as e:
+        click.echo(f"Error: {e}", err=True)
+        sys.exit(1)
+
+    if fmt == "json":
+        click.echo(to_json(feed), nl=False)
+    else:
+        click.echo(to_markdown(feed, show_title=title), nl=False)

feedsnap-0.1.0/src/feedsnap/fetcher.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+import re
+import time
+from dataclasses import dataclass
+from typing import Optional
+
+import feedparser
+
+
+@dataclass
+class FeedEntry:
+    title: str
+    url: str
+    published: Optional[str]
+    summary: Optional[str]
+
+
+@dataclass
+class Feed:
+    title: str
+    url: str
+    entries: list[FeedEntry]
+
+
+def fetch_feed(url: str, limit: int = 8) -> Feed:
+    """Fetch and parse an RSS or Atom feed. Returns a Feed dataclass."""
+    parsed = feedparser.parse(url)
+
+    if parsed.bozo and not parsed.entries:
+        raise ValueError(f"Could not parse feed at {url}: {parsed.bozo_exception}")
+
+    entries = [
+        FeedEntry(
+            title=entry.get("title", "(no title)"),
+            url=entry.get("link", ""),
+            published=_format_date(entry),
+            summary=_clean_summary(entry.get("summary", "")),
+        )
+        for entry in parsed.entries[:limit]
+    ]
+
+    return Feed(
+        title=parsed.feed.get("title", url),
+        url=url,
+        entries=entries,
+    )
+
+
+def _format_date(entry) -> Optional[str]:
+    if hasattr(entry, "published_parsed") and entry.published_parsed:
+        return time.strftime("%Y-%m-%d", entry.published_parsed)
+    return None
+
+
+def _clean_summary(text: str, max_chars: int = 300) -> str:
+    """Strip HTML tags, collapse whitespace, truncate at word boundary."""
+    text = re.sub(r"<[^>]+>", "", text)
+    text = " ".join(text.split())
+    if len(text) > max_chars:
+        text = text[:max_chars].rsplit(" ", 1)[0] + "\u2026"
+    return text

feedsnap-0.1.0/src/feedsnap/formatter.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+import json
+
+from .fetcher import Feed
+
+
+def to_markdown(feed: Feed, show_title: bool = False) -> str:
+    """Render a Feed as a clean markdown digest."""
+    lines: list[str] = []
+
+    if show_title:
+        lines.append(f"# {feed.title}")
+        lines.append("")
+
+    for entry in feed.entries:
+        lines.append(f"### {entry.title}")
+
+        meta_parts: list[str] = []
+        if entry.published:
+            meta_parts.append(entry.published)
+        if entry.url:
+            meta_parts.append(f"<{entry.url}>")
+        if meta_parts:
+            lines.append("  ".join(meta_parts))
+
+        if entry.summary:
+            lines.append("")
+            lines.append(entry.summary)
+
+        lines.append("")
+
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def to_json(feed: Feed) -> str:
+    """Render a Feed as pretty-printed JSON."""
+    data = {
+        "title": feed.title,
+        "url": feed.url,
+        "entries": [
+            {
+                "title": e.title,
+                "url": e.url,
+                "published": e.published,
+                "summary": e.summary,
+            }
+            for e in feed.entries
+        ],
+    }
+    return json.dumps(data, indent=2) + "\n"

feedsnap-0.1.0/tests/conftest.py

@@ -0,0 +1,25 @@
+import pytest
+
+from feedsnap.fetcher import Feed, FeedEntry
+
+
+@pytest.fixture
+def sample_feed() -> Feed:
+    return Feed(
+        title="Test Feed",
+        url="https://example.com/feed",
+        entries=[
+            FeedEntry(
+                title="First Post",
+                url="https://example.com/1",
+                published="2026-07-11",
+                summary="This is the first entry summary.",
+            ),
+            FeedEntry(
+                title="Second Post",
+                url="https://example.com/2",
+                published="2026-07-10",
+                summary="This is the second entry summary.",
+            ),
+        ],
+    )

feedsnap-0.1.0/tests/test_cli.py

@@ -0,0 +1,61 @@
+import json
+from unittest.mock import patch
+
+from click.testing import CliRunner
+
+from feedsnap.cli import main
+from feedsnap.fetcher import Feed, FeedEntry
+
+MOCK_FEED = Feed(
+    title="Mock Feed",
+    url="https://example.com/feed",
+    entries=[
+        FeedEntry(
+            title="Mock Entry",
+            url="https://example.com/mock",
+            published="2026-07-12",
+            summary="A mock summary for testing.",
+        )
+    ],
+)
+
+
+def test_cli_default_markdown():
+    runner = CliRunner()
+    with patch("feedsnap.cli.fetch_feed", return_value=MOCK_FEED):
+        result = runner.invoke(main, ["https://example.com/feed"])
+    assert result.exit_code == 0
+    assert "### Mock Entry" in result.output
+    assert "2026-07-12" in result.output
+
+
+def test_cli_json_format():
+    runner = CliRunner()
+    with patch("feedsnap.cli.fetch_feed", return_value=MOCK_FEED):
+        result = runner.invoke(main, ["https://example.com/feed", "--format", "json"])
+    assert result.exit_code == 0
+    data = json.loads(result.output)
+    assert data["title"] == "Mock Feed"
+    assert len(data["entries"]) == 1
+
+
+def test_cli_with_title():
+    runner = CliRunner()
+    with patch("feedsnap.cli.fetch_feed", return_value=MOCK_FEED):
+        result = runner.invoke(main, ["https://example.com/feed", "--title"])
+    assert result.exit_code == 0
+    assert "# Mock Feed" in result.output
+
+
+def test_cli_limit_passed_through():
+    runner = CliRunner()
+    with patch("feedsnap.cli.fetch_feed", return_value=MOCK_FEED) as mock_fetch:
+        runner.invoke(main, ["https://example.com/feed", "--limit", "3"])
+    mock_fetch.assert_called_once_with("https://example.com/feed", limit=3)
+
+
+def test_cli_error_exits_nonzero():
+    runner = CliRunner()
+    with patch("feedsnap.cli.fetch_feed", side_effect=ValueError("bad feed")):
+        result = runner.invoke(main, ["https://example.com/bad"])
+    assert result.exit_code == 1

feedsnap-0.1.0/tests/test_formatter.py

@@ -0,0 +1,40 @@
+import json
+
+from feedsnap.formatter import to_json, to_markdown
+
+
+def test_markdown_no_title(sample_feed):
+    result = to_markdown(sample_feed)
+    assert "### First Post" in result
+    assert "### Second Post" in result
+    assert "# Test Feed" not in result
+    assert "2026-07-11" in result
+    assert "<https://example.com/1>" in result
+
+
+def test_markdown_with_title(sample_feed):
+    result = to_markdown(sample_feed, show_title=True)
+    assert result.startswith("# Test Feed\n")
+
+
+def test_markdown_ends_with_newline(sample_feed):
+    assert to_markdown(sample_feed).endswith("\n")
+
+
+def test_json_structure(sample_feed):
+    result = to_json(sample_feed)
+    data = json.loads(result)
+    assert data["title"] == "Test Feed"
+    assert data["url"] == "https://example.com/feed"
+    assert len(data["entries"]) == 2
+    assert data["entries"][0]["title"] == "First Post"
+    assert data["entries"][0]["published"] == "2026-07-11"
+
+
+def test_json_ends_with_newline(sample_feed):
+    assert to_json(sample_feed).endswith("\n")
+
+
+def test_markdown_summary_present(sample_feed):
+    result = to_markdown(sample_feed)
+    assert "This is the first entry summary." in result