root/tags/amplee-0.5.0/amplee/atompub/member/__init__.py

# -*- coding: utf-8 -*-

__doc__ = """
APP establishes uses the term of members to describe
resources within an APP service context.

APP says:
'''
A resource whose IRI is listed in a Collection by a link
element with a relation of "edit" or "edit-media". 
'''

The base member is the what amplee calls the EntryMember
which is the resource whose IRI is contained in the
link defined by rel="edit".

The EntryMember should be rarerly used directly has it is
only meaningful if your resource is an Atom entry document.

On the other hand the MediaMember describes the resource
whose IRI is contained in the link defined by rel="edit-media".

The Mediamember will certainly be the most common class to
inherit for your own member implementations.
"""

__all__ = ['MemberResource']

import os.path
from xml.parsers.expat import ExpatError
from urlparse import urljoin, urlparse
from urllib import quote

from bridge import Element as E
from bridge import Attribute as A
from bridge import Document, PI
from bridge.filter.atom import lookup_links
from amplee.utils import generate_uuid_uri, get_isodate, safe_quote, safe_unquote, safe_url_join
from amplee.comparer import app_edited_comparer
from amplee.error import ResourceOperationException

from bridge.common import ATOM10_PREFIX, ATOMPUB_PREFIX, XML_PREFIX, XML_NS, \
     ATOM10_NS, ATOMPUB_NS, XHTML1_NS, XHTML1_PREFIX, atom_as_attr, atom_as_list, \
     atom_attribute_of_element

class MemberResource(object):
    def __init__(self, collection, id=None, atom=None):
        """
        Keyword Arguments:
        collection -- AtomPubCollection instance holding this member
        id -- identifier for this member
        atom -- bridge.Element instance
        """
        self.collection = collection
        self.entry = atom
        self.member_id = id
        self.media_id = None
        self.media_type = u'application/atom+xml;type=entry'
        self.draft = False
        self.comparer = app_edited_comparer
        self.xslt_path = None
        
    def __cmp__(self, other):
        """By default members are compared following their app:edited element"""
        return self.comparer(self, other)
        
    def _getentry(self):
        if self.entry is None:
            # Lazy loading of the atom entry
            info = self.collection.get_meta_data_info(self.member_id)
            source = self.collection.get_meta_data(info)
            self.entry = E.load(source, as_attribute=atom_as_attr, as_list=atom_as_list,
                                as_attribute_of_element=atom_attribute_of_element).xml_root
        return self.entry

    def _setentry(self, entry):
        raise AttributeError("Cannot overwrite the underlying Atom entry")

    def _delentry(self):
        raise AttributeError("Cannot delete the underlying Atom entry")
    
    atom = property(_getentry, _setentry, _delentry)

    def _getmediacontent(self):
        return self.collection.get_content(self.collection.get_info(self.media_id))

    def _setmediacontent(self, entry):
        raise AttributeError("Cannot overwrite the underlying content")

    def _delmediacontent(self):
        raise AttributeError("Cannot delete the media content")
    
    content = property(_getmediacontent, _setmediacontent, _delmediacontent)

    # For the pickling of this class
    def __getstate__(self):
        return {'member_id': self.member_id,
                'media_id': self.media_id,
                'media_type': self.media_type}
                #'entry': self.atom.xml(indent=False)}

    def __setstate__(self, state):
        self.entry = None
        self.member_id = state['member_id']
        self.media_id = state['media_id']
        self.media_type = state['media_type']
        #self.entry = E.load(state['entry'], as_attribute=atom_as_attr, as_list=atom_as_list,
        #                    as_attribute_of_element=atom_attribute_of_element).xml_root

    def from_entry(self, entry):
        """Allows the filling of the current instance from an Atom entry.

        This will lookup for two links:
         * rel='edit'
         * rel='edit-media'
        """
        
        self.entry = entry
        
        edit_links = self.entry.filtrate(lookup_links, rel='edit')
        if edit_links:
            href = edit_links[0].get_attribute('href')
            if href:
                self.member_id = safe_unquote(os.path.split(urlparse(unicode(href))[2])[-1])
            self.media_type = u'application/atom+xml;type=entry'
            
        edit_media_links = self.entry.filtrate(lookup_links, rel='edit-media')
        if edit_media_links:
            href = edit_media_links[0].get_attribute('href')
            if href:
                self.media_id = safe_unquote(os.path.split(urlparse(unicode(href))[2])[-1])
            media_type = edit_media_links[0].get_attribute('type')
            if media_type:
                self.media_type = unicode(media_type)
        elif self.member_id:
            self.media_id = self.collection.convert_id(self.member_id)[-1]

        self.draft = self.is_draft()

    def set_xslt(self, info):
        """
        Sets the XSLT to associate to the Atom entry. A processing
        instruction will be inserted when tge self.xml() method is
        called.

        The ``path`` is a URI to the the XSLT resource. 
        """
        self.xslt_path = path

    def xml(self):
        """Returns the serialization as a string of the atom entry."""
        if self.xslt_path:
            d = Document()
            PI(target=u'xml-stylesheet', data=u'href="%s" type="text/xsl"' % self.xslt_path, parent=d)
            d.xml_children.append(self.entry)
            return d.xml()

        return self.entry.xml()
    
    def load_document(self, source):
        try:
            doc = E.load(source, as_attribute=atom_as_attr, as_list=atom_as_list,
                         as_attribute_of_element=atom_attribute_of_element).xml_root
        except ExpatError, er:
            raise ResourceOperationException("Could not parse posted Atom entry", 400, body=str(er))

        # Let's ensure of the correctness of the namespace mapping
        doc.update_prefix(ATOM10_PREFIX, doc.xml_ns, ATOM10_NS, update_attributes=False)

        return doc

    def update_dates(self):
        entry = self.entry
        isodate = get_isodate()
        
        updated = entry.get_child('updated', entry.xml_ns)
        if updated is not None:
            updated.xml_text = isodate
        else:
            E(u'updated', content=isodate, prefix=entry.xml_prefix,
              namespace=entry.xml_ns, parent=entry)

        edited = entry.get_child('edited', ATOMPUB_NS)
        if edited is not None:
            edited.xml_text = isodate
        else:
            E(u'edited', content=isodate, prefix=ATOMPUB_PREFIX,
              namespace=ATOMPUB_NS, parent=entry)

    def merge_dates(self, new_member):
        entry = self.entry
        new_entry = new_member.atom

        updated = entry.get_child('updated', entry.xml_ns)
        isodate = get_isodate()
        if updated is not None:
            updated.xml_text = isodate
        else:
            E(u'updated', content=isodate, prefix=entry.xml_prefix,
              namespace=entry.xml_ns, parent=entry)
            
        new_edited = new_entry.get_child('edited', ATOMPUB_NS)
        if new_edited:
            edited = entry.get_child('edited', ATOMPUB_NS)
            if edited is not None:
                edited.xml_text = new_edited.xml_text
            else:
                E(u'edited', content=new_edited.xml_text, prefix=ATOMPUB_PREFIX,
                  namespace=ATOMPUB_NS, parent=entry)

    def prepare_for_public(self, content=None, external_content=False,
                           rel=u'alternate', media_type=u'text/html',
                           xslt_path=None):
        clone = self.entry.clone().xml_root
        xml_base = self.collection.get_xml_base()
        if xml_base:
            A(u'base', value=xml_base, namespace=XML_NS, prefix=XML_PREFIX, parent=clone)

        edited = clone.get_child('edited', ATOMPUB_NS)
        if edited: edited.forget()
        
        control = clone.get_child('control', ATOMPUB_NS)
        if control: control.forget()

        links = clone.filtrate(lookup_links, rel="edit")
        if links: links[0].forget()
        
        links = clone.filtrate(lookup_links, rel="edit-media")
        if links: links[0].forget()

        # link rel="self"
        if xml_base:
            href = safe_url_join([self.collection.base_uri, self.member_id])
        else:
            href = safe_url_join([self.collection.get_base_uri(), self.member_id])
        links = clone.filtrate(lookup_links, rel="self")
        if links:
            links[0].href = href
            links[0].type = u'application/atom+xml;type=entry'
        else:
            E(u'link', attributes={u'rel': u'self', u'type': u'application/atom+xml;type=entry',
                                   u'href': href},
              namespace=clone.xml_ns, prefix=clone.xml_prefix, parent=clone)

            
        # link rel="%s" % rel
        if self.media_id:
            if xml_base:
                href = safe_url_join([self.collection.base_uri, self.media_id])
            else:
                href = self.public_uri
                
            links = clone.filtrate(lookup_links, rel=rel)
            if links:
                links[0].href = href
                links[0].type = media_type
            else:
                E(u'link', attributes={u'rel': rel, u'type': media_type, u'href': href},
                  namespace=clone.xml_ns, prefix=clone.xml_prefix, parent=clone)

        ct = clone.get_child('content', clone.xml_ns)
        if ct: ct.forget()

        if external_content:
            if xml_base:
                src = safe_url_join([self.collection.base_uri, self.media_id])
            else:
                src = self.public_uri
            attr = {u'src': src, u'type': media_type}
            E(u'content', attributes=attr, namespace=clone.xml_ns,
              prefix=clone.xml_prefix, parent=clone)
        elif content:
            ct = E(u'content', attributes={u'type': u'xhtml'},
                   namespace=clone.xml_ns, prefix=clone.xml_prefix, parent=clone)
            content = '<div xmlns="%s">%s</div>'  % (XHTML1_NS, content)
            div = E.load(content).xml_root
            ct.xml_children.append(div)
            div.xml_parent = ct

        d = Document()
        if xslt_path:
            PI(target=u'xml-stylesheet', data=u'href="%s" type="text/xsl"' % xslt_path, parent=d)

        d.xml_children.append(clone)
        
        return d

    def index(self):
        """Passes the member to the collection indexers"""
        if self.collection:
            for indexer in self.collection.indexers:
                indexer.process(self)

    def get_public_uri(self):
        """Returns a URI suitable for public feed and independant from the collection URI"""
        if self.member_id:
            return safe_url_join([self.collection.get_base_uri(),
                                  self.media_id], start_at=1)
    public_uri = property(get_public_uri)

    def get_public_stripped_uri(self):
        """Returns a URI suitable for public feed and independant from the collection URI.
        It removes any trailing extension there may be.
        """
        public_uri = self.public_uri
        if public_uri:
            public_uri, ext = os.path.splitext(public_uri)
            return public_uri
    public_uri_stripped = property(get_public_uri)

    def get_edit_uri(self):
        """Returns the URI of the member resource"""
        if self.member_id:
            return safe_url_join([self.collection.get_base_edit_uri(),
                                  self.member_id], start_at=1)
    member_uri = property(get_edit_uri)
    
    def get_edit_media_uri(self):
        """Returns the URI of the media link entry (MLE)"""
        if self.media_id:
            return safe_url_join([self.collection.get_base_media_edit_uri(),
                                  self.media_id], start_at=1)
    media_uri = property(get_edit_media_uri)
      
    def is_draft(self):
        """
        Returns True is the entry has a app:control element with an
        app:draft element which has a text value set to 'yes'. Returns False
        otherwise.
        """
        app_ctrl_element = self.entry.get_child('control', ATOMPUB_NS)
        if app_ctrl_element:
            app_draft = app_ctrl_element.get_child('draft', ATOMPUB_NS)
            if app_draft and app_draft.xml_text and app_draft.xml_text.lower() == u'yes':
                return True
        return False
    
    ############################################################
    # API to implement per your application requirements
    ############################################################
    def generate_atom_id(self, entry=None, slug=None):
        """
        Called to generate a valid atom identifier (a valid URI)
        which will be used within the Atom entry itself.

        By default this returns a random urn:uuid value.
        """
        return generate_uuid_uri()

    def generate_resource_id(self, entry, slug=None):
        """
        Called to generate a token that will be used as the internal
        identifier for this member within its collection. Also
        used as the identifier within the storage it will be added
        to which means the returned value should be valid for the
        chosen storage.

        By default this returns the atom:id value of the member entry.
        """
        atom_id = entry.get_child('id', ATOM10_NS)
        return atom_id.xml_text

    def create(self, source, slug=None):
        """
        Called to generate the member entry from the atom entry
        provided in the source parameter.

        This must return the source again after being processed
        if need be within the method call. The content can be returned
        either as a byte string, unicode or a file object.
        
        Keyword arguments:
        source -- resource string to handle
        
        slug -- hint on how to generate the name of the resource and
        used as the last part of the edit and edit-media IRIs (default:None)
        """
        raise NotImplemented()

    def update(self, source, exisiting_member):
        """
        Called to generate the new member entry from the atom entry
        provided in the source parameter as well as from the
        existing member in the store.
        
        This must return the source again after being processed
        if need be within the method call. The content can be returned
        either as a byte string, unicode or a file object.
        
        Keyword arguments:
        source -- resource string to handle
        exisiting_member -- member instance of an existing member resource
        """
        raise NotImplemented()