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 feeds entry node or an RSS
   feeds item node.

   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 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:
         * **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 a 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 entries 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 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.

   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.

         * **isSummary** -- If the description should be used as
           content or summary.

      Returns:
         The entries description.

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

      Get or set the value of enclosure which describes a media object
      that is attached to the item. This is a RSS only value which is
      represented by link(rel=enclosure) in ATOM. ATOM feeds can
      furthermore contain several enclosures while RSS may contain
      only one. That is why this method, if repeatedly called, will
      add more than one enclosures to the feed.  However, only the
      last one is used for RSS.

      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 entries guid which is a string that uniquely
      identifies the item. This will also set atom:id.

      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. Id is mandatory for an ATOM entry.

      Parameters:
         **id** -- New Id of the entry.

      Returns:
         Id of the entry.

   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 nothing but a URL. So for the
      RSS link element the last link with rel=alternate is used.

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

      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.

      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 just another name for the
      published(...) method.

   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.

   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. In any case it is
      necessary that the value include timezone information.

      Parameters:
         **published** -- The creation date.

      Returns:
         Creation date as datetime.datetime

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

      Register a specific extension by classes to a namespace.

      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.

      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.

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

      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.

      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.

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

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

      Parameters:
         **updated** -- The modification date.

      Returns:
         Modification date as datetime.datetime
