feedgen.feed
************

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

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

class feedgen.feed.FeedGenerator

   FeedGenerator for generating ATOM and RSS feeds.

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

      This method will add a new entry to the feed. If the feedEntry
      argument is omittet a new Entry object is created automatically.
      This is the preferred way to add new entries to a feed.

      Parameters:
         * **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*).

      Returns:
         FeedEntry object created or passed to this function.

      Example:

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

   add_item(item=None)

      This method will add a new item to the feed. If the item
      argument is omittet a new FeedEntry object is created
      automatically. This is just another name for add_entry(...)

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

      Generates an ATOM feed and write 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).

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

      Generates an ATOM feed and returns the feed XML as 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** -- Encoding used in the  XML file (default:
           UTF-8).

         * **xml_declaration** -- If an XML declaration should be
           added to the output (Default: enabled).

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

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

      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.

      Parameters:
         * **author** -- Dictionary or list of dictionaries with
           author data.

         * **replace** -- Add or replace old data.

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

      Parameters:
         * **link** -- Dict or list of dicts with data.

         * **replace** -- Add or replace old data.

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

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

      Parameters:
         * **contributor** -- Dictionary or list of dictionaries with
           contributor data.

         * **replace** -- Add or replace old data.

      Returns:
         List of contributors as dictionaries.

   copyright(copyright=None)

      Get or set the copyright notice for content in the channel. This
      RSS value will also set the atom:rights value.

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

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

      Parameters:
         **docs** -- URL of the format documentation.

      Returns:
         URL of the format documentation.

   entry(entry=None, replace=False)

      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.

      Parameters:
         **entry** -- FeedEntry object or list of FeedEntry objects.

      Returns:
         List ob all feed entries.

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

      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.

      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 which is a small image which
      provides iconic visual identification for the feed. Icons should
      be square. This is an ATOM only value.

      Parameters:
         **icon** -- URI of the feeds icon.

      Returns:
         URI of the feeds icon.

   id(id=None)

      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.

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

         * **link** -- URL of the site the image will link to. The
           default is to use the feeds first altertate 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(...)

   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.

      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.

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

      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.

      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.

      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.

      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.

      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.

      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.

      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.

   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.

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

      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** -- If an XML declaration should be
           added to the output (Default: enabled).

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

   skipDays(days=None, replace=False)

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

      Parameters:
         * **hours** -- List of days the feedreaders should not check
           the feed.

         * **replace** -- Add or replace old data.

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

      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 cannel which contains a
      human-readable description or subtitle for the feed. This ATOM
      property will also set the value for rss:description.

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

      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.

      Parameters:
         **title** -- The new title of the feed.

      Returns:
         The feeds title.

   ttl(ttl=None)

      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.

      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.

      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.
