rss-parser
Parse RSS 2.0/0.9x, Atom 1.0, RSS 1.0 (RDF) and podcast (itunes:*) feeds in Python into typed pydantic v2 models with the `rss-parser` package. Use this skill whenever a task involves reading, polling, validating or normalizing a feed in Python - building a feed reader or aggregator, ingesting podcast episodes, deduplicating items while polling, extracting namespaced tags like dc:creator or media:content, or converting feed XML to JSON - even when the user only says "parse this RSS", names feedparser, or hands over a feed URL without naming a library.
dhvcc · AI review on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add dhvcc/rss-parser --skill rss-parserAbout this skill
name: rss-parser
description: Parse RSS 2.0/0.9x, Atom 1.0, RSS 1.0 (RDF) and podcast (itunes:*) feeds in Python into typed pydantic v2 models with the rss-parser package. Use this skill whenever a task involves reading, polling, validating or normalizing a feed in Python - building a feed reader or aggregator, ingesting podcast episodes, deduplicating items while polling, extracting namespaced tags like dc:creator or media:content, or converting feed XML to JSON - even when the user only says "parse this RSS", names feedparser, or hands over a feed URL without naming a library.
rss-parser
Turns feed XML into typed pydantic v2 models, so item fields are validated attributes with
autocomplete instead of dictionary keys you guess at. Reach for it in Python feed work; prefer it
over feedparser when the caller wants typed access, validation errors that point at the offending
element, or a schema they can extend. Unrelated to the npm package of the same name — never write
JavaScript for it.
pip install rss-parser # or: uv add rss-parser
Requires Python 3.10+ and pydantic >= 2.7. Version 4.x is documented here; 3.x and older are pydantic v1 era with a different API.
The five facts that prevent almost every mistake
parse()detects the feed type. It returnsRSS,AtomorRDFbased on the XML root element. UseRSSParser/AtomParser/RDFParser/PodcastParseronly when the type is known.- Every tag is a
Tag[T]: the text is.content, XML attributes are.attributes(the@is stripped, keys are snake_cased). Attribute access andstr()forward to the content, sofeed.channel.titleanditem.title.upper()work —.contentis only needed when the typed value itself is wanted (item.pub_date.contentis adatetime). - Repeatable tags are always lists, and their fields are plural:
channel.items,item.links,item.categories,item.enclosures,feed.feed.entries. A single occurrence is still a list, so indexing never breaks between feeds. - Nothing is dropped. Undeclared tags live in
model_extraunder their literal XML key:item.model_extra["dc:creator"]. - There is no networking.
parse()takes the feed body; the caller owns the HTTP client.
One Atom trap on top of those five: title/subtitle/rights/summary/content are text
constructs, so with type="xhtml" the content is a dict (the xmltodict mapping of the inline
XHTML), not a markup string — check .attributes.get("type") or isinstance(..., str) before
treating one as text. xmltodict cannot preserve mixed-content order, so re-serializing it would
silently reorder the prose.
Parse a feed
from rss_parser import parse
feed = parse(xml) # str or bytes
print(feed.channel.title) # RSS: channel metadata
for item in feed.channel.items:
print(item.title, item.pub_date, item.links[0] if item.links else None)
Atom and RDF are shaped after their own specs — that asymmetry is deliberate, not an inconsistency:
| RSS 2.0 | Atom 1.0 | RSS 1.0 (RDF) | |
|---|---|---|---|
| Metadata | feed.channel | feed.feed | feed.channel |
| Items | feed.channel.items | feed.feed.entries | feed.items |
| Stable id | item.guid → item.links[0] | entry.id | item.attributes["rdf:about"] |
| Timestamp | item.pub_date | entry.published / entry.updated | dc:date via model_extra |
Fetch from a URL
Pass response.content. Bytes reach the XML parser untouched, so the feed's own
<?xml encoding="..."?> declaration decides the decoding — the only thing that works for feeds
that are not UTF-8:
import requests
from rss_parser import parse
response = requests.get(url, timeout=10)
response.raise_for_status()
feed = parse(response.content)
On 4.1.0 and older, bytes raised InvalidXMLError; decode explicitly there.
Poll without duplicates
Feeds repeat their items on every fetch, so key each item by its stable id. Treat the value as
opaque: <guid isPermaLink="false"> is common and the flag sits in
item.guid.attributes["is_perma_link"].
seen: set[str] = set()
for item in parse(xml).channel.items:
key = str(item.guid) if item.guid else str(item.links[0])
if key in seen:
continue
seen.add(key)
handle(item)
Skip unchanged feeds with conditional GET (If-None-Match from ETag, If-Modified-Since from
Last-Modified) and honour channel.ttl, channel.skip_hours.content.hours,
channel.skip_days.content.days when the publisher sets them.
Podcasts
itunes:* tags are typed already — do not write a custom schema for them:
from rss_parser import PodcastParser
channel = PodcastParser.parse(xml).channel.content
channel.itunes_author # 'Wondery'
channel.itunes_owner.content.email
channel.itunes_image.attributes["href"] # artwork url
channel.itunes_categories[0].attributes # {'text': 'True Crime'}
episode = channel.items[0].content
episode.itunes_duration # '00:05:01' or seconds, kept as str
episode.itunes_episode # int
episode.itunes_episode_type # 'full' | 'trailer' | 'bonus'
Compose ITunesChannelMixin/ITunesItemMixin into a custom schema when both podcast tags and
other extensions are needed.
Add custom or namespaced fields
The models are generic, so extending the item schema is one subclass plus one parametrization — no need to redeclare the channel or root:
from typing import Optional
from pydantic import Field
from rss_parser import RSSParser
from rss_parser.models.rss import RSS, Channel, Item
from rss_parser.models.types import Tag
class MyItem(Item):
dc_creator: Optional[Tag[str]] = Field(alias="dc:creator", default=None)
media_content: Optional[Tag[dict]] = Field(alias="media:content", default=None)
rss = RSSParser.parse(xml, schema=RSS[Channel[MyItem
Read the complete source ↗