PYFEEDGEN.TEX(1)

📦 version 1.0.0, in arch rolling

✨ pyFeedGen.tex — pyFeedGen Documentation ✨

okay bestie, buckle up 💅 this is the python-feedgen page, and it's literally the glow-up manual for generating web feeds. no cap, it's a whole vibe.

📖 NAME 📖

pyFeedGen.tex — pyFeedGen Documentation. that's the whole name. iconic, brief, slay.

🌸 Table of Contents 🌸

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

so basically this module generates web feeds in both ATOM and RSS format. it has extension support too — like, included is literally an extension for producing Podcasts 🎙️✨

its licensing is giving "choose your own adventure": it's licensed under the terms of both the FreeBSD license and the LGPLv3+. pick whichever one is more convenient for you, bestie 🫶 for more details have a look at license.bsd and license.lgpl.

more details about the project:

Repository — https://github.com/lkiesow/python-feedgen
Documentation — https://lkiesow.github.io/python-feedgen/
Python Package Index — https://pypi.python.org/pypi/feedgen/

🎀 INSTALLATION 🎀

Prebuild packages

if your distribution includes this project as a package (like Fedora Linux literally does), you can simply use your package manager to install it. easy. for example:

$ dnf install python3-feedgen

Using pip

you can also use pip to install the feedgen module. simply run:

$ pip install feedgen

and that's it 💖

🦋 CREATE A FEED 🦋

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

okay but here's the part you actually need to remember 👀 for the methods that set fields which 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 a 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'}, ...])

three ways, one slay 💅

⭐ GENERATE THE FEED ⭐

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

strings or files, your choice, we support both, we're not gatekeeping 😌

🌈 ADD FEED ENTRIES 🌈

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 feed's internal list of entries, and return it, so that additional data can be added. it literally does everything for you, main character energy fr fr 👑

💜 EXTENSIONS 💜

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

🎧 Example: Producing a Podcast 🎧

one extension already provided is the podcast extension. a podcast is an RSS feed with some additional elements for ITunes. yes bestie, that's literally all a podcast is on the inside 🎙️

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. so you can absolutely have your extensions and also not have them. flexible queen behavior 💅

🌸 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. everywhere!! 🦋

🧚 TESTING THE GENERATOR 🧚

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 at https://github.com/lkiesow/python-feedgen/blob/master/feedgen/__main__.py 👀

👑 API DOCUMENTATION 👑

🍓 feedgen 🍓

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.

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

✨ Create a Feed ✨

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

🌟 Generate the Feed 🌟

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

🦄 Add Feed Entries 🦄

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 feed's internal list of entries, and return it, so that additional data can be added. no cap, it's that easy 😭

🎀 Extensions 🎀

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 course 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. lowkey niche, but valid 🫶

of course you can still produce a normal ATOM or RSS feed, even if you have loaded some plugins, by temporarily disabling them during the feed generation. this can be done by calling the generating method with the keyword argument extensions set to False. so chill, your plugins aren't holding your feed hostage 💅

⭐ Testing the Generator ⭐

you can test the module by simply executing:

$ python -m feedgen

Contents:

🌸 `feedgen.feed`

💖 `copyright`

2013-2020, Lars Kiesow <<lkiesow@uos.de>>

💖 `license`

FreeBSD and LGPL, see license.* for more details. iykyk, go read the files bestie 🫶

👑 class `feedgen.feed.FeedGenerator`

okay so this is THE main character right here — the FeedGenerator that generates your ATOM and RSS feeds ✨ It's literally the whole point of the library.

⭐ `add_entry(feedEntry=None, order='prepend')`

This one adds a shiny new entry to your feed 🎀 And here's the cute part: if you don't pass the feedEntry argument, it just makes a brand new Entry object for you automatically — no cap, that's the preferred way to add new entries to a feed. 💅

Parameters

feedEntry — the FeedEntry object you wanna add.
order — if prepend is chosen, the entry gets inserted at the beginning of the feed. If append is chosen, it gets appended to the feed. (default: prepend).

Returns The FeedEntry object that was created or passed to this function.

Example:

...
>>> entry = feedgen.add_entry()
>>> entry.title('First feed entry')

heads up bestie: the order default is prepend — so your new entry goes to the TOP unless you say otherwise 💅

⭐ `add_item(item=None)`

Same energy, different name 🦋 This adds a new item to the feed, and if you skip the item argument it auto-creates a fresh FeedEntry object for you. It's literally just another name for add_entry(...) — lowkey iconic of them to give us options.

⭐ `atom_file(filename, extensions=True, pretty=False, encoding='UTF-8', xml_declaration=True)`

Generates an ATOM feed and writes the resulting XML straight into a file 📝

Parameters

filename — name of the file to write, or a file-like object, or a URL. yes bestie, three whole vibes.
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 — the encoding used in the XML file (default: UTF-8).
xml_declaration — if an XML declaration should be added to the output (Default: enabled).

⭐ `atom_str(pretty=False, extensions=True, encoding='UTF-8', xml_declaration=True)`

Same thing but instead of writing to a file it hands you the feed XML as a string 🎁

Parameters

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 — the encoding used in the XML file (default: UTF-8).
xml_declaration — if an XML declaration should be added to the output (Default: enabled).

Returns A string representation of the ATOM feed.

Return type: ngl the return type may vary between different Python versions and the encoding parameters you pass to this method 😭 For the details, go look at the lxml documentation: <https://docs.python.org/3/library/xml.etree.elementtree.html#xml.etree.ElementTree.tostring>

⭐ `author(author=None, replace=False, **kwargs)`

Get or set the author data 🫶 An author element is a dictionary holding a name, an email address and a uri. Name is mandatory for ATOM, email is mandatory for RSS. Important detail, don't skip it bestie 💅

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.

Parameters

author — Dictionary or list of dictionaries with author data.
replace — Add or replace old data.

Returns A 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'}]

⭐ `category(category=None, replace=False, **kwargs)`

Get or set the categories your feed belongs to 🏷️ lil organizational moment.

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. ✨ (yes, we're keeping all those details, that's the whole vibe)

Parameters

category — Dict or list of dicts with data.
replace — Add or replace old data.

Returns A list of category data.

⭐ `cloud(domain=None, port=None, path=None, registerProcedure=None, protocol=None)`

Set or get the cloud data of the feed ☁️ It's 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.

Parameters

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.

Returns A dictionary containing the cloud data. 🫶

⭐ `contributor(contributor=None, replace=False, **kwargs)`

Get or set the contributor data of the feed 💜 This is an ATOM only value.

This method can be called with: - the fields of a 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.

Parameters

contributor — Dictionary or list of dictionaries with contributor data.
replace — Add or replace old data.

Returns A list of contributors as dictionaries.

⭐ `copyright(copyright=None)`

Get or set the copyright notice for content in the channel 📜 And plot twist — this RSS value will also set the atom:rights value. two birds, one adorable stone 🎀

Parameters copyright — The copyright notice.

Returns The copyright notice.

⭐ `description(description=None)`

Set and get the description of the feed 🌈 This is an RSS only element — a phrase or sentence describing the channel. It is mandatory for RSS feeds. It's roughly the same as atom:subtitle, so setting this will also set atom:subtitle. multitasking queen 💅

Parameters description — Description of the channel.

Returns Description of the channel.

⭐ `docs(docs=None)`

Get or set the docs value of the feed 📚 This is an RSS only value. It's a URL that points to the documentation for the format used in the RSS file. It is probably a pointer to [1]. It's for people who might stumble across an RSS file on a Web server 25 years from now and wonder what it is 😭 honestly a public service.

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

Parameters docs — URL of the format documentation.

Returns URL of the format documentation.

⭐ `entry(entry=None, replace=False)`

Get or set feed entries ✨ But bestie, use the add_entry() method instead to automatically create the FeedEntry objects — it's the whole preferred workflow 💅

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

Parameters entry — FeedEntry object or list of FeedEntry objects.

Returns List of all feed entries.

⭐ `generator(generator=None, version=None, uri=None)`

Get or set the generator of the feed — it 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.

Parameters

generator — Software used to create the feed.
version — Version of the software.
uri — URI the software can be found.

⭐ `icon(icon=None)`

Get or set the icon of the feed 🎀 It's a small image that provides iconic visual identification for the feed. Icons should be square. And heads up — this is an ATOM only value.

Parameters

icon — the URI of the feed's icon. 🎀

Returns

The URI of the feed's icon. ✨

💖 `id(id=None)`

Okay so this one gets or sets the feed id, aka the thing that 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. 😭

Parameters

id — New Id of the ATOM feed.

Returns

Id of the feed. 🦋

🖼️ `image(url=None, title=None, link=None, width=None, height=None, description=None)`

Set the image of the feed. This element is roughly equivalent to atom:logo. 💅

Parameters

url — The URL of a GIF, JPEG or PNG image.
title — Describes the image. The default value is the feed's title.
link — URL of the site the image will link to. The default is to use the feed's 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.

Returns

Data of the image as dictionary. 🎀

🧺 `item(item=None, replace=False)`

Get or set feed items. This is just another name for entry(...). That's it, that's the vibe. ✨

🌍 `language(language=None)`

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

Parameters

language — Language of the feed.

Returns

Language of the feed. 💖

🕰️ `lastBuildDate(lastBuildDate=None)`

Set or get the lastBuildDate value, which indicates the last time the content of the channel changed. Lowkey important.

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. Do not forget the timezone bestie, I'm begging. 😭

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

Default value

If not set, lastBuildDate has as value the current date and time. ⏰

Parameters

lastBuildDate — The modification date.

Returns

Modification date as datetime.datetime. ✨

🔗 `link(link=None, replace=False, **kwargs)`

Get or set link data. A 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 a 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. That's the rule. 🫶

Parameters

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

Returns

Current set of link data. 🌸

Example:

>>> feedgen.link( href='http://example.com/', rel='self')
[{'href':'http://example.com/', 'rel':'self'}]

🧩 `load_extension(name, atom=True, rss=True)`

Load a specific extension by name. Plug it in, plug it in. 🔌

Parameters

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.

🎨 `logo(logo=None)`

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. Main character image energy. 👑

Parameters

logo — Logo of the feed.

Returns

Logo of the feed. 🎀

📧 `managingEditor(managingEditor=None)`

Set or get the value for managingEditor, which is the email address for person responsible for editorial content. This is a RSS only value. 📬

Parameters

managingEditor — Email address of the managing editor.

Returns

Email address of the managing editor. 💌

📅 `pubDate(pubDate=None)`

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. 🗞️

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

Parameters

pubDate — The publication date.

Returns

Publication date as datetime.datetime. ✨

⭐ `rating(rating=None)`

Set and get the PICS rating for the channel. It is an RSS only value. ⭐

🛠️ `register_extension(namespace, extension_class_feed=None, extension_class_entry=None, atom=True, rss=True)`

Registers an extension by class. Very official. Very slay. 💅

Parameters

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_entry(entry)`

Remove a single entry from the feed. This method accepts both the FeedEntry object to remove or the index of the entry as argument. Bye bestie. 👋

Parameters

entry — Entry or index of entry to remove.

🧹 `remove_item(item)`

Remove a single item from the feed. This is another name for remove_entry. Same energy, different name. ✨

⚖️ `rights(rights=None)`

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. Legal-ish queen behavior. 👑

Parameters

rights — Rights information of the feed.

📰 `rss_file(filename, extensions=True, pretty=False, encoding='UTF-8', xml_declaration=True)`

Generates an RSS feed and writes the resulting XML to a file. 🗂️

Parameters

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

📜 `rss_str(pretty=False, extensions=True, encoding='UTF-8', xml_declaration=True)`

Generates an RSS feed and returns the feed XML as string. String time. 🧵

Parameters

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 — whether an XML declaration should get added to the output (Default: enabled). ✨

Returns: String representation of the RSS feed.

Return type: okay so this one is a little chaotic — 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 https://docs.python.org/3/library/xml.etree.elementtree.html#xml.etree.ElementTree.tostring — no cap, go read it if you need the specifics 💅

🦋 `skipDays(days=None, replace=False)`

Set or get the value of skipDays — it's a lil hint for aggregators telling them which days they can skip. Heads up bestie: this is an RSS only value.

You can call this method with a single day name or a whole list of day names. Days are represented as strings from 'Monday' to 'Sunday'. 🗓️

Parameters

hours — List of days the feedreaders should not check the feed.
replace — Add or replace old data.

okay yes, the parameter is literally called days up top and the docs then call it hours — iconic of them, I'm keeping it exactly as written 🙈

Returns: List of days the feedreaders should not check the feed.

🌸 `skipHours(hours=None, replace=False)`

Set or get the value of skipHours, a hint for aggregators telling them which hours they can skip. Also an RSS only value.

You can call this with one hour or a list of hours. Hours are integer values from 0 to 23. ⏰

Parameters

hours — List of hours the feedreaders should not check the feed.
replace — Add or replace old data.

Returns: List of hours the feedreaders should not check the feed.

🎀 `subtitle(subtitle=None)`

Get or set the subtitle value of the channel, which holds a human-readable description or subtitle for the feed. This ATOM property will also set the value for rss:description. two birds, one slay 🐦

Parameters

subtitle — The subtitle of the feed.

Returns: The subtitle of the feed.

🫶 `textInput(title=None, description=None, name=None, link=None)`

Get or set the value of textInput. This is an RSS only field. And honestly? 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. So like... do with that what you will.

Parameters

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.

Returns: Dictionary containing textInput values.

👑 `title(title=None)`

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. Do not skip this one bestie, it's the main character. 💅

Parameters

title — The new title of the feed.

Returns: The feed's title.

⭐ `ttl(ttl=None)`

Get or set the ttl value. It's 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. ⏳

Parameters

ttl — Integer value indicating how long the channel may be cached.

Returns: Time to live.

🌈 `updated(updated=None)`

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. ⚠️ like actually necessary, don't come crying to me.

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

Default value: If not set, updated has as value the current date and time.

Parameters

updated — The modification date.

Returns: Modification date as datetime.datetime

💜 `webMaster(webMaster=None)`

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. 🙋‍♀️

Parameters

webMaster — Email address of the webmaster.

Returns: Email address of the webmaster.

🧚 feedgen.entry

copyright

2013-2020, Lars Kiesow <lkiesow@uos.de>

license

FreeBSD and LGPL, see license.* for more details.

🦋 class `feedgen.entry.FeedEntry`

FeedEntry call representing an ATOM feed's entry node or an RSS feed's item node. it's giving duality, we love that ✨

atom_entry(extensions=True) — Create an ATOM entry and return it.

author(author=None, replace=False, **kwargs) — 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.

Parameters

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'}]

category(category=None, replace=False, **kwargs) — 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 category 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.

Parameters

category — Dict or list of dicts with data.
replace — Add or replace old data.

Returns: List of category data.

comments(comments=None) — Get or set the value of comments, which is the URL of the comments page for the item. This is an RSS only value. 💬

Parameters

comments — URL to the comments page.

Returns: URL to the comments page.

content(content=None, src=None, type=None) — 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. ✍️

Parameters

content — The content of the feed entry.
src — Link to the entry's content.
type — If type is CDATA content would not be escaped.

Returns: Content element of the entry.

contributor(contributor=None, replace=False, **kwargs) — Get or set the contributor data of the feed. This is an ATOM only value. 🫶

This method can be called with:

the fields of a contributor as keyword arguments
the fields of a contributor as a dictionary
a list of dictionaries containing the contributor fields

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

Parameters

contributor — Dictionary or list of dictionaries with contributor data.
replace — Add or replace old data.

Returns: List of contributors as dictionaries.

description(description=None, isSummary=False) — 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.

Parameters

description — Description of the entry.

`enclosure(url=None, length=None, type=None)`

Get or set the enclosure value, bestie — that's the thing that describes a media object attached to the item. Heads up: this is an RSS only value, and in ATOM it's represented by link(rel=enclosure). And like, ATOM feeds can hold several enclosures while RSS can only hold one. Which is why this method, if you keep calling it over and over, will add more than one enclosure to the feed. But only the last one is what RSS actually uses. 😭

Parameters

url — URL of the media object.
length — Size of the media in bytes.
type — Mimetype of the linked media.

Returns

Data of the enclosure element.

`guid(guid=None, permalink=False)`

Get or set the entry's guid — a string that uniquely identifies the item. This will also set atom:id, cute right?

Parameters

guid — Id of the entry.
permalink — If this is a permanent identifier for this item.

Returns

Id and permalink setting of the entry.

`id(id=None)`

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. And fr, id is mandatory for an ATOM entry. 👑

Parameters

id — New Id of the the entry.

Returns

Id of the entry.

`link(link=None, replace=False, **kwargs)`

Get or set link data. A 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 enclosure element per entry, which is covered by the link element in ATOM feed entries. So for the RSS enclosure element, the last link with rel=enclosure is used.

Parameters

link — Dict or list of dicts with data.
replace — Add or replace old data.

Returns

List of link data.

`load_extension(name, atom=True, rss=True)`

Load a specific extension by name. Slay.

Parameters

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.

`pubDate(pubDate=None)`

Get or set the pubDate of the entry, which indicates when the entry was published. This method is literally just another name for the published(...) method. Same vibes, different spelling.

`pubdate(pubDate=None)`

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, bestie. Don't get attached.

`published(published=None)`

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. Either way, it is necessary that the value include timezone information. No timezone, no deal. 🕐

Parameters

published — The creation date.

Returns

Creation date as datetime.datetime

`register_extension(namespace, extension_class_entry=None, atom=True, rss=True)`

Parameters

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.

`rights(rights=None)`

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. Two for one, we love efficiency. 💅

Parameters

rights — Rights information of the feed.

Returns

Rights information of the feed.

`rss_entry(extensions=True)`

Create a RSS item and return it.

`source(url=None, title=None)`

Get or set the source for the current feed entry.

Okay so real talk: ATOM feeds support a lot more sub elements than title and URL (which is what RSS supports), but those are currently not supported. Patches are welcome if that's your thing. 🫶

Parameters

url — Link to the source.
title — Title of the linked resource

Returns

Source element as dictionaries.

`summary(summary=None, type=None)`

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. Sneaky but helpful. ✨

Parameters

summary — Summary of the entries contents.

Returns

Summary of the entries contents.

`title(title=None)`

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. Like, don't leave it empty, that's not the move. 🙈

Parameters

title — The new title of the entry.

Returns

The entries title.

`ttl(ttl=None)`

Get or set the ttl value. It's 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.

Parameters

ttl — Integer value representing the time to live.

Returns

Time to live of of the entry.

`updated(updated=None)`

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. (Yes, same rule as published. Timezones are not optional, bestie. 🌍)

Parameters

updated — The modification date.

Returns

Modification date as datetime.datetime

🌈 `feedgen.util`

This file contains helper functions for the feed generator module. Little utilities doing the quiet work behind the scenes, iykyk.

copyright

2013, Lars Kiesow <lkiesow@uos.de>

license

FreeBSD and LGPL, see license.* for more details.

`feedgen.util.ensure_format(val, allowed, required, allowed_values=None, defaults=None)`

Takes a dictionary or a list of dictionaries and checks 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. A whole vibe check for your dicts. ✅

Parameters

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.

Returns

List of checked dictionaries.

🌸 `feedgen.util.formatRFC2822(date)`

Okay bestie, this one's a tiny helper: it makes sure the locale setting does not interfere with the time format. That's it. That's the whole vibe check. 💅

🦋 `feedgen.ext.base`

This is the basic FeedGenerator extension — it literally does nothing except provide all the necessary methods. Lowkey the friend who shows up with no snacks but has every charger you could ever need. 🔌

copyright — 2013, Lars Kiesow <<lkiesow@uos.de>>

license — FreeBSD and LGPL, see license.* for more details.

🎀 `class feedgen.ext.base.BaseEntryExtension`

Basic FeedEntry extension. Short, sweet, iconic.

🎀 `class feedgen.ext.base.BaseExtension`

Basic FeedGenerator extension.

extend_atom(feed) — Extend an ATOM feed xml structure containing all previously set fields. ✨

Parameters:

feed -- The feed xml root element.

Returns: The feed root element.

extend_ns() — Returns a dict that will be used in the namespace map for the feed. No cap, it just hands you the namespace dict.

extend_rss(feed) — Extend a RSS feed xml structure containing all previously set fields. 💖

Parameters:

feed -- The feed xml root element.

Returns: The feed root element.

🌈 `feedgen.ext.dc`

Extends the FeedGenerator to add Dublin Core Elements to the feeds. Yes bestie, we're adding metadata lore. 📚

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

copyright — 2013-2017, Lars Kiesow <<lkiesow@uos.de>>

license — FreeBSD and LGPL, see license.* for more details.

💅 `class feedgen.ext.dc.DcBaseExtension`

Dublin Core Elements extension for podcasts. Periodt. 🎙️

dc_contributor(contributor=None, replace=False) — 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>

Parameters:

contributor -- Contributor or list of contributors.
replace -- Replace already set contributors (default: False).

Returns: List of contributors.

dc_coverage(coverage=None, replace=True) — Get or set the dc:coverage, which indicates the spatial or temporal topic of the resource, the spatial applicability of the resource, or the jurisdiction under which the resource is relevant. Big metadata energy. 🗺️

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>

Parameters:

coverage -- Coverage of the feed.
replace -- Replace already set coverage (default: True).

Returns: Coverage of the feed.

dc_creator(creator=None, replace=False) — Get or set the dc:creator, which is an entity primarily responsible for making the resource. Main character energy, but for metadata. 👑

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

Parameters:

creator -- Creator or list of creators.
replace -- Replace already set creators (default: False).

Returns: List of creators.

dc_date(date=None, replace=True) — Get or set the dc:date, which describes a point or period of time associated with an event in the lifecycle of the resource. Timestamp slay. ⏰

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

Parameters:

date -- Date or list of dates.
replace -- Replace already set dates (default: True).

Returns: List of dates.

dc_description(description=None, replace=True) — Get or set the dc:description, which is an account of the resource. Tell the people what it is, bestie. 📝

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

Parameters:

description -- Description or list of descriptions.
replace -- Replace already set descriptions (default: True).

Returns: List of descriptions.

dc_format(format=None, replace=True) — Get or set the dc:format, which describes the file format, physical medium, or dimensions of the resource. It's giving "what even is this file". 💾

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

Parameters:

format -- Format of the resource or list of formats.
replace -- Replace already set format (default: True).

Returns: Format of the resource.

dc_identifier(identifier=None, replace=True) — Get or set the dc:identifier, which should be an unambiguous reference to the resource within a given context. No cap, make it unique. 🔑

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

Parameters:

identifier -- Identifier of the resource or list of identifiers.
replace -- Replace already set identifier (default: True).

Returns: Identifiers of the resource.

dc_language(language=None, replace=True) — Get or set the dc:language, which describes a language of the resource. Fr fr, language matters. 🌍

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

Parameters:

language -- Language or list of languages.
replace -- Replace already set languages (default: True).

Returns: List of languages.

dc_publisher(publisher=None, replace=False) — Get or set the dc:publisher, which is an entity responsible for making the resource available. The plug. 📢

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

Parameters:

publisher -- Publisher or list of publishers.
replace -- Replace already set publishers (default: False).

Returns: List of publishers.

dc_relation(relation=None, replace=False) — Get or set the dc:relation, which describes a related resource. It's giving "linked, but make it metadata". 🔗

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

Parameters:

relation -- Relation or list of relations.
replace -- Replace already set relations (default: False).

Returns: List of relations.

dc_rights(rights=None, replace=False) — Get or set the dc:rights, which may contain information about rights held in and over the resource. Legal bestie has entered the chat. ⚖️

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

Parameters:

rights -- Rights information or list of rights information.
replace -- Replace already set rights (default: False).

Returns: List of rights information.

dc_source(source=None, replace=False) — 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>

Parameters:

source -- Source or list of sources.
replace -- Replace already set sources (default: False).

Returns: List of sources.

dc_subject(subject=None, replace=False) — Get or set the dc:subject, which describes the topic of the resource. The vibe of the feed, basically. 🏷️

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

Parameters:

subject -- Subject or list of subjects.
replace -- Replace already set subjects (default: False).

Returns: List of subjects.

dc_title(title=None, replace=True) — Get or set the dc:title, which is a name given to the resource. The literal title. The nameplate. The header. You get it. 🎀

(Also yes — the signature up top says replace=True, but the bullet below says default False. I'm just repeating the page, bestie. Don't come for me. 😭)

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

Parameters:

title -- Title or list of titles.
replace -- Replace already set titles (default: False).

Returns: List of titles.

dc_type(type=None, replace=False) 🎀

Grab or set the dc:type — literally the thing that says what nature or genre your resource actually is, bestie.

For the full tea, peep: http://dublincore.org/documents/dcmi-terms/#elements-type

Parameters

type — a type, or a whole list of types, your call 💅
replace — nuke the types that are already set and start fresh (default: False)

Returns: List of types.

extend_atom(atom_feed) ✨

Sprinkles all the DC fields you've set onto an Atom feed.

Parameters

atom_feed — the feed root element

Returns: the feed root element

extend_ns() 🦋

Returns: a dict that gets used in the namespace map for the feed.

extend_rss(rss_feed) 🌸

Same deal, but for RSS — extends it with all the DC fields you set.

Parameters

rss_feed — the feed root element

Returns: the feed root element.

💜 `class feedgen.ext.dc.DcEntryExtension`

Dublin Core Elements extension for podcasts. Iconic.

extend_atom(entry)

Drops the dc elements into an atom item. Heads up: it alters the item itself, no cap.

Parameters

entry — an atom entry element.

Returns: the entry element.

extend_rss(item)

Drops the dc elements into a RSS item. Also alters the item itself, fr fr.

Parameters

item — a RSS item element.

Returns: the item element.

🌈 `class feedgen.ext.dc.DcExtension`

Dublin Core Elements extension for podcasts. (Yes, same description as above — it's giving twin energy 💀)

🎧 `feedgen.ext.podcast`

Extends the FeedGenerator so it can produce podcasts. Main character behavior, honestly.

license FreeBSD and LGPL, see license.* for more details.

👑 `class feedgen.ext.podcast.PodcastExtension`

The FeedGenerator extension for podcasts. Obsessed with her.

extend_ns()

Returns: a dict that will be used in the namespace map for the feed.

extend_rss(rss_feed)

Extends an RSS feed root with the itunes fields you've set.

Returns: the feed root element.

itunes_author(itunes_author=None) 🫶

Get or set itunes:author. Whatever you put here shows up in the Artist column in iTunes. If the tag isn't there, iTunes falls back to the contents of the <author> tag. And if <itunes:author> isn't present at the feed level, iTunes will straight up use the contents of <managingEditor>.

Parameters

itunes_author — the author of the podcast.

Returns: the author of the podcast.

itunes_block(itunes_block=None) 🙈

Get or set the iTunes block attribute. Use this to stop the entire podcast from showing up in the iTunes podcast directory. That's the whole vibe check.

Parameters

itunes_block — block the podcast.

Returns: if the podcast is blocked.

itunes_category(itunes_category=None, replace=False, **kwargs) 🍓

Get or set the iTunes category — the one that appears in the category column and in the iTunes Store Browser.

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

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.

So like, if the parameter is:

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

…it would become:

<itunes:category text="Arts">
    <itunes:category text="Design"/>
    <itunes:category text="Food"/>
</itunes:category>

Parameters

itunes_category — dictionary or list of dictionaries with itunes_category data.
replace — add or replace old data.

Returns: list of itunes_categories as dictionaries.

⚠️ Important note about deprecated parameter syntax: old versions of feedgen only supported one category plus one subcategory, which got passed to this function as the first two parameters. For compatibility reasons that still works, but you should not use it and it may be removed at any time. Consider this your warning, bestie 💀

itunes_complete(itunes_complete=None) ✅

Get or set the itunes:complete value of the podcast. This tag is how you indicate a podcast is done-done.

If you populate this tag with "yes", you're saying 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 has no effect on the podcast. Literally nothing.

Parameters

itunes_complete — if the podcast is complete.

Returns: if the podcast is complete.

itunes_explicit(itunes_explicit=None) 🔥

Get or set the itunes:explicit value of the podcast. This tag is for indicating whether your podcast contains explicit material. The three values for this tag are "yes", "no", and "clean".

Here's the breakdown:

Populate it with "yes" and an "explicit" parental advisory graphic appears 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 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 at all — blank is the default advisory type.

Parameters

itunes_explicit — if the podcast contains explicit material.

Returns: if the podcast contains explicit material.

itunes_image(itunes_image=None) 🎀

Get or set the image for the podcast. This tag is the artwork for your podcast — put the URL to the image in the href attribute.

The specs, since iTunes is picky:

iTunes prefers square .jpg images that are at least 1400x1400 pixels, which is different from what's specified for the standard RSS image tag.
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 still the same. Also, the server hosting your cover art image must allow HTTP head requests for iTS to be able to automatically update your cover art. Don't skip this step, iykyk.

Parameters

itunes_image — image of the podcast.

Returns: image of the podcast.

itunes_new_feed_url(itunes_new_feed_url=None) 🦋

Get or set the new-feed-url property of the podcast. This tag lets you change the URL where the podcast feed lives.

After adding the tag to your old feed, keep maintaining the old feed for 48 hours before retiring it. At that point, iTunes will have updated the directory with the new feed URL. Patience is a virtue, bestie ✨

Parameters

itunes_new_feed_url — new feed URL.

Returns: new feed URL.

itunes_owner(name=None, email=None) 💌

Get or set the itunes:owner of the podcast. This tag holds the info used to contact the owner of the podcast for communication specifically about the podcast. It will not be publicly displayed — private, like your finsta.

Parameters

itunes_owner — the owner of the feed.

Returns: data of the owner of the feed.

itunes_subtitle(itunes_subtitle=None) ⭐

Get or set the itunes:subtitle value for the podcast. The contents show up in the Description column in iTunes. It displays best if it's only a few words long — short and slay.

Parameters

itunes_subtitle — subtitle of the podcast.

Returns: subtitle of the podcast.

itunes_summary(itunes_summary=None) 📝

Get or set the itunes:summary value for the podcast. The contents of this tag are shown in a separate window that pops up 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.

Parameters

itunes_summary — summary of the podcast.

Returns: Summary of the podcast.

`itunes_type(itunes_type=None)` ✨

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.

Parameters: itunes_type — the type of the podcast.
Returns: type of the pdocast.

`feedgen.ext.podcast_entry` 🎧

Extends the feedgen to produce podcasts.

license: FreeBSD and LGPL, see license.* for more details.

class feedgen.ext.podcast_entry.PodcastEntryExtension — FeedEntry extension for podcasts. 👑

`extend_rss(entry)` 🌸

Add additional fields to an RSS item.

Parameters: feed — the RSS item XML element to use.

`itunes_author(itunes_author=None)` 🎤

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

Parameters: itunes_author — the author of the podcast.
Returns: the author of the podcast.

`itunes_block(itunes_block=None)` 🚫

Get or set the ITunes block attribute. Use this to prevent episodes from appearing in the iTunes podcast directory.

Parameters: itunes_block — block podcast episodes.
Returns: if the podcast episode is blocked.

`itunes_duration(itunes_duration=None)` ⏱️

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.

Parameters: itunes_duration — duration of the podcast episode.
Returns: duration of the podcast episode.

`itunes_episode(itunes_episode=None)` 🔢

Get or set the itunes:episode value for the podcast episode.

Parameters: itunes_season — episode number of the podcast epiosode.
Returns: episode number of the podcast episode.

`itunes_episode_type(itunes_episode_type=None)` 🎬

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.

Parameters: itunes_episode_type — the episode type.
Returns: type of the episode.

`itunes_explicit(itunes_explicit=None)` 🔞

Get or set 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.

Parameters: itunes_explicit — if the podcast episode contains explicit material.
Returns: if the podcast episode contains explicit material.

`itunes_image(itunes_image=None)` 🖼️

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.

Parameters: itunes_image — image of the podcast.
Returns: image of the podcast.

`itunes_is_closed_captioned(itunes_is_closed_captioned=None)` 💬

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

Parameters: is_closed_captioned — if the episode has closed captioning support.
Returns: if the episode has closed captioning support.

`itunes_order(itunes_order=None)` 🔀

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.

Parameters: itunes_order — the order of the episode.
Returns: the order of the episode.

`itunes_season(itunes_season=None)` 🌦️

Get or set the itunes:season value for the podcast episode.

Parameters: itunes_season — season number of the podcast epiosode.
Returns: season number of the podcast episode.

`itunes_subtitle(itunes_subtitle=None)` ✏️

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.

Parameters: itunes_subtitle — subtitle of the podcast episode.
Returns: subtitle of the podcast episode.

`itunes_summary(itunes_summary=None)` 📝

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.

Parameters: itunes_summary — summary of the podcast episode.
Returns: summary of the podcast episode.
itunes_title(itunes_title=None) — Get or set the itunes:title value for the podcast episode.

Okay so this one’s an episode title made specifically for Apple Podcasts. Don’t put the episode number or season number in this tag, and don’t repeat the title of your show inside your episode title. Got it? 💅

Parameters: itunes_title — Episode title specific for Apple Podcasts
Returns: Title specific for Apple Podcast

🌈 `feedgen.ext.torrent` 🌈

Extends the FeedGenerator to produce torrent feeds. Yes, torrent feeds. We love a niche icon. 🏴‍☠️✨

license: FreeBSD and LGPL, see license.* for more details.

🏴‍☠️ class `feedgen.ext.torrent.TorrentEntryExtension` 🏴‍☠️

FeedEntry extension for torrent feeds. It’s giving “entry but make it torrent.” 🌊

contentlength(torrent_contentlength=None) — Get or set the size of the target file.

Like, how big is the target file? This grabs or sets that.

Parameters: torrent_contentlength — The target file size.
Returns: The target file size.

extend_rss(entry) — Add additional fields to an RSS item.
- Parameters: feed — The RSS item XML element to use.
filename(torrent_filename=None) — Get or set the name of the torrent file.
- Parameters: torrent_filename — The name of the torrent file.
- Returns: The name of the torrent file.
infohash(torrent_infohash=None) — Get or set the hash of the target file.
- Parameters: torrent_infohash — The target file hash.
- Returns: The target hash file.
peers(torrent_peers=None) — Get or set the number od peers. (that’s what it says, bestie — “od” and all 😭)
- Parameters: torrent_infohash — The peers number.
- Returns: The peers number.
seeds(torrent_seeds=None) — Get or set the number of seeds.
- Parameters: torrent_seeds — The seeds number.
- Returns: The seeds number.
verified(torrent_verified=None) — Get or set the number of verified peers.
- Parameters: torrent_infohash — The verified peers number.
- Returns: The verified peers number.

👑 class `feedgen.ext.torrent.TorrentExtension` 👑

FeedGenerator extension for torrent feeds. Main character energy for your namespace map. 🌈

extend_ns() — Returns a dict that will be used in the namespace map for the feed.

Index <>
Module Index <>
Search Page <>

👑 Author 👑

Lars Kiesow

💖 Copyright 💖

2013-2016, Lars Kiesow

Okay that’s the whole page, bestie! 🫶 This one’s version 1.0, dated Dec 14, 2025 — go forth and make feeds that absolutely slay. 💅✨🦋

📦 where this page comes from

arch rolling: python-feedgen 1.0.0-4 · BSD
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms

PYFEEDGEN.TEX(1)

✨ pyFeedGen.tex — pyFeedGen Documentation ✨

📖 NAME 📖

🌸 Table of Contents 🌸

🎀 INSTALLATION 🎀

Prebuild packages

Using pip

🦋 CREATE A FEED 🦋

⭐ GENERATE THE FEED ⭐

🌈 ADD FEED ENTRIES 🌈

💜 EXTENSIONS 💜

🎧 Example: Producing a Podcast 🎧

🌸 Custom Extensions 🌸

🧚 TESTING THE GENERATOR 🧚

👑 API DOCUMENTATION 👑

🍓 feedgen 🍓

✨ Create a Feed ✨

🌟 Generate the Feed 🌟

🦄 Add Feed Entries 🦄

🎀 Extensions 🎀

🎙️ Example: Producing a Podcast 🎙️

⭐ Testing the Generator ⭐

🌸 feedgen.feed

💖 copyright

💖 license

👑 class feedgen.feed.FeedGenerator

⭐ add_entry(feedEntry=None, order='prepend')

⭐ add_item(item=None)

⭐ atom_file(filename, extensions=True, pretty=False, encoding='UTF-8', xml_declaration=True)

⭐ atom_str(pretty=False, extensions=True, encoding='UTF-8', xml_declaration=True)

⭐ author(author=None, replace=False, **kwargs)

⭐ category(category=None, replace=False, **kwargs)

⭐ cloud(domain=None, port=None, path=None, registerProcedure=None, protocol=None)

⭐ contributor(contributor=None, replace=False, **kwargs)

⭐ copyright(copyright=None)

⭐ description(description=None)

⭐ docs(docs=None)

⭐ entry(entry=None, replace=False)

⭐ generator(generator=None, version=None, uri=None)

⭐ icon(icon=None)

💖 id(id=None)

🖼️ image(url=None, title=None, link=None, width=None, height=None, description=None)

🧺 item(item=None, replace=False)

🌍 language(language=None)

🕰️ lastBuildDate(lastBuildDate=None)

🔗 link(link=None, replace=False, **kwargs)

🧩 load_extension(name, atom=True, rss=True)

🎨 logo(logo=None)

📧 managingEditor(managingEditor=None)

📅 pubDate(pubDate=None)

⭐ rating(rating=None)

🛠️ register_extension(namespace, extension_class_feed=None, extension_class_entry=None, atom=True, rss=True)

🗑️ remove_entry(entry)

🧹 remove_item(item)

⚖️ rights(rights=None)

📰 rss_file(filename, extensions=True, pretty=False, encoding='UTF-8', xml_declaration=True)

📜 rss_str(pretty=False, extensions=True, encoding='UTF-8', xml_declaration=True)

🦋 skipDays(days=None, replace=False)

🌸 skipHours(hours=None, replace=False)

🎀 subtitle(subtitle=None)

🫶 textInput(title=None, description=None, name=None, link=None)

👑 title(title=None)

⭐ ttl(ttl=None)

🌈 updated(updated=None)

💜 webMaster(webMaster=None)

🧚 feedgen.entry

copyright

license

🦋 class feedgen.entry.FeedEntry

enclosure(url=None, length=None, type=None)

guid(guid=None, permalink=False)

id(id=None)

link(link=None, replace=False, **kwargs)

load_extension(name, atom=True, rss=True)

pubDate(pubDate=None)

pubdate(pubDate=None)

published(published=None)

register_extension(namespace, extension_class_entry=None, atom=True, rss=True)

rights(rights=None)

rss_entry(extensions=True)

🌸 `feedgen.feed`

💖 `copyright`

💖 `license`

👑 class `feedgen.feed.FeedGenerator`

⭐ `add_entry(feedEntry=None, order='prepend')`

⭐ `add_item(item=None)`

⭐ `atom_file(filename, extensions=True, pretty=False, encoding='UTF-8', xml_declaration=True)`

⭐ `atom_str(pretty=False, extensions=True, encoding='UTF-8', xml_declaration=True)`

⭐ `author(author=None, replace=False, **kwargs)`

⭐ `category(category=None, replace=False, **kwargs)`

⭐ `cloud(domain=None, port=None, path=None, registerProcedure=None, protocol=None)`

⭐ `contributor(contributor=None, replace=False, **kwargs)`

⭐ `copyright(copyright=None)`

⭐ `description(description=None)`

⭐ `docs(docs=None)`

⭐ `entry(entry=None, replace=False)`

⭐ `generator(generator=None, version=None, uri=None)`

⭐ `icon(icon=None)`

💖 `id(id=None)`

🖼️ `image(url=None, title=None, link=None, width=None, height=None, description=None)`

🧺 `item(item=None, replace=False)`

🌍 `language(language=None)`

🕰️ `lastBuildDate(lastBuildDate=None)`

🔗 `link(link=None, replace=False, **kwargs)`

🧩 `load_extension(name, atom=True, rss=True)`

🎨 `logo(logo=None)`

📧 `managingEditor(managingEditor=None)`

📅 `pubDate(pubDate=None)`

⭐ `rating(rating=None)`

🛠️ `register_extension(namespace, extension_class_feed=None, extension_class_entry=None, atom=True, rss=True)`

🗑️ `remove_entry(entry)`

🧹 `remove_item(item)`

⚖️ `rights(rights=None)`

📰 `rss_file(filename, extensions=True, pretty=False, encoding='UTF-8', xml_declaration=True)`

📜 `rss_str(pretty=False, extensions=True, encoding='UTF-8', xml_declaration=True)`

🦋 `skipDays(days=None, replace=False)`

🌸 `skipHours(hours=None, replace=False)`

🎀 `subtitle(subtitle=None)`

🫶 `textInput(title=None, description=None, name=None, link=None)`

👑 `title(title=None)`

⭐ `ttl(ttl=None)`

🌈 `updated(updated=None)`

💜 `webMaster(webMaster=None)`

🦋 class `feedgen.entry.FeedEntry`

`enclosure(url=None, length=None, type=None)`

`guid(guid=None, permalink=False)`

`id(id=None)`

`link(link=None, replace=False, **kwargs)`

`load_extension(name, atom=True, rss=True)`

`pubDate(pubDate=None)`

`pubdate(pubDate=None)`

`published(published=None)`

`register_extension(namespace, extension_class_entry=None, atom=True, rss=True)`

`rights(rights=None)`

`rss_entry(extensions=True)`

`source(url=None, title=None)`

`summary(summary=None, type=None)`

`title(title=None)`

`ttl(ttl=None)`

`updated(updated=None)`

🌈 `feedgen.util`

`feedgen.util.ensure_format(val, allowed, required, allowed_values=None, defaults=None)`

🌸 `feedgen.util.formatRFC2822(date)`

🦋 `feedgen.ext.base`

🎀 `class feedgen.ext.base.BaseEntryExtension`

🎀 `class feedgen.ext.base.BaseExtension`

🌈 `feedgen.ext.dc`

💅 `class feedgen.ext.dc.DcBaseExtension`

💜 `class feedgen.ext.dc.DcEntryExtension`

🌈 `class feedgen.ext.dc.DcExtension`

🎧 `feedgen.ext.podcast`

👑 `class feedgen.ext.podcast.PodcastExtension`

`itunes_type(itunes_type=None)` ✨

`feedgen.ext.podcast_entry` 🎧

`extend_rss(entry)` 🌸

`itunes_author(itunes_author=None)` 🎤

`itunes_block(itunes_block=None)` 🚫

`itunes_duration(itunes_duration=None)` ⏱️

`itunes_episode(itunes_episode=None)` 🔢

`itunes_episode_type(itunes_episode_type=None)` 🎬