Feed Generator (ATOM, RSS, Podcasts)

Common errors

• ValueError: unconverted data remains: ' GMT'

  cause Attempting to set a date string that `dateutil.parser` (used internally by feedgen) cannot fully parse, often due to non-standard format or trailing text.
  fix Ensure date strings are in a standard format (e.g., ISO 8601) and include timezone information, or pass a `datetime.datetime` object with `tzinfo` set.

• XML Syntax Error: Entity '...' not defined

  cause Special characters like `&`, `<`, `>` are not properly escaped in the feed content, violating XML rules.
  fix Let `feedgen` handle content by passing plain strings to `fe.content()` or `fe.fe.summary()`. It will automatically escape these characters. Avoid manually constructing XML snippets within content fields.

• Feed reader shows old items or fetches repeatedly.

  cause This usually indicates missing or incorrect `pubDate`/`lastBuildDate` with timezone information, leading the reader to believe content is new or its update status is ambiguous.
  fix Verify that `fg.lastBuildDate()` and `fe.published()`/`fe.updated()` are always set with timezone-aware `datetime` objects, preferably UTC, e.g., `datetime.datetime.now(datetime.timezone.utc)`.

Warnings

• breaking Version 1.0.0 removed official support for Python 2. While older versions might work, Python 2 is no longer tested or maintained.
  Fix: Ensure your project runs on Python 3.x. Upgrade your Python environment if necessary.
• gotcha Date and time fields (`pubDate`, `lastBuildDate`, `published`, `updated`) *must* include timezone information for proper parsing by feed readers. Without it, readers may incorrectly interpret dates (e.g., as future dates) or repeatedly fetch content.
  Fix: Always provide timezone-aware datetime objects, e.g., `datetime.datetime.now(datetime.timezone.utc)` or use `dateutil.parser.parse('2023-01-01T12:00:00+00:00')`.
• gotcha RSS feeds require a `guid` (Global Unique Identifier) for each entry to uniquely identify it. While `feedgen` provides a `guid()` method, ensure the value is truly unique and consistent for the item across feed updates. For items that are not permalinks, set `isPermaLink=False`.
  Fix: Use `fe.guid('your-unique-id-string', isPermaLink=False)` if the ID is not a permanent URL to the item. The ID should be unique to the content, not necessarily the URL.
• gotcha Improperly formatted XML can lead to feed validation errors or prevent feed readers from parsing your content. This often happens with special characters in content or missing required fields.
  Fix: Always use `feedgen`'s methods for setting content (`fe.content()`, `fe.summary()`) which handle escaping. Validate your generated feed using online validators (e.g., W3C Feed Validator).

Install

• pip install feedgen Install stable version

Imports

• FeedGenerator

  from feedgen.feed import FeedGenerator

• FeedEntry

  from feedgen.entry import FeedEntry

Quickstart

This quickstart demonstrates how to create a basic RSS feed (and optionally ATOM) with a few entries using `FeedGenerator`. It includes setting global feed properties like ID, title, author, and links, and then adding individual entries with their own metadata. Date fields are set with timezone information, which is crucial for proper feed parsing. Finally, it shows how to generate the feed as a pretty-printed string.

from feedgen.feed import FeedGenerator
import datetime

fg = FeedGenerator()
fg.id('http://example.com/pages/1')
fg.title('My Example Feed')
fg.author({'name': 'John Doe', 'email': 'john.doe@example.com'})
fg.link(href='http://example.com', rel='alternate')
fg.link(href='http://example.com/feed.xml', rel='self')
fg.language('en')
fg.description('A fantastic example feed generated by feedgen.')
fg.lastBuildDate(datetime.datetime.now(datetime.timezone.utc))

# Add an entry
fe = fg.add_entry()
fe.id('http://example.com/pages/1/article1')
fe.title('First Article Title')
fe.link(href='http://example.com/articles/1')
fe.published(datetime.datetime(2023, 1, 10, 10, 0, 0, tzinfo=datetime.timezone.utc))
fe.updated(datetime.datetime(2023, 1, 15, 12, 30, 0, tzinfo=datetime.timezone.utc))
fe.summary('This is a summary of the first article.')
fe.content('This is the full content of the first article, potentially with <b>HTML</b>.')
fe.author({'name': 'Jane Doe', 'email': 'jane.doe@example.com'})

# Add another entry
fe2 = fg.add_entry()
fe2.id('http://example.com/pages/1/article2')
fe2.title('Second Article Title')
fe2.link(href='http://example.com/articles/2')
fe2.published(datetime.datetime(2023, 2, 1, 9, 0, 0, tzinfo=datetime.timezone.utc))
fe2.updated(datetime.datetime(2023, 2, 5, 11, 45, 0, tzinfo=datetime.timezone.utc))
fe2.summary('Summary of the second article.')

# Generate and print the RSS feed
print(fg.rss_str(pretty=True).decode('utf-8'))

# Generate and print the ATOM feed
# print(fg.atom_str(pretty=True).decode('utf-8'))