path: root/python/werkzeug/contrib/atom.py

# -*- coding: utf-8 -*-
"""
    werkzeug.contrib.atom
    ~~~~~~~~~~~~~~~~~~~~~

    This module provides a class called :class:`AtomFeed` which can be
    used to generate feeds in the Atom syndication format (see :rfc:`4287`).

    Example::

        def atom_feed(request):
            feed = AtomFeed("My Blog", feed_url=request.url,
                            url=request.host_url,
                            subtitle="My example blog for a feed test.")
            for post in Post.query.limit(10).all():
                feed.add(post.title, post.body, content_type='html',
                         author=post.author, url=post.url, id=post.uid,
                         updated=post.last_update, published=post.pub_date)
            return feed.get_response()

    :copyright: 2007 Pallets
    :license: BSD-3-Clause
"""
import warnings
from datetime import datetime

from .._compat import implements_to_string
from .._compat import string_types
from ..utils import escape
from ..wrappers import BaseResponse

warnings.warn(
    "'werkzeug.contrib.atom' is deprecated as of version 0.15 and will"
    " be removed in version 1.0.",
    DeprecationWarning,
    stacklevel=2,
)

XHTML_NAMESPACE = "http://www.w3.org/1999/xhtml"


def _make_text_block(name, content, content_type=None):
    """Helper function for the builder that creates an XML text block."""
    if content_type == "xhtml":
        return u'<%s type="xhtml"><div xmlns="%s">%s</div></%s>\n' % (
            name,
            XHTML_NAMESPACE,
            content,
            name,
        )
    if not content_type:
        return u"<%s>%s</%s>\n" % (name, escape(content), name)
    return u'<%s type="%s">%s</%s>\n' % (name, content_type, escape(content), name)


def format_iso8601(obj):
    """Format a datetime object for iso8601"""
    iso8601 = obj.isoformat()
    if obj.tzinfo:
        return iso8601
    return iso8601 + "Z"


@implements_to_string
class AtomFeed(object):

    """A helper class that creates Atom feeds.

    :param title: the title of the feed. Required.
    :param title_type: the type attribute for the title element.  One of
                       ``'html'``, ``'text'`` or ``'xhtml'``.
    :param url: the url for the feed (not the url *of* the feed)
    :param id: a globally unique id for the feed.  Must be an URI.  If
               not present the `feed_url` is used, but one of both is
               required.
    :param updated: the time the feed was modified the last time.  Must
                    be a :class:`datetime.datetime` object.  If not
                    present the latest entry's `updated` is used.
                    Treated as UTC if naive datetime.
    :param feed_url: the URL to the feed.  Should be the URL that was
                     requested.
    :param author: the author of the feed.  Must be either a string (the
                   name) or a dict with name (required) and uri or
                   email (both optional).  Can be a list of (may be
                   mixed, too) strings and dicts, too, if there are
                   multiple authors. Required if not every entry has an
                   author element.
    :param icon: an icon for the feed.
    :param logo: a logo for the feed.
    :param rights: copyright information for the feed.
    :param rights_type: the type attribute for the rights element.  One of
                        ``'html'``, ``'text'`` or ``'xhtml'``.  Default is
                        ``'text'``.
    :param subtitle: a short description of the feed.
    :param subtitle_type: the type attribute for the subtitle element.
                          One of ``'text'``, ``'html'``, ``'text'``
                          or ``'xhtml'``.  Default is ``'text'``.
    :param links: additional links.  Must be a list of dictionaries with
                  href (required) and rel, type, hreflang, title, length
                  (all optional)
    :param generator: the software that generated this feed.  This must be
                      a tuple in the form ``(name, url, version)``.  If
                      you don't want to specify one of them, set the item
                      to `None`.
    :param entries: a list with the entries for the feed. Entries can also
                    be added later with :meth:`add`.

    For more information on the elements see
    http://www.atomenabled.org/developers/syndication/

    Everywhere where a list is demanded, any iterable can be used.
    """

    default_generator = ("Werkzeug", None, None)

    def __init__(self, title=None, entries=None, **kwargs):
        self.title = title
        self.title_type = kwargs.get("title_type", "text")
        self.url = kwargs.get("url")
        self.feed_url = kwargs.get("feed_url", self.url)
        self.id = kwargs.get("id", self.feed_url)
        self.updated = kwargs.get("updated")
        self.author = kwargs.get("author", ())
        self.icon = kwargs.get("icon")
        self.logo = kwargs.get("logo")
        self.rights = kwargs.get("rights")
        self.rights_type = kwargs.get("rights_type")
        self.subtitle = kwargs.get("subtitle")
        self.subtitle_type = kwargs.get("subtitle_type", "text")
        self.generator = kwargs.get("generator")
        if self.generator is None:
            self.generator = self.default_generator
        self.links = kwargs.get("links", [])
        self.entries = list(entries) if entries else []

        if not hasattr(self.author, "__iter__") or isinstance(
            self.author, string_types + (dict,)
        ):
            self.author = [self.author]
        for i, author in enumerate(self.author):
            if not isinstance(author, dict):
                self.author[i] = {"name": author}

        if not self.title:
            raise ValueError("title is required")
        if not self.id:
            raise ValueError("id is required")
        for author in self.author:
            if "name" not in author:
                raise TypeError("author must contain at least a name")

    def add(self, *args, **kwargs):
        """Add a new entry to the feed.  This function can either be called
        with a :class:`FeedEntry` or some keyword and positional arguments
        that are forwarded to the :class:`FeedEntry` constructor.
        """
        if len(args) == 1 and not kwargs and isinstance(args[0], FeedEntry):
            self.entries.append(args[0])
        else:
            kwargs["feed_url"] = self.feed_url
            self.entries.append(FeedEntry(*args, **kwargs))

    def __repr__(self):
        return "<%s %r (%d entries)>" % (
            self.__class__.__name__,
            self.title,
            len(self.entries),
        )

    def generate(self):
        """Return a generator that yields pieces of XML."""
        # atom demands either an author element in every entry or a global one
        if not self.author:
            if any(not e.author for e in self.entries):
                self.author = ({"name": "Unknown author"},)

        if not self.updated:
            dates = sorted([entry.updated for entry in self.entries])
            self.updated = dates[-1] if dates else datetime.utcnow()

        yield u'<?xml version="1.0" encoding="utf-8"?>\n'
        yield u'<feed xmlns="http://www.w3.org/2005/Atom">\n'
        yield "  " + _make_text_block("title", self.title, self.title_type)
        yield u"  <id>%s</id>\n" % escape(self.id)
        yield u"  <updated>%s</updated>\n" % format_iso8601(self.updated)
        if self.url:
            yield u'  <link href="%s" />\n' % escape(self.url)
        if self.feed_url:
            yield u'  <link href="%s" rel="self" />\n' % escape(self.feed_url)
        for link in self.links:
            yield u"  <link %s/>\n" % "".join(
                '%s="%s" ' % (k, escape(link[k])) for k in link
            )
        for author in self.author:
            yield u"  <author>\n"
            yield u"    <name>%s</name>\n" % escape(author["name"])
            if "uri" in author:
                yield u"    <uri>%s</uri>\n" % escape(author["uri"])
            if "email" in author:
                yield "    <email>%s</email>\n" % escape(author["email"])
            yield "  </author>\n"
        if self.subtitle:
            yield "  " + _make_text_block("subtitle", self.subtitle, self.subtitle_type)
        if self.icon:
            yield u"  <icon>%s</icon>\n" % escape(self.icon)
        if self.logo:
            yield u"  <logo>%s</logo>\n" % escape(self.logo)
        if self.rights:
            yield "  " + _make_text_block("rights", self.rights, self.rights_type)
        generator_name, generator_url, generator_version = self.generator
        if generator_name or generator_url or generator_version:
            tmp = [u"  <generator"]
            if generator_url:
                tmp.append(u' uri="%s"' % escape(generator_url))
            if generator_version:
                tmp.append(u' version="%s"' % escape(generator_version))
            tmp.append(u">%s</generator>\n" % escape(generator_name))
            yield u"".join(tmp)
        for entry in self.entries:
            for line in entry.generate():
                yield u"  " + line
        yield u"</feed>\n"

    def to_string(self):
        """Convert the feed into a string."""
        return u"".join(self.generate())

    def get_response(self):
        """Return a response object for the feed."""
        return BaseResponse(self.to_string(), mimetype="application/atom+xml")

    def __call__(self, environ, start_response):
        """Use the class as WSGI response object."""
        return self.get_response()(environ, start_response)

    def __str__(self):
        return self.to_string()


@implements_to_string
class FeedEntry(object):

    """Represents a single entry in a feed.

    :param title: the title of the entry. Required.
    :param title_type: the type attribute for the title element.  One of
                       ``'html'``, ``'text'`` or ``'xhtml'``.
    :param content: the content of the entry.
    :param content_type: the type attribute for the content element.  One
                         of ``'html'``, ``'text'`` or ``'xhtml'``.
    :param summary: a summary of the entry's content.
    :param summary_type: the type attribute for the summary element.  One
                         of ``'html'``, ``'text'`` or ``'xhtml'``.
    :param url: the url for the entry.
    :param id: a globally unique id for the entry.  Must be an URI.  If
               not present the URL is used, but one of both is required.
    :param updated: the time the entry was modified the last time.  Must
                    be a :class:`datetime.datetime` object.  Treated as
                    UTC if naive datetime. Required.
    :param author: the author of the entry.  Must be either a string (the
                   name) or a dict with name (required) and uri or
                   email (both optional).  Can be a list of (may be
                   mixed, too) strings and dicts, too, if there are
                   multiple authors. Required if the feed does not have an
                   author element.
    :param published: the time the entry was initially published.  Must
                      be a :class:`datetime.datetime` object.  Treated as
                      UTC if naive datetime.
    :param rights: copyright information for the entry.
    :param rights_type: the type attribute for the rights element.  One of
                        ``'html'``, ``'text'`` or ``'xhtml'``.  Default is
                        ``'text'``.
    :param links: additional links.  Must be a list of dictionaries with
                  href (required) and rel, type, hreflang, title, length
                  (all optional)
    :param categories: categories for the entry. Must be a list of dictionaries
                       with term (required), scheme and label (all optional)
    :param xml_base: The xml base (url) for this feed item.  If not provided
                     it will default to the item url.

    For more information on the elements see
    http://www.atomenabled.org/developers/syndication/

    Everywhere where a list is demanded, any iterable can be used.
    """

    def __init__(self, title=None, content=None, feed_url=None, **kwargs):
        self.title = title
        self.title_type = kwargs.get("title_type", "text")
        self.content = content
        self.content_type = kwargs.get("content_type", "html")
        self.url = kwargs.get("url")
        self.id = kwargs.get("id", self.url)
        self.updated = kwargs.get("updated")
        self.summary = kwargs.get("summary")
        self.summary_type = kwargs.get("summary_type", "html")
        self.author = kwargs.get("author", ())
        self.published = kwargs.get("published")
        self.rights = kwargs.get("rights")
        self.links = kwargs.get("links", [])
        self.categories = kwargs.get("categories", [])
        self.xml_base = kwargs.get("xml_base", feed_url)

        if not hasattr(self.author, "__iter__") or isinstance(
            self.author, string_types + (dict,)
        ):
            self.author = [self.author]
        for i, author in enumerate(self.author):
            if not isinstance(author, dict):
                self.author[i] = {"name": author}

        if not self.title:
            raise ValueError("title is required")
        if not self.id:
            raise ValueError("id is required")
        if not self.updated:
            raise ValueError("updated is required")

    def __repr__(self):
        return "<%s %r>" % (self.__class__.__name__, self.title)

    def generate(self):
        """Yields pieces of ATOM XML."""
        base = ""
        if self.xml_base:
            base = ' xml:base="%s"' % escape(self.xml_base)
        yield u"<entry%s>\n" % base
        yield u"  " + _make_text_block("title", self.title, self.title_type)
        yield u"  <id>%s</id>\n" % escape(self.id)
        yield u"  <updated>%s</updated>\n" % format_iso8601(self.updated)
        if self.published:
            yield u"  <published>%s</published>\n" % format_iso8601(self.published)
        if self.url:
            yield u'  <link href="%s" />\n' % escape(self.url)
        for author in self.author:
            yield u"  <author>\n"
            yield u"    <name>%s</name>\n" % escape(author["name"])
            if "uri" in author:
                yield u"    <uri>%s</uri>\n" % escape(author["uri"])
            if "email" in author:
                yield u"    <email>%s</email>\n" % escape(author["email"])
            yield u"  </author>\n"
        for link in self.links:
            yield u"  <link %s/>\n" % "".join(
                '%s="%s" ' % (k, escape(link[k])) for k in link
            )
        for category in self.categories:
            yield u"  <category %s/>\n" % "".join(
                '%s="%s" ' % (k, escape(category[k])) for k in category
            )
        if self.summary:
            yield u"  " + _make_text_block("summary", self.summary, self.summary_type)
        if self.content:
            yield u"  " + _make_text_block("content", self.content, self.content_type)
        yield u"</entry>\n"

    def to_string(self):
        """Convert the feed item into a unicode object."""
        return u"".join(self.generate())

    def __str__(self):
        return self.to_string()