= Feeds components =

`feeds` is a ZCML directive for handling feeds requests.  The
directive requires minimal ZCML configuration and relies on
implementing view classes defining the `usedfor` and `name` class
variables.

Feeds are defined on the `FeedsLayer` layer.


== Demonstrating a feeds class ==

In order to demonstrate a feed class, we need to create an interface
for the thing comprising the feed.  Rather than use a standard
Launchpad interface, we'll define one here.

    >>> from zope.interface import Interface, Attribute, implements
    >>> from lp.services.feeds.tests.helper import (
    ...     IThing, Thing, ThingFeedView)


== ZCML for browser:feeds ==

The zcml `browser:feeds` directive describes a feed view.

    >>> from zope.configuration import xmlconfig
    >>> zcmlcontext = xmlconfig.string("""
    ... <configure xmlns:browser="http://namespaces.zope.org/browser">
    ...   <include package="lp.services.webapp" file="meta.zcml" />
    ...   <include package="zope.app.zcmlfiles" file="meta.zcml" />
    ...   <browser:feeds
    ...       module="lp.services.feeds.tests.helper"
    ...       classes="ThingFeedView"
    ...       />
    ... </configure>
    ... """)

Get the view from a `thing` on 'thing-feed' for a request.

    >>> from zope.component import getMultiAdapter
    >>> from lp.services.webapp.servers import LaunchpadTestRequest
    >>> from lp.services.webapp.testing import verifyObject

    >>> request = LaunchpadTestRequest()

To successfully get a view, the lookup must be on an object that is an
`IThing` and the view name must be one that is supported.  If the
view is not found a ComponentLookupError is raised.  Also, the request
must be in the FeedsLayer.

The request we just created is not in the FeedsLayer, so the view will
not be found.

    >>> thing = Thing('thing 1')
    >>> verifyObject(IThing, thing)
    True
    >>> feed_view = getMultiAdapter((thing, request), name='thing-feed.xml')
    Traceback (most recent call last):
      ...
    ComponentLookupError: ...

Set the layer on the request for all subsequent uses.

    >>> from lp.layers import setFirstLayer, FeedsLayer
    >>> setFirstLayer(request, FeedsLayer)

If the context object is not an IThing then the view will not be
found.

    >>> thing = object()
    >>> verifyObject(IThing, thing)
    Traceback (most recent call last):
      ...
    DoesNotImplement: ...
    >>> feed_view = getMultiAdapter((thing, request), name='thing-feed.atom')
    Traceback (most recent call last):
      ...
    ComponentLookupError: ...

If the name is not one of the supported names the view will not be
found.

    >>> thing = Thing('thing 1')
    >>> verifyObject(IThing, thing)
    True
    >>> feed_view = getMultiAdapter((thing, request), name='thing-feed.xml')
    Traceback (most recent call last):
      ...
    ComponentLookupError: ...

If the thing is an IThing and the name is supported the view will be
found, indicated by the absence of a ComponentLookupError.

    >>> thing = Thing('thing 1')
    >>> verifyObject(IThing, thing)
    True
    >>> for name in ['thing-feed.atom', 'thing-feed.html']:
    ...     feed_view = getMultiAdapter((thing, request), name=name)
    ...     print feed_view()
    a feed view on an IThing
    a feed view on an IThing

== Feeds Configuration Options ==

The max_feed_cache_minutes and the max_bug_feed_cache_minutes
configurations are provided to allow overriding the Expires
and Cache-Control headers so that the feeds will be cached longer
by browsers and the reverse-proxy in front of the feeds servers.

    >>> from lp.services.config import config
    >>> from lp.services.feeds.feed import FeedBase
    >>> from lp.bugs.feed.bug import BugsFeedBase
    >>> config.launchpad.max_feed_cache_minutes
    60
    >>> config.launchpad.max_bug_feed_cache_minutes
    30
    >>> FeedBase.max_age
    3600
    >>> BugsFeedBase.max_age
    1800
    >>> config.launchpad.max_feed_cache_minutes * 60 == FeedBase.max_age
    True
    >>> (config.launchpad.max_bug_feed_cache_minutes * 60
    ...  == BugsFeedBase.max_age)
    True


== FeedTypedData class ==

The FeedTypedData class performs the appropriate escaping for data
with a type of "text", "html", or "xhtml". The template is responsible
for setting the "type" attribute in the <title> or <content> element. If
no content type is specified, then "text" is assumed.

Since plain text and html are not valid xml, "<", ">", and "&" must
be escaped using xml entities such as "&lt;".

    >>> from lp.services.feeds.feed import FeedTypedData
    >>> text = FeedTypedData("<b> and &nbsp; and &amp;")
    >>> text.content
    '&lt;b&gt; and &amp;nbsp; and &amp;amp;'
    >>> text2 = FeedTypedData("<b> and &nbsp; and &amp;", content_type="text")
    >>> text2.content
    '&lt;b&gt; and &amp;nbsp; and &amp;amp;'
    >>> html = FeedTypedData("<b> and &nbsp; and &amp;", content_type="html")
    >>> html.content
    '&lt;b&gt; and &amp;nbsp; and &amp;amp;'

Since xhtml is valid xml, the "<" and ">" characters do not need to be
escaped. However, xhtml supports many more entities than xml, and Internet
Explorer 7 does not allow a DTD to be specified in feeds which prevents the
xhtml entities from easily being registered in the xml document. Therefore,
the xhtml entities will be converted to valid UTF-8. Since some simplistic
feed readers may expect ascii, we prefer using "html" over "xhtml", however,
we are testing xhtml encoding here in case we need it in the future.

    >>> xhtml = FeedTypedData("<b> and &nbsp; and &amp;</b><hr/>",
    ...               content_type="xhtml")
    >>> xhtml.content
    u'<b> and \xa0 and &</b><hr />'


== validate_feed() helper function ==

Pagetests can use the validate_feed() function to perform all the
checks available at http://feedvalidator.org

Occasionally, there will be suggestions from feedvalidator that we will
ignore. For example, when the <title type="text"> element contains html,
we want to view the html as opposed to having the title text formatted.
Therefore, we won't set type="html" for the title element.

    >>> feed = """<?xml version="1.0" encoding="UTF-8"?>
    ... <feed xmlns="http://www.w3.org/2005/Atom" xml:lang="en">
    ... <id>one</id>
    ... <title>Bugs in Launchpad itself</title>
    ... <link rel="self" href="http://foo.bar" />
    ... <updated>2006-05-19T06:37:40.344941+00:00</updated>
    ... <entry>
    ...     <id>http://launchpad.dev/entry</id>
    ...     <author></author>
    ...     <updated>2007-05-19T06:37:40.344941+00:00</updated>
    ...     <title type="text">&lt;b&gt;hello&lt;/b&gt;</title>
    ...     <content type="html">&lt;b&gt;hello&lt;/b&gt;</content>
    ... </entry>
    ... </feed>"""
    >>> from lp.services.feeds.tests.helper import validate_feed
    >>> validate_feed(feed, '/atom+xml', 'http://ubuntu.com')
    -------- Error: InvalidFullLink --------
    Backupcolumn: 7
    Backupline: 3
    Column: 7
    Element: id
    Line: 3
    Parent: feed
    Value: one
    =
      1: <?xml version="1.0" encoding="UTF-8"?>
      2: <feed xmlns="http://www.w3.org/2005/Atom" xml:lang="en">
      3: <id>one</id>
       : ~~~~~~~^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
      4: <title>Bugs in Launchpad itself</title>
      5: <link rel="self" href="http://foo.bar" />
    =
    -------- Error: MissingElement --------
    Backupcolumn: 12
    Backupline: 9
    Column: 12
    Element: name
    Line: 9
    Parent: author
    =
      7: <entry>
      8:     <id>http://launchpad.dev/entry</id>
      9:     <author></author>
       : ~~~~~~~~~~~~^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     10:     <updated>2007-05-19T06:37:40.344941+00:00</updated>
     11:     <title type="text">&lt;b&gt;hello&lt;/b&gt;</title>
    =
    -------- Warning: UnexpectedContentType --------
    Contenttype: /atom+xml
    Type: Feeds
    -------- Warning: SelfDoesntMatchLocation --------
    Backupcolumn: 41
    Backupline: 5
    Column: 41
    Element: href
    Line: 5
    Parent: feed
    Location: http://ubuntu.com
    =
      3: <id>one</id>
      4: <title>Bugs in Launchpad itself</title>
      5: <link rel="self" href="http://foo.bar" />
       : ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^~~~~~~~~~~~~~~~~~~~~~~~~
      6: <updated>2006-05-19T06:37:40.344941+00:00</updated>
      7: <entry>
    =
    -------- Warning: ContainsUndeclaredHTML --------
    Backupcolumn: 47
    Backupline: 11
    Column: 47
    Element: title
    Line: 11
    Parent: entry
    Value: b
    =
      9:     <author></author>
     10:     <updated>2007-05-19T06:37:40.344941+00:00</updated>
     11:     <title type="text">&lt;b&gt;hello&lt;/b&gt;</title>
       : ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^~~~~~~~~~~~~~~~~~~
     12:     <content type="html">&lt;b&gt;hello&lt;/b&gt;</content>
     13: </entry>
    =