DOCSEARCHbyAlgolia
Submit Docs

python-feedgen

repository·main·Indexed 20 days ago

https://github.com/lkiesow/python-feedgen

A Python module used to generate web feeds in ATOM and RSS formats. It features a FeedGenerator for feed-level metadata and a FeedEntry class for individual items. The library includes a plugin-like extension system to handle specialized feed types, such as Podcasts, and provides methods to output feeds as strings or files.

Tokens
2.9K
Snippets
15
Records
15
Agent score
24%

What's inside feedgen

  1. How extensions work in FeedGenerator

    main

    Extensions allow you to include additional data in the XML structure (e.g., Podcast metadata).

    Loading Extensions

    Use fg.load_extension(name, atom=True, rss=True) to load an extension. This looks for a file named {name}.py and expects a class named {Name}Extension (e.g., someext looks for SomextExtension). It also attempts to load a {Name}EntryExtension for individual entries.

    • atom and rss flags (default True) control whether the extension applies to those formats.
    • You can load an extension for a specific FeedEntry by calling load_extension(...) on the entry object.
    • To temporarily disable all extensions during generation, call the generation method with extensions=False (e.g., fg.rss_str(extensions=False)).

    Custom Extensions

    If your extension classes are already defined in your code, use register_extension(feed_ext_class, entry_ext_class) instead of loading from a file.

    # Loading from a file
fg.load_extension('someext', atom=True, rss=True)

# Using a custom class directly
fg.register_extension(MyFeedExtension, MyEntryExtension)

  3. Example: Producing a Podcast feed

    main

    To create a podcast, load the built-in podcast extension. This provides access to iTunes-specific metadata via the fg.podcast attribute and allows for enclosure tags in entries.

    from feedgen.feed import FeedGenerator

fg = FeedGenerator()
fg.load_extension('podcast')

# Configure podcast metadata
fg.podcast.itunes_category('Technology', 'Podcasting')

# Add an entry with an enclosure
fe = fg.add_entry()
fe.id('http://lernfunk.de/media/654321/1/file.mp3')
fe.title('The First Episode')
fe.description('Enjoy our first episode.')
fe.enclosure('http://lernfunk.de/media/654321/1/file.mp3', 0, 'audio/mpeg')

fg.rss_file('podcast.xml')

  4. Add entries to a feed

    main

    Use the FeedGenerator.add_entry() method to create a new FeedEntry object. This method automatically appends the entry to the feed's internal list and returns the entry object, allowing you to chain configuration calls like id(), title(), and link().

    fe = fg.add_entry()
fe.id('http://lernfunk.de/media/654321/1/')
fe.title('The First Episode')
fe.link(href="http://lernfunk.de/feed")

  5. Generate ATOM or RSS feeds

    main

    Once the feed and its entries are configured, you can generate the output as a string or write it directly to a file using the following methods:

    • atom_str(pretty=True): Returns the ATOM feed as a string.
    • rss_str(pretty=True): Returns the RSS feed as a string.
    • atom_file('filename.xml'): Writes the ATOM feed to a file.
    • rss_file('filename.xml'): Writes the RSS feed to a file.
    atomfeed = fg.atom_str(pretty=True) # Get the ATOM feed as string
rssfeed  = fg.rss_str(pretty=True) # Get the RSS feed as string
fg.atom_file('atom.xml') # Write the ATOM feed to a file
fg.rss_file('rss.xml') # Write the RSS feed to a file

  6. Create and configure a FeedGenerator

    main

    To create a feed, instantiate the FeedGenerator class. You can set feed-level metadata such as id, title, author, link, logo, subtitle, language, and more.

    For fields that can occur multiple times (like contributor), you can provide data using:

    • Keyword arguments
    • A dictionary
    • A list of dictionaries
    from feedgen.feed import FeedGenerator

fg = FeedGenerator()
fg.id('http://lernfunk.de/media/654321')
fg.title('Some Testfeed')
fg.author({'name':'John Doe','email':'john@example.de'})
fg.link(href='http://example.com', rel='alternate')
fg.logo('http://ex.com/logo.jpg')
fg.subtitle('This is a cool feed!')
fg.link(href='http://larskiesow.de/test.atom', rel='self')
fg.language('en')

# Multiple contributors example
fg.contributor(name='John Doe', email='jdoe@example.com')
fg.contributor({'name':'John Doe', 'email':'jdoe@example.com'})
fg.contributor([{'name':'John Doe', 'email':'jdoe@example.com'}, {'name':'Jane Doe', 'email':'jane@example.com'}])

  7. Set entry content and summary

    main

    Manage the main body and short excerpts of the entry:

    • content(content=None, src=None, type=None): Sets the main content. If src is provided, the content is treated as linked (external). If content is provided, it is embedded. Supported types include xhtml, CDATA, and XML types (e.g., text/xml).
    • summary(summary=None, type=None): Sets an ATOM summary. This also sets the RSS description if it wasn't already set.
    • description(description=None, isSummary=False): An RSS-specific method. If isSummary=True, it sets the ATOM summary. Otherwise, it sets the ATOM content.
    entry.content('Full content here', type='xhtml')
entry.summary('A short summary')
entry.description('RSS description')

  8. Set entry categories

    main

    Use category() to add categorization metadata. A category can have a term (mandatory), a scheme (URI for the categorization scheme), and a label (human-readable label).

    entry.category(term='technology', label='Tech News', scheme='http://example.com/tags')

  10. Set entry publication and update dates

    main

    Use published() or updated() to set timestamps. Values can be datetime.datetime objects or strings that can be parsed by dateutil. Note: Datetime objects must include timezone information.

    • published(published=None): Sets the initial creation time. Also sets pubDate for RSS.
    • pubDate(pubDate=None): Alias for published(). Use this instead of the deprecated pubdate().
    • updated(updated=None): Sets the last time the entry was significantly modified.
    from datetime import datetime, timezone

entry.published(datetime.now(timezone.utc))
entry.updated(datetime.now(timezone.utc))

  11. Set the entry ID or GUID

    main

    Use id() or guid() to uniquely identify an entry.

    • id(id=None): Sets the ATOM id and the RSS guid (with isPermaLink set to False). This is mandatory for ATOM entries.
    • guid(guid=None, permalink=False): Sets both the ATOM id and the RSS guid. Use permalink=True if the identifier is a permanent URI.
    entry.id('https://example.com/unique-id')
# OR
entry.guid('https://example.com/unique-id', permalink=True)

  12. Set entry links and enclosures

    main

    Manage links and media attachments:

    • link(link=None, replace=False, **kwargs): Sets link data. Fields include href (mandatory), rel (default is alternate), type, hreflang, title, and length. For RSS, only the last link with rel='alternate' is used as the primary link, and the last link with rel='enclosure' is used as the enclosure.
    • enclosure(url=None, length=None, type=None): Specifically sets a media enclosure. This is represented as a link with rel='enclosure' in ATOM.
    entry.link(href='https://example.com', rel='alternate', title='Main Link')
entry.enclosure(url='https://example.com/audio.mp3', length='12345', type='audio/mpeg')