PYFEEDGEN.TEX(1) python-feedgen PYFEEDGEN.TEX(1)

pyFeedGen.tex - pyFeedGen Documentation

•
Feedgenerator
  • Installation
  • Create a Feed
  • Generate the Feed
  • Add Feed Entries
  • Extensions
  • Testing the Generator
  • Module documentation
  • Indices and tables

This module can be used to generate web feeds in both ATOM and RSS format. It has support for extensions. Included is for example an extension to produce Podcasts.

It is licensed under the terms of both, the FreeBSD license and the LGPLv3+. Choose the one which is more convenient for you. For more details have a look at license.bsd and license.lgpl.

More details about the project:

  • Repository
  • Documentation
  • Python Package Index

Prebuild packages

If your distribution includes this project as package, like Fedora Linux does, you can simply use your package manager to install the package. For example:

$ dnf install python3-feedgen

Using pip

You can also use pip to install the feedgen module. Simply run:

$ pip install feedgen

To create a feed simply instantiate the FeedGenerator class and insert some data:

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')

Note that for the methods which set fields that can occur more than once in a feed you can use all of the following ways to provide data:

  • Provide the data for that element as keyword arguments
  • Provide the data for that element as dictionary
  • Provide a list of dictionaries with the data for several elements

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'}, ...])

After that you can generate both RSS or ATOM by calling the respective method:

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

To add entries (items) to a feed you need to create new FeedEntry objects and append them to the list of entries in the FeedGenerator. The most convenient way to go is to use the FeedGenerator itself for the instantiation of the FeedEntry object:

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

The FeedGenerator's method add_entry(...) will generate a new FeedEntry object, automatically append it to the feeds internal list of entries and return it, so that additional data can be added.

The FeedGenerator supports extensions to include additional data into the XML structure of the feeds. Extensions can be loaded like this:

fg.load_extension('someext', atom=True, rss=True)

This example would try to load the extension “someext” from the file ext/someext.py. It is required that someext.py contains a class named “SomextExtension” which is required to have at least the two methods extend_rss(...) and extend_atom(...). Although not required, it is strongly suggested to use BaseExtension from ext/base.py as superclass.

load_extension('someext', ...) will also try to load a class named “SomextEntryExtension” for every entry of the feed. This class can be located either in the same file as SomextExtension or in ext/someext_entry.py which is suggested especially for large extensions.

The parameters atom and rss control if the extension is used for ATOM and RSS feeds respectively. The default value for both parameters is True, meaning the extension is used for both kinds of feeds.

Example: Producing a Podcast

One extension already provided is the podcast extension. A podcast is an RSS feed with some additional elements for ITunes.

To produce a podcast simply load the podcast extension:

from feedgen.feed import FeedGenerator
fg = FeedGenerator()
fg.load_extension('podcast')
...
fg.podcast.itunes_category('Technology', 'Podcasting')
...
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_str(pretty=True)
fg.rss_file('podcast.xml')

If the FeedGenerator class is used to load an extension, it is automatically loaded for every feed entry as well. You can, however, load an extension for a specific FeedEntry only by calling load_extension(...) on that entry.

Even if extensions are loaded, they can be temporarily disabled during the feed generation by calling the generating method with the keyword argument extensions set to False.

Custom Extensions

If you want to load custom extensions which are not part of the feedgen package, you can use the method register_extension instead. You can directly pass the classes for the feed and the entry extension to this method meaning that you can define them everywhere.

You can test the module by simply executing:

$ python -m feedgen

If you want to have a look at the code for this test to have a working code example for a whole feed generation process, you can find it in the __main__.py.

This module can be used to generate web feeds in both ATOM and RSS format. It has support for extensions. Included is for example an extension to produce Podcasts.

2013 by Lars Kiesow
FreeBSD and LGPL, see license.* for more details.

To create a feed simply instantiate the FeedGenerator class and insert some data:

>>> 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')

Note that for the methods which set fields that can occur more than once in a feed you can use all of the following ways to provide data:

  • Provide the data for that element as keyword arguments
  • Provide the data for that element as dictionary
  • Provide a list of dictionaries with the data for several elements

Example:

>>> fg.contributor(name='John Doe', email='jdoe@example.com' )
>>> fg.contributor({'name':'John Doe', 'email':'jdoe@example.com'})
>>> fg.contributor([{'name':'John', 'email':'jdoe@example.com'}, …])

After that you can generate both RSS or ATOM by calling the respective method:

>>> 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

To add entries (items) to a feed you need to create new FeedEntry objects and append them to the list of entries in the FeedGenerator. The most convenient way to do this, is to call the method add_entry(...) like this:

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

The FeedGenerator's method add_entry(...) will automatically create a new FeedEntry object, append it to the feeds internal list of entries and return it, so that additional data can be added.

The FeedGenerator supports extension to include additional data into the XML structure of the feeds. Extensions can be loaded like this:

>>> fg.load_extension('someext', atom=True, rss=True)

This will try to load the extension “someext” from the file ext/someext.py. It is required that someext.py contains a class named “SomextExtension” which is required to have at least the two methods extend_rss(...) and extend_atom(...). Although not required, it is strongly suggested to use BaseExtension from ext/base.py as superclass.

load_extension('someext', ...) will also try to load a class named “SomextEntryExtension” for every entry of the feed. This class can be located either in the same file as SomextExtension or in ext/someext_entry.py which is suggested especially for large extensions.

The parameters atom and rss tell the FeedGenerator if the extensions should only be used for either ATOM or RSS feeds. The default value for both parameters is true which means that the extension would be used for both kinds of feeds.

Example: Producing a Podcast

One extension already provided is the podcast extension. A podcast is an RSS feed with some additional elements for ITunes.

To produce a podcast simply load the podcast extension:

>>> from feedgen.feed import FeedGenerator
>>> fg = FeedGenerator()
>>> fg.load_extension('podcast')
...
>>> fg.podcast.itunes_category('Technology', 'Podcasting')
...
>>> fg.rss_str(pretty=True)
>>> fg.rss_file('podcast.xml')

Of cause the extension has to be loaded for the FeedEntry objects as well but this is done automatically by the FeedGenerator for every feed entry if the extension is loaded for the whole feed. You can, however, load an extension for a specific FeedEntry by calling load_extension(...) on that entry. But this is a rather uncommon use.

Of cause you can still produce a normal ATOM or RSS feed, even if you have loaded some plugins by temporary disabling them during the feed generation. This can be done by calling the generating method with the keyword argument extensions set to False.

You can test the module by simply executing:

$ python -m feedgen

Contents:

2013-2020, Lars Kiesow <lkiesow@uos.de>
FreeBSD and LGPL, see license.* for more details.
FeedGenerator for generating ATOM and RSS feeds.
This method will add a new entry to the feed. If the feedEntry argument is omitted a new Entry object is created automatically. This is the preferred way to add new entries to a feed.
  • feedEntry -- FeedEntry object to add.
  • order -- If prepend is chosen, the entry will be inserted at the beginning of the feed. If append is chosen, the entry will be appended to the feed. (default: prepend).
FeedEntry object created or passed to this function.

Example:

...
>>> entry = feedgen.add_entry()
>>> entry.title('First feed entry')
This method will add a new item to the feed. If the item argument is omitted a new FeedEntry object is created automatically. This is just another name for add_entry(...)
Generates an ATOM feed and write the resulting XML to a file.
  • filename -- Name of file to write or a file-like object or a URL.
  • extensions -- Enable or disable the loaded extensions for the xml generation (default: enabled).
  • pretty -- If the feed should be split into multiple lines and properly indented.
  • encoding -- Encoding used in the XML file (default: UTF-8).
  • xml_declaration -- If an XML declaration should be added to the output (Default: enabled).
Generates an ATOM feed and returns the feed XML as string.
  • pretty -- If the feed should be split into multiple lines and properly indented.
  • extensions -- Enable or disable the loaded extensions for the xml generation (default: enabled).
  • encoding -- Encoding used in the XML file (default: UTF-8).
  • xml_declaration -- If an XML declaration should be added to the output (Default: enabled).
String representation of the ATOM feed.

Return type: The return type may vary between different Python versions and your encoding parameters passed to this method. For details have a look at the lxml documentation

Get or set author data. An author element is a dictionary containing a name, an email address and a URI. Name is mandatory for ATOM, email is mandatory for RSS.

This method can be called with:

  • the fields of an author as keyword arguments
  • the fields of an author as a dictionary
  • a list of dictionaries containing the author fields

An author has the following fields:

  • name conveys a human-readable name for the person.
  • uri contains a home page for the person.
  • email contains an email address for the person.
  • author -- Dictionary or list of dictionaries with author data.
  • replace -- Add or replace old data.
List of authors as dictionaries.

Example:

>>> feedgen.author({'name':'John Doe', 'email':'jdoe@example.com'})
[{'name':'John Doe','email':'jdoe@example.com'}]
>>> feedgen.author([{'name':'Mr. X'},{'name':'Max'}])
[{'name':'John Doe','email':'jdoe@example.com'},
        {'name':'John Doe'}, {'name':'Max'}]
>>> feedgen.author(name='John Doe', email='jdoe@example.com',
                   replace=True)
[{'name':'John Doe','email':'jdoe@example.com'}]
Get or set categories that the feed belongs to.

This method can be called with:

  • the fields of a category as keyword arguments
  • the fields of a category as a dictionary
  • a list of dictionaries containing the category fields

A categories has the following fields:

  • term identifies the category
  • scheme identifies the categorization scheme via a URI.
  • label provides a human-readable label for display

If a label is present it is used for the RSS feeds. Otherwise the term is used. The scheme is used for the domain attribute in RSS.

  • category -- Dict or list of dicts with data.
  • replace -- Add or replace old data.
List of category data.
Set or get the cloud data of the feed. It is an RSS only attribute. It specifies a web service that supports the rssCloud interface which can be implemented in HTTP-POST, XML-RPC or SOAP 1.1.
  • domain -- The domain where the webservice can be found.
  • port -- The port the webservice listens to.
  • path -- The path of the webservice.
  • registerProcedure -- The procedure to call.
  • protocol -- Can be either HTTP-POST, XML-RPC or SOAP 1.1.
Dictionary containing the cloud data.
Get or set the contributor data of the feed. This is an ATOM only value.

This method can be called with: - the fields of an contributor as keyword arguments - the fields of an contributor as a dictionary - a list of dictionaries containing the contributor fields

An contributor has the following fields: - name conveys a human-readable name for the person. - uri contains a home page for the person. - email contains an email address for the person.

  • contributor -- Dictionary or list of dictionaries with contributor data.
  • replace -- Add or replace old data.
List of contributors as dictionaries.
Get or set the copyright notice for content in the channel. This RSS value will also set the atom:rights value.
copyright -- The copyright notice.
The copyright notice.
Set and get the description of the feed. This is an RSS only element which is a phrase or sentence describing the channel. It is mandatory for RSS feeds. It is roughly the same as atom:subtitle. Thus setting this will also set atom:subtitle.
description -- Description of the channel.
Description of the channel.
Get or set the docs value of the feed. This is an RSS only value. It is a URL that points to the documentation for the format used in the RSS file. It is probably a pointer to [1]. It is for people who might stumble across an RSS file on a Web server 25 years from now and wonder what it is.

[1]: http://www.rssboard.org/rss-specification

docs -- URL of the format documentation.
URL of the format documentation.
Get or set feed entries. Use the add_entry() method instead to automatically create the FeedEntry objects.

This method takes both a single FeedEntry object or a list of objects.

entry -- FeedEntry object or list of FeedEntry objects.
List ob all feed entries.
Get or set the generator of the feed which identifies the software used to generate the feed, for debugging and other purposes. Both the uri and version attributes are optional and only available in the ATOM feed.
  • generator -- Software used to create the feed.
  • version -- Version of the software.
  • uri -- URI the software can be found.
Get or set the icon of the feed which is a small image which provides iconic visual identification for the feed. Icons should be square. This is an ATOM only value.
icon -- URI of the feeds icon.
URI of the feeds icon.
Get or set the feed id which identifies the feed using a universally unique and permanent URI. If you have a long-term, renewable lease on your Internet domain name, then you can feel free to use your website's address. This field is for ATOM only. It is mandatory for ATOM.
id -- New Id of the ATOM feed.
Id of the feed.
Set the image of the feed. This element is roughly equivalent to atom:logo.
  • url -- The URL of a GIF, JPEG or PNG image.
  • title -- Describes the image. The default value is the feeds title.
  • link -- URL of the site the image will link to. The default is to use the feeds first alternate link.
  • width -- Width of the image in pixel. The maximum is 144.
  • height -- The height of the image. The maximum is 400.
  • description -- Title of the link.
Data of the image as dictionary.
Get or set feed items. This is just another name for entry(...)
Get or set the language of the feed. It indicates the language the channel is written in. This allows aggregators to group all Italian language sites, for example, on a single page. This is an RSS only field. However, this value will also be used to set the xml:lang property of the ATOM feed node. The value should be an IETF language tag.
language -- Language of the feed.
Language of the feed.
Set or get the lastBuildDate value which indicates the last time the content of the channel changed.

The value can either be a string which will automatically be parsed or a datetime.datetime object. In any case it is necessary that the value include timezone information.

This will set both atom:updated and rss:lastBuildDate.

If not set, lastBuildDate has as value the current date and time.
lastBuildDate -- The modification date.
Modification date as datetime.datetime
Get or set link data. An link element is a dict with the fields href, rel, type, hreflang, title, and length. Href is mandatory for ATOM.

This method can be called with:

  • the fields of a link as keyword arguments
  • the fields of a link as a dictionary
  • a list of dictionaries containing the link fields

A link has the following fields:

  • href is the URI of the referenced resource (typically a Web page)
  • rel contains a single link relationship type. It can be a full URI, or one of the following predefined values (default=alternate):
  • alternate an alternate representation of the entry or feed, for example a permalink to the html version of the entry, or the front page of the weblog.
  • enclosure a related resource which is potentially large in size and might require special handling, for example an audio or video recording.
  • related an document related to the entry or feed.
  • self the feed itself.
  • via the source of the information provided in the entry.
  • type indicates the media type of the resource.
  • hreflang indicates the language of the referenced resource.
  • title human readable information about the link, typically for display purposes.
  • length the length of the resource, in bytes.

RSS only supports one link with URL only.

  • link -- Dict or list of dicts with data.
  • replace -- If old links are to be replaced (default: False)
Current set of link data

Example:

>>> feedgen.link( href='http://example.com/', rel='self')
[{'href':'http://example.com/', 'rel':'self'}]
Load a specific extension by name.
  • name -- Name of the extension to load.
  • atom -- If the extension should be used for ATOM feeds.
  • rss -- If the extension should be used for RSS feeds.
Get or set the logo of the feed which is a larger image which provides visual identification for the feed. Images should be twice as wide as they are tall. This is an ATOM value but will also set the rss:image value.
logo -- Logo of the feed.
Logo of the feed.
Set or get the value for managingEditor which is the email address for person responsible for editorial content. This is a RSS only value.
managingEditor -- Email address of the managing editor.
Email address of the managing editor.
Set or get the publication date for the content in the channel. For example, the New York Times publishes on a daily basis, the publication date flips once every 24 hours. That's when the pubDate of the channel changes.

The value can either be a string which will automatically be parsed or a datetime.datetime object. In any case it is necessary that the value include timezone information.

This will set both atom:updated and rss:lastBuildDate.

pubDate -- The publication date.
Publication date as datetime.datetime
Set and get the PICS rating for the channel. It is an RSS only value.
Registers an extension by class.
  • namespace -- namespace for the extension
  • extension_class_feed -- Class of the feed extension to load.
  • extension_class_entry -- Class of the entry extension to load
  • atom -- If the extension should be used for ATOM feeds.
  • rss -- If the extension should be used for RSS feeds.
Remove a single entry from the feed. This method accepts both the FeedEntry object to remove or the index of the entry as argument.
entry -- Entry or index of entry to remove.
Remove a single item from the feed. This is another name for remove_entry.
Get or set the rights value of the feed which conveys information about rights, e.g. copyrights, held in and over the feed. This ATOM value will also set rss:copyright.
rights -- Rights information of the feed.
Generates an RSS feed and write the resulting XML to a file.
  • filename -- Name of file to write or a file-like object or a URL.
  • extensions -- Enable or disable the loaded extensions for the xml generation (default: enabled).
  • pretty -- If the feed should be split into multiple lines and properly indented.
  • encoding -- Encoding used in the XML file (default: UTF-8).
  • xml_declaration -- If an XML declaration should be added to the output (Default: enabled).
Generates an RSS feed and returns the feed XML as string.
  • pretty -- If the feed should be split into multiple lines and properly indented.
  • extensions -- Enable or disable the loaded extensions for the xml generation (default: enabled).
  • encoding -- Encoding used in the XML file (default: UTF-8).
  • xml_declaration -- If an XML declaration should be added to the output (Default: enabled).
String representation of the RSS feed.

Return type: The return type may vary between different Python versions and your encoding parameters passed to this method. For details have a look at the lxml documentation

Set or get the value of skipDays, a hint for aggregators telling them which days they can skip This is an RSS only value.

This method can be called with a day name or a list of day names. The days are represented as strings from 'Monday' to 'Sunday'.

  • hours -- List of days the feedreaders should not check the feed.
  • replace -- Add or replace old data.
List of days the feedreaders should not check the feed.
Set or get the value of skipHours, a hint for aggregators telling them which hours they can skip. This is an RSS only value.

This method can be called with an hour or a list of hours. The hours are represented as integer values from 0 to 23.

  • hours -- List of hours the feedreaders should not check the feed.
  • replace -- Add or replace old data.
List of hours the feedreaders should not check the feed.
Get or set the subtitle value of the channel which contains a human-readable description or subtitle for the feed. This ATOM property will also set the value for rss:description.
subtitle -- The subtitle of the feed.
The subtitle of the feed.
Get or set the value of textInput. This is an RSS only field. The purpose of the <textInput> element is something of a mystery. You can use it to specify a search engine box. Or to allow a reader to provide feedback. Most aggregators ignore it.
  • title -- The label of the Submit button in the text input area.
  • description -- Explains the text input area.
  • name -- The name of the text object in the text input area.
  • link -- The URL of the CGI script that processes text input requests.
Dictionary containing textInput values.
Get or set the title value of the feed. It should contain a human readable title for the feed. Often the same as the title of the associated website. Title is mandatory for both ATOM and RSS and should not be blank.
title -- The new title of the feed.
The feeds title.
Get or set the ttl value. It is an RSS only element. ttl stands for time to live. It's a number of minutes that indicates how long a channel can be cached before refreshing from the source.
ttl -- Integer value indicating how long the channel may be cached.
Time to live.
Set or get the updated value which indicates the last time the feed was modified in a significant way.

The value can either be a string which will automatically be parsed or a datetime.datetime object. In any case it is necessary that the value include timezone information.

This will set both atom:updated and rss:lastBuildDate.

If not set, updated has as value the current date and time.
updated -- The modification date.
Modification date as datetime.datetime
Get and set the value of webMaster, which represents the email address for the person responsible for technical issues relating to the feed. This is an RSS only value.
webMaster -- Email address of the webmaster.
Email address of the webmaster.

2013-2020, Lars Kiesow <lkiesow@uos.de>
FreeBSD and LGPL, see license.* for more details.
FeedEntry call representing an ATOM feeds entry node or an RSS feeds item node.
Create an ATOM entry and return it.
Get or set author data. An author element is a dict containing a name, an email address and a uri. Name is mandatory for ATOM, email is mandatory for RSS.

This method can be called with: - the fields of an author as keyword arguments - the fields of an author as a dictionary - a list of dictionaries containing the author fields

An author has the following fields: - name conveys a human-readable name for the person. - uri contains a home page for the person. - email contains an email address for the person.

  • author -- Dict or list of dicts with author data.
  • replace -- Add or replace old data.

Example:

>>> author({'name':'John Doe', 'email':'jdoe@example.com'})
[{'name':'John Doe','email':'jdoe@example.com'}]
>>> author([{'name': 'Mr. X'}, {'name': 'Max'}])
[{'name':'John Doe','email':'jdoe@example.com'},
        {'name':'John Doe'}, {'name':'Max'}]
>>> author(name='John Doe', email='jdoe@example.com', replace=True)
[{'name':'John Doe','email':'jdoe@example.com'}]
Get or set categories that the entry belongs to.

This method can be called with: - the fields of a category as keyword arguments - the fields of a category as a dictionary - a list of dictionaries containing the category fields

A categories has the following fields: - term identifies the category - scheme identifies the categorization scheme via a URI. - label provides a human-readable label for display

If a label is present it is used for the RSS feeds. Otherwise the term is used. The scheme is used for the domain attribute in RSS.

  • category -- Dict or list of dicts with data.
  • replace -- Add or replace old data.
List of category data.
Get or set the value of comments which is the URL of the comments page for the item. This is a RSS only value.
comments -- URL to the comments page.
URL to the comments page.
Get or set the content of the entry which contains or links to the complete content of the entry. Content must be provided for ATOM entries if there is no alternate link, and should be provided if there is no summary. If the content is set (not linked) it will also set rss:description.
  • content -- The content of the feed entry.
  • src -- Link to the entries content.
  • type -- If type is CDATA content would not be escaped.
Content element of the entry.
Get or set the contributor data of the feed. This is an ATOM only value.

This method can be called with: - the fields of an contributor as keyword arguments - the fields of an contributor as a dictionary - a list of dictionaries containing the contributor fields

An contributor has the following fields: - name conveys a human-readable name for the person. - uri contains a home page for the person. - email contains an email address for the person.

  • contributor -- Dictionary or list of dictionaries with contributor data.
  • replace -- Add or replace old data.
List of contributors as dictionaries.
Get or set the description value which is the item synopsis. Description is an RSS only element. For ATOM feeds it is split in summary and content. The isSummary parameter can be used to control which ATOM value is set when setting description.
  • description -- Description of the entry.
  • isSummary -- If the description should be used as content or summary.
The entries description.
Get or set the value of enclosure which describes a media object that is attached to the item. This is a RSS only value which is represented by link(rel=enclosure) in ATOM. ATOM feeds can furthermore contain several enclosures while RSS may contain only one. That is why this method, if repeatedly called, will add more than one enclosures to the feed. However, only the last one is used for RSS.
  • url -- URL of the media object.
  • length -- Size of the media in bytes.
  • type -- Mimetype of the linked media.
Data of the enclosure element.
Get or set the entries guid which is a string that uniquely identifies the item. This will also set atom:id.
  • guid -- Id of the entry.
  • permalink -- If this is a permanent identifier for this item
Id and permalink setting of the entry.
Get or set the entry id which identifies the entry using a universally unique and permanent URI. Two entries in a feed can have the same value for id if they represent the same entry at different points in time. This method will also set rss:guid with permalink set to False. Id is mandatory for an ATOM entry.
id -- New Id of the entry.
Id of the entry.
Get or set link data. An link element is a dict with the fields href, rel, type, hreflang, title, and length. Href is mandatory for ATOM.

This method can be called with: - the fields of a link as keyword arguments - the fields of a link as a dictionary - a list of dictionaries containing the link fields

A link has the following fields:

  • href is the URI of the referenced resource (typically a Web page)
  • rel contains a single link relationship type. It can be a full URI, or one of the following predefined values (default=alternate):
  • alternate an alternate representation of the entry or feed, for example a permalink to the html version of the entry, or the front page of the weblog.
  • enclosure a related resource which is potentially large in size and might require special handling, for example an audio or video recording.
  • related an document related to the entry or feed.
  • self the feed itself.
  • via the source of the information provided in the entry.
  • type indicates the media type of the resource.
  • hreflang indicates the language of the referenced resource.
  • title human readable information about the link, typically for display purposes.
  • length the length of the resource, in bytes.

RSS only supports one link with nothing but a URL. So for the RSS link element the last link with rel=alternate is used.

RSS also supports one enclusure element per entry which is covered by the link element in ATOM feed entries. So for the RSS enclusure element the last link with rel=enclosure is used.

  • link -- Dict or list of dicts with data.
  • replace -- Add or replace old data.
List of link data.
Load a specific extension by name.
  • name -- Name of the extension to load.
  • atom -- If the extension should be used for ATOM feeds.
  • rss -- If the extension should be used for RSS feeds.
Get or set the pubDate of the entry which indicates when the entry was published. This method is just another name for the published(...) method.
Get or set the pubDate of the entry which indicates when the entry was published. This method is just another name for the published(...) method.

pubdate(…) is deprecated and may be removed in feedgen ≥ 0.8. Use pubDate(…) instead.

Set or get the published value which contains the time of the initial creation or first availability of the entry.

The value can either be a string which will automatically be parsed or a datetime.datetime object. In any case it is necessary that the value include timezone information.

published -- The creation date.
Creation date as datetime.datetime
Register a specific extension by classes to a namespace.
  • namespace -- namespace for the extension
  • extension_class_entry -- Class of the entry extension to load.
  • atom -- If the extension should be used for ATOM feeds.
  • rss -- If the extension should be used for RSS feeds.
Get or set the rights value of the entry which conveys information about rights, e.g. copyrights, held in and over the entry. This ATOM value will also set rss:copyright.
rights -- Rights information of the feed.
Rights information of the feed.
Create a RSS item and return it.
Get or set the source for the current feed entry.

Note that ATOM feeds support a lot more sub elements than title and URL (which is what RSS supports) but these are currently not supported. Patches are welcome.

  • url -- Link to the source.
  • title -- Title of the linked resource
Source element as dictionaries.
Get or set the summary element of an entry which conveys a short summary, abstract, or excerpt of the entry. Summary is an ATOM only element and should be provided if there either is no content provided for the entry, or that content is not inline (i.e., contains a src attribute), or if the content is encoded in base64. This method will also set the rss:description field if it wasn't previously set or contains the old value of summary.
summary -- Summary of the entries contents.
Summary of the entries contents.
Get or set the title value of the entry. It should contain a human readable title for the entry. Title is mandatory for both ATOM and RSS and should not be blank.
title -- The new title of the entry.
The entriess title.
Get or set the ttl value. It is an RSS only element. ttl stands for time to live. It's a number of minutes that indicates how long a channel can be cached before refreshing from the source.
ttl -- Integer value representing the time to live.
Time to live of of the entry.
Set or get the updated value which indicates the last time the entry was modified in a significant way.

The value can either be a string which will automatically be parsed or a datetime.datetime object. In any case it is necessary that the value include timezone information.

updated -- The modification date.
Modification date as datetime.datetime

This file contains helper functions for the feed generator module.

2013, Lars Kiesow <lkiesow@uos.de>
FreeBSD and LGPL, see license.* for more details.
Takes a dictionary or a list of dictionaries and check if all keys are in the set of allowed keys, if all required keys are present and if the values of a specific key are ok.
  • val -- Dictionaries to check.
  • allowed -- Set of allowed keys.
  • required -- Set of required keys.
  • allowed_values -- Dictionary with keys and sets of their allowed values.
  • defaults -- Dictionary with default values.
List of checked dictionaries.
Make sure the locale setting do not interfere with the time format.

Basic FeedGenerator extension which does nothing but provides all necessary methods.

2013, Lars Kiesow <lkiesow@uos.de>
FreeBSD and LGPL, see license.* for more details.
Basic FeedEntry extension.
Basic FeedGenerator extension.
Extend an ATOM feed xml structure containing all previously set fields.
feed -- The feed xml root element.
The feed root element.
Returns a dict that will be used in the namespace map for the feed.
Extend a RSS feed xml structure containing all previously set fields.
feed -- The feed xml root element.
The feed root element.

Extends the FeedGenerator to add Dubline Core Elements to the feeds.

Descriptions partly taken from http://dublincore.org/documents/dcmi-terms/#elements-coverage

2013-2017, Lars Kiesow <lkiesow@uos.de>
FreeBSD and LGPL, see license.* for more details.
Dublin Core Elements extension for podcasts.
Get or set the dc:contributor which is an entity responsible for making contributions to the resource.

For more information see: http://dublincore.org/documents/dcmi-terms/#elements-contributor

  • contributor -- Contributor or list of contributors.
  • replace -- Replace already set contributors (default: False).
List of contributors.
Get or set the dc:coverage which indicated the spatial or temporal topic of the resource, the spatial applicability of the resource, or the jurisdiction under which the resource is relevant.

Spatial topic and spatial applicability may be a named place or a location specified by its geographic coordinates. Temporal topic may be a named period, date, or date range. A jurisdiction may be a named administrative entity or a geographic place to which the resource applies. Recommended best practice is to use a controlled vocabulary such as the Thesaurus of Geographic Names [TGN]. Where appropriate, named places or time periods can be used in preference to numeric identifiers such as sets of coordinates or date ranges.

References: [TGN] http://www.getty.edu/research/tools/vocabulary/tgn/index.html

  • coverage -- Coverage of the feed.
  • replace -- Replace already set coverage (default: True).
Coverage of the feed.
Get or set the dc:creator which is an entity primarily responsible for making the resource.

For more information see: http://dublincore.org/documents/dcmi-terms/#elements-creator

  • creator -- Creator or list of creators.
  • replace -- Replace already set creators (default: False).
List of creators.
Get or set the dc:date which describes a point or period of time associated with an event in the lifecycle of the resource.

For more information see: http://dublincore.org/documents/dcmi-terms/#elements-date

  • date -- Date or list of dates.
  • replace -- Replace already set dates (default: True).
List of dates.
Get or set the dc:description which is an account of the resource.

For more information see: http://dublincore.org/documents/dcmi-terms/#elements-description

  • description -- Description or list of descriptions.
  • replace -- Replace already set descriptions (default: True).
List of descriptions.
Get or set the dc:format which describes the file format, physical medium, or dimensions of the resource.

For more information see: http://dublincore.org/documents/dcmi-terms/#elements-format

  • format -- Format of the resource or list of formats.
  • replace -- Replace already set format (default: True).
Format of the resource.
Get or set the dc:identifier which should be an unambiguous reference to the resource within a given context.

For more inidentifierion see: http://dublincore.org/documents/dcmi-terms/#elements-identifier

  • identifier -- Identifier of the resource or list of identifiers.
  • replace -- Replace already set identifier (default: True).
Identifiers of the resource.
Get or set the dc:language which describes a language of the resource.

For more information see: http://dublincore.org/documents/dcmi-terms/#elements-language

  • language -- Language or list of languages.
  • replace -- Replace already set languages (default: True).
List of languages.
Get or set the dc:publisher which is an entity responsible for making the resource available.

For more information see: http://dublincore.org/documents/dcmi-terms/#elements-publisher

  • publisher -- Publisher or list of publishers.
  • replace -- Replace already set publishers (default: False).
List of publishers.
Get or set the dc:relation which describes a related resource.

For more information see: http://dublincore.org/documents/dcmi-terms/#elements-relation

  • relation -- Relation or list of relations.
  • replace -- Replace already set relations (default: False).
List of relations.
Get or set the dc:rights which may contain information about rights held in and over the resource.

For more information see: http://dublincore.org/documents/dcmi-terms/#elements-rights

  • rights -- Rights information or list of rights information.
  • replace -- Replace already set rights (default: False).
List of rights information.
Get or set the dc:source which is a related resource from which the described resource is derived.

The described resource may be derived from the related resource in whole or in part. Recommended best practice is to identify the related resource by means of a string conforming to a formal identification system.

For more information see: http://dublincore.org/documents/dcmi-terms/#elements-source

  • source -- Source or list of sources.
  • replace -- Replace already set sources (default: False).
List of sources.
Get or set the dc:subject which describes the topic of the resource.

For more information see: http://dublincore.org/documents/dcmi-terms/#elements-subject

  • subject -- Subject or list of subjects.
  • replace -- Replace already set subjects (default: False).
List of subjects.
Get or set the dc:title which is a name given to the resource.

For more information see: http://dublincore.org/documents/dcmi-terms/#elements-title

  • title -- Title or list of titles.
  • replace -- Replace already set titles (default: False).
List of titles.
Get or set the dc:type which describes the nature or genre of the resource.

For more information see: http://dublincore.org/documents/dcmi-terms/#elements-type

  • type -- Type or list of types.
  • replace -- Replace already set types (default: False).
List of types.
Extend an Atom feed with the set DC fields.
atom_feed -- The feed root element
The feed root element
Returns a dict that will be used in the namespace map for the feed.
Extend a RSS feed with the set DC fields.
rss_feed -- The feed root element
The feed root element.
Dublin Core Elements extension for podcasts.
Add dc elements to an atom item. Alters the item itself.
entry -- An atom entry element.
The entry element.
Add dc elements to a RSS item. Alters the item itself.
item -- A RSS item element.
The item element.
Dublin Core Elements extension for podcasts.

Extends the FeedGenerator to produce podcasts.

2013, Lars Kiesow <lkiesow@uos.de>
FreeBSD and LGPL, see license.* for more details.
FeedGenerator extension for podcasts.
Returns a dict that will be used in the namespace map for the feed.
Extend an RSS feed root with set itunes fields.
The feed root element.
Get or set the itunes:author. The content of this tag is shown in the Artist column in iTunes. If the tag is not present, iTunes uses the contents of the <author> tag. If <itunes:author> is not present at the feed level, iTunes will use the contents of <managingEditor>.
itunes_author -- The author of the podcast.
The author of the podcast.
Get or set the ITunes block attribute. Use this to prevent the entire podcast from appearing in the iTunes podcast directory.
itunes_block -- Block the podcast.
If the podcast is blocked.
Get or set the ITunes category which appears in the category column and in iTunes Store Browser.

The (sub-)category has to be one from the values defined at http://www.apple.com/itunes/podcasts/specs.html#categories

This method can be called with:

  • the fields of an itunes_category as keyword arguments
  • the fields of an itunes_category as a dictionary
  • a list of dictionaries containing the itunes_category fields

An itunes_category has the following fields:

  • cat name for a category.
  • sub name for a subcategory, child of category

If a podcast has more than one subcategory from the same category, the category is called more than once.

Likei the parameter:

[{"cat":"Arts","sub":"Design"},{"cat":"Arts","sub":"Food"}]

…would become:

<itunes:category text="Arts">
    <itunes:category text="Design"/>
    <itunes:category text="Food"/>
</itunes:category>
  • itunes_category -- Dictionary or list of dictionaries with itunes_category data.
  • replace -- Add or replace old data.
List of itunes_categories as dictionaries.

---

Important note about deprecated parameter syntax: Old version of the feedgen did only support one category plus one subcategory which would be passed to this ducntion as first two parameters. For compatibility reasons, this still works but should not be used any may be removed at any time.

Get or set the itunes:complete value of the podcast. This tag can be used to indicate the completion of a podcast.

If you populate this tag with "yes", you are indicating that no more episodes will be added to the podcast. If the <itunes:complete> tag is present and has any other value (e.g. “no”), it will have no effect on the podcast.

itunes_complete -- If the podcast is complete.
If the podcast is complete.
Get or the the itunes:explicit value of the podcast. This tag should be used to indicate whether your podcast contains explicit material. The three values for this tag are "yes", "no", and "clean".

If you populate this tag with "yes", an "explicit" parental advisory graphic will appear next to your podcast artwork on the iTunes Store and in the Name column in iTunes. If the value is "clean", the parental advisory type is considered Clean, meaning that no explicit language or adult content is included anywhere in the episodes, and a "clean" graphic will appear. If the explicit tag is present and has any other value (e.g., "no"), you see no indicator — blank is the default advisory type.

itunes_explicit -- If the podcast contains explicit material.
If the podcast contains explicit material.
Get or set the image for the podcast. This tag specifies the artwork for your podcast. Put the URL to the image in the href attribute. iTunes prefers square .jpg images that are at least 1400x1400 pixels, which is different from what is specified for the standard RSS image tag. In order for a podcast to be eligible for an iTunes Store feature, the accompanying image must be at least 1400x1400 pixels.

iTunes supports images in JPEG and PNG formats with an RGB color space (CMYK is not supported). The URL must end in ".jpg" or ".png". If the <itunes:image> tag is not present, iTunes will use the contents of the RSS image tag.

If you change your podcast’s image, also change the file’s name. iTunes may not change the image if it checks your feed and the image URL is the same. The server hosting your cover art image must allow HTTP head requests for iTS to be able to automatically update your cover art.

itunes_image -- Image of the podcast.
Image of the podcast.
Get or set the new-feed-url property of the podcast. This tag allows you to change the URL where the podcast feed is located

After adding the tag to your old feed, you should maintain the old feed for 48 hours before retiring it. At that point, iTunes will have updated the directory with the new feed URL.

itunes_new_feed_url -- New feed URL.
New feed URL.
Get or set the itunes:owner of the podcast. This tag contains information that will be used to contact the owner of the podcast for communication specifically about the podcast. It will not be publicly displayed.
itunes_owner -- The owner of the feed.
Data of the owner of the feed.
Get or set the itunes:subtitle value for the podcast. The contents of this tag are shown in the Description column in iTunes. The subtitle displays best if it is only a few words long.
itunes_subtitle -- Subtitle of the podcast.
Subtitle of the podcast.
Get or set the itunes:summary value for the podcast. The contents of this tag are shown in a separate window that appears when the "circled i" in the Description column is clicked. It also appears on the iTunes page for your podcast. This field can be up to 4000 characters. If <itunes:summary> is not included, the contents of the <description> tag are used.
itunes_summary -- Summary of the podcast.
Summary of the podcast.
Get or set the itunes:type value of the podcast. This tag should be used to indicate the type of your podcast. The two values for this tag are "episodic" and "serial".

If your show is Serial you must use this tag.

Specify episodic when episodes are intended to be consumed without any specific order. Apple Podcasts will present newest episodes first and display the publish date (required) of each episode. If organized into seasons, the newest season will be presented first - otherwise, episodes will be grouped by year published, newest first.

Specify serial when episodes are intended to be consumed in sequential order. Apple Podcasts will present the oldest episodes first and display the episode numbers (required) of each episode. If organized into seasons, the newest season will be presented first and <itunes:episode> numbers must be given for each episode.
itunes_type -- The type of the podcast
type of the pdocast.

Extends the feedgen to produce podcasts.

2013-2016, Lars Kiesow <lkiesow@uos.de>
FreeBSD and LGPL, see license.* for more details.
FeedEntry extension for podcasts.
Add additional fields to an RSS item.
feed -- The RSS item XML element to use.
Get or set the itunes:author of the podcast episode. The content of this tag is shown in the Artist column in iTunes. If the tag is not present, iTunes uses the contents of the <author> tag. If <itunes:author> is not present at the feed level, iTunes will use the contents of <managingEditor>.
itunes_author -- The author of the podcast.
The author of the podcast.
Get or set the ITunes block attribute. Use this to prevent episodes from appearing in the iTunes podcast directory.
itunes_block -- Block podcast episodes.
If the podcast episode is blocked.
Get or set the duration of the podcast episode. The content of this tag is shown in the Time column in iTunes.

The tag can be formatted HH:MM:SS, H:MM:SS, MM:SS, or M:SS (H = hours, M = minutes, S = seconds). If an integer is provided (no colon present), the value is assumed to be in seconds. If one colon is present, the number to the left is assumed to be minutes, and the number to the right is assumed to be seconds. If more than two colons are present, the numbers farthest to the right are ignored.

itunes_duration -- Duration of the podcast episode.
Duration of the podcast episode.
Get or set the itunes:episode value for the podcast episode.
itunes_season -- Episode number of the podcast epiosode.
Episode number of the podcast episode.
Get or set the itunes:episodeType value of the item. This tag should be used to indicate the episode type. The three values for this tag are "full", "trailer" and "bonus".

If an episode is a trailer or bonus content, use this tag.

Specify full when you are submitting the complete content of your show. Specify trailer when you are submitting a short, promotional piece of content that represents a preview of your current show. Specify bonus when you are submitting extra content for your show (for example, behind the scenes information or interviews with the cast) or cross-promotional content for another show.

itunes_episode_type -- The episode type
type of the episode.
Get or the the itunes:explicit value of the podcast episode. This tag should be used to indicate whether your podcast episode contains explicit material. The three values for this tag are "yes", "no", and "clean".

If you populate this tag with "yes", an "explicit" parental advisory graphic will appear next to your podcast artwork on the iTunes Store and in the Name column in iTunes. If the value is "clean", the parental advisory type is considered Clean, meaning that no explicit language or adult content is included anywhere in the episodes, and a "clean" graphic will appear. If the explicit tag is present and has any other value (e.g., "no"), you see no indicator — blank is the default advisory type.

itunes_explicit -- If the podcast episode contains explicit material.
If the podcast episode contains explicit material.
Get or set the image for the podcast episode. This tag specifies the artwork for your podcast. Put the URL to the image in the href attribute. iTunes prefers square .jpg images that are at least 1400x1400 pixels, which is different from what is specified for the standard RSS image tag. In order for a podcast to be eligible for an iTunes Store feature, the accompanying image must be at least 1400x1400 pixels.

iTunes supports images in JPEG and PNG formats with an RGB color space (CMYK is not supported). The URL must end in ".jpg" or ".png". If the <itunes:image> tag is not present, iTunes will use the contents of the RSS image tag.

If you change your podcast’s image, also change the file’s name. iTunes may not change the image if it checks your feed and the image URL is the same. The server hosting your cover art image must allow HTTP head requests for iTS to be able to automatically update your cover art.

itunes_image -- Image of the podcast.
Image of the podcast.
Get or set the is_closed_captioned value of the podcast episode. This tag should be used if your podcast includes a video episode with embedded closed captioning support. The two values for this tag are "yes" and "no”.
is_closed_captioned -- If the episode has closed captioning support.
If the episode has closed captioning support.
Get or set the itunes:order value of the podcast episode. This tag can be used to override the default ordering of episodes on the store.

This tag is used at an <item> level by populating with the number value in which you would like the episode to appear on the store. For example, if you would like an <item> to appear as the first episode in the podcast, you would populate the <itunes:order> tag with “1”. If conflicting order values are present in multiple episodes, the store will use default ordering (pubDate).

To remove the order from the episode set the order to a value below zero.

itunes_order -- The order of the episode.
The order of the episode.
Get or set the itunes:season value for the podcast episode.
itunes_season -- Season number of the podcast epiosode.
Season number of the podcast episode.
Get or set the itunes:subtitle value for the podcast episode. The contents of this tag are shown in the Description column in iTunes. The subtitle displays best if it is only a few words long.
itunes_subtitle -- Subtitle of the podcast episode.
Subtitle of the podcast episode.
Get or set the itunes:summary value for the podcast episode. The contents of this tag are shown in a separate window that appears when the "circled i" in the Description column is clicked. It also appears on the iTunes page for your podcast. This field can be up to 4000 characters. If <itunes:summary> is not included, the contents of the <description> tag are used.
itunes_summary -- Summary of the podcast episode.
Summary of the podcast episode.
Get or set the itunes:title value for the podcast episode.

An episode title specific for Apple Podcasts. Don’t specify the episode number or season number in this tag. Also, don’t repeat the title of your show within your episode title.

itunes_title -- Episode title specific for Apple Podcasts
Title specific for Apple Podcast

Extends the FeedGenerator to produce torrent feeds.

2016, Raspbeguy <raspbeguy@hashtagueule.fr>
FreeBSD and LGPL, see license.* for more details.
FeedEntry extension for torrent feeds
Get or set the size of the target file.
torrent_contentlength -- The target file size.
The target file size.
Add additional fields to an RSS item.
feed -- The RSS item XML element to use.
Get or set the name of the torrent file.
torrent_filename -- The name of the torrent file.
The name of the torrent file.
Get or set the hash of the target file.
torrent_infohash -- The target file hash.
The target hash file.
Get or set the number od peers
torrent_infohash -- The peers number.
The peers number.
Get or set the number of seeds.
torrent_seeds -- The seeds number.
The seeds number.
Get or set the number of verified peers.
torrent_infohash -- The verified peers number.
The verified peers number.
FeedGenerator extension for torrent feeds.
Returns a dict that will be used in the namespace map for the feed.
  • Index
  • Module Index
  • Search Page

Lars Kiesow

2013-2024, Lars Kiesow

April 6, 2024 1.0