rss-parser

Typed, pydantic-powered RSS/Atom parsing for Python.

rss-parser turns RSS/Atom XML into typed pydantic models — autocomplete, validation, and clear errors instead of digging through nested dicts.

Documentation

At a glance

Installation

pip install rss-parser

Quickstart

from rss_parser import parse
from requests import get  # noqa

rss_url = "https://rss.art19.com/apology-line"
response = get(rss_url)

feed = parse(response.text)  # detects RSS 2.0 / 0.9x, Atom 1.0 or RSS 1.0 (RDF)

print("Language", feed.channel.language)
print("RSS", feed.version)

for item in feed.channel.items:
    print(item.title)
    print(str(item.description)[:50])

# Language en
# RSS 2.0
# Wondery Presents - Flipping The Bird: Elon vs Twitter
# <p>When Elon Musk posted a video of himself arrivi
# Introducing: The Apology Line
# <p>If you could call a number and say you’re sorry

parse() picks the right parser from the XML root element and raises UnknownFeedTypeError if the document is not a feed. If you already know the feed type, use the explicit parsers: RSSParser, AtomParser, RDFParser, PodcastParser.

Podcasts

itunes:* tags are supported out of the box, fully typed:

from rss_parser import PodcastParser

podcast = PodcastParser.parse(feed_xml)
channel = podcast.channel.content

channel.itunes_author                    # 'Wondery'
channel.itunes_owner.content.email       # 'iwonder@wondery.com'
channel.itunes_image.attributes["href"]  # artwork url

episode = channel.items[0].content
episode.itunes_duration                  # '00:05:01'
episode.itunes_episode_type              # 'trailer'

Custom fields: one subclass away

The models are generic, so extending the schema doesn't require re-declaring the whole tree:

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)


rss = RSSParser.parse(data, schema=RSS[Channel[MyItem]])

rss.channel.items[0].content.dc_creator

And even without a custom schema, unknown tags are never dropped — they're kept in model_extra:

rss = RSSParser.parse(podcast_xml)
rss.channel.content.model_extra["itunes:author"]  # 'Wondery'

See Customizing the schema for mixins, repeatable tags, and the field types cheat sheet.

Migrating from 3.x

4.0 removes the legacy pydantic v1 models, fixes several RSS 2.0 spec violations, and makes the models generic and lossless. See the migration guide for the full list.

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Install dependencies with uv sync (install uv).

Using pre-commit is highly recommended. To install hooks, run:

uv run pre-commit install -t=pre-commit -t=pre-push

See Contributing for tests, snapshots, and docs.

License

GPLv3