FeedTrail

Feed Tracking and Retrieval Abstraction Interface Layer.

feedtrail provides a resilient RSS/Atom parser focused on production-style feeds where XML can be noisy, partially malformed, or inconsistent across publishers.

Repository: https://github.com/juanmcristobal/feedtrail

What It Does

• Parses RSS and Atom feeds with namespace support.
• Normalizes and cleans feed/item text content.
• Converts heterogeneous date formats to UTC ISO strings.
• Extracts structured metadata: title, link, description, summary, author, categories, and primary image.
• Computes a deterministic request_hash for parsed payload integrity checks.
• Handles malformed XML defensively (entity sanitization, escaped CDATA recovery, trailing content trimming).

Installation

pip install feedtrail

Command Line

feedtrail reads XML from standard input and prints normalized JSON to standard output. The example below uses crawlsmith to fetch the feed content.

crawlsmith fetch https://example.com/feed.xml | jq -r ".content" | feedtrail

If you need relative URLs resolved, pass a base URL:

feedtrail --base-url https://example.com < feed.xml

Quick Start

from feedtrail.feed_parser import FeedParser

xml_content = """<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0">
  <channel>
    <title>Example Feed</title>
    <link>https://example.com</link>
    <description>Demo</description>
    <item>
      <title>Hello</title>
      <link>/hello</link>
      <pubDate>Wed, 20 Mar 2024 09:00:00 GMT</pubDate>
      <description><![CDATA[Post body]]></description>
    </item>
  </channel>
</rss>"""

parser = FeedParser()
result = parser.parse(xml_content, base_url="https://example.com")

print(result["headers"]["title"])
print(result["items"][0]["link"])

Output Contract

FeedParser.parse(...) returns a dictionary with:

• headers: feed-level metadata (title, link, description, updated, language, generator, parent_link, self_link).
• items: list of normalized entries, each including:
  • title
  • link
  • description
  • summary
  • pub_date (ISO-like UTC string, when available)
  • author
  • image
  • categories
• request_hash: SHA-256 hash of normalized parsed payload.
• error: present when parsing fails (items will be empty in that case).

Support & Connect

• ⭐ Star the repo if you found it useful
• ☕ Support me: Say thanks by buying me a coffee! https://buymeacoffee.com/juanmcristobal
• 💼 Open to work: https://www.linkedin.com/in/jmcristobal/

Author

• Juan Manuel Cristóbal Moreno (juanmcristobal@gmail.com)

See AUTHORS.md for contributors.

History

0.3.1 (2026-06-30)

• Added a feedtrail command-line entry point for parsing XML from standard input.
• Added support for parsing byte-string XML content.
• Documented command-line usage with a generic feed URL and linked crawlsmith.

0.1.0 (2026-03-25)

• First release.