diff -r 000000000000 -r b97547f5f1fa interfaces.py
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/interfaces.py	Wed Nov 05 15:52:50 2008 +0100
@@ -0,0 +1,234 @@
+"""Specific views for entities implementing IDownloadable
+
+:organization: Logilab
+:copyright: 2001-2008 LOGILAB S.A. (Paris, FRANCE), all rights reserved.
+:contact: http://www.logilab.fr/ -- mailto:contact@logilab.fr
+"""
+
+__docformat__ = "restructuredtext en"
+
+from logilab.common.interface import Interface
+
+class IEmailable(Interface):
+    """interface for emailable entities"""
+    
+    def get_email(self):
+        """return email address"""
+
+    @classmethod
+    def allowed_massmail_keys(cls):
+        """returns a set of allowed email substitution keys
+
+        The default is to return the entity's attribute list but an
+        entity class might override this method to allow extra keys.
+        For instance, the Person class might want to return a `companyname`
+        key.
+        """
+
+    def as_email_context(self):
+        """returns the dictionary as used by the sendmail controller to
+        build email bodies.
+        
+        NOTE: the dictionary keys should match the list returned by the
+        `allowed_massmail_keys` method.
+        """
+
+
+class IWorkflowable(Interface):
+    """interface for entities dealing with a specific workflow"""
+
+    @property
+    def state(self):
+        """return current state"""
+
+    def change_state(self, stateeid, trcomment=None, trcommentformat=None):
+        """change the entity's state according to a state defined in given
+        parameters
+        """
+    
+    def can_pass_transition(self, trname):
+        """return true if the current user can pass the transition with the
+        given name
+        """
+    
+    def latest_trinfo(self):
+        """return the latest transition information for this entity
+        """
+
+class IProgress(Interface):
+    """something that has a cost, a state and a progression
+
+    Take a look at cubicweb.common.mixins.ProgressMixIn for some
+    default implementations
+    """
+
+    @property
+    def cost(self):
+        """the total cost"""
+
+    @property
+    def done(self):
+        """what is already done"""
+
+    @property
+    def todo(self):
+        """what remains to be done"""
+    
+    def progress_info(self):
+        """returns a dictionary describing progress/estimated cost of the
+        version.
+
+        mandatory keys are (''estimated', 'done', 'todo')
+        optional keys are ('notestimated', 'notestimatedcorrected',
+                           'estimatedcorrected')
+       'noestimated' and 'notestimatedcorrected' should default to 0
+       'estimatedcorrected' should default to 'estimated'
+       """
+
+    def finished(self):
+        """returns True if status is finished"""
+
+    def in_progress(self):
+        """returns True if status is not finished"""
+
+    def progress(self):
+        """returns the % progress of the task item"""
+        
+    
+class IMileStone(IProgress):
+    """represents an ITask's item"""
+    
+    parent_type = None # specify main task's type
+    
+    def get_main_task(self):
+        """returns the main ITask entity"""
+
+    def initial_prevision_date(self):
+        """returns the initial expected end of the milestone"""
+        
+    def eta_date(self):
+        """returns expected date of completion based on what remains
+        to be done
+        """
+
+    def completion_date(self):
+        """returns date on which the subtask has been completed"""
+
+    def contractors(self):
+        """returns the list of persons supposed to work on this task"""
+
+
+class ITree(Interface):
+
+    def parent(self):
+        """returns the parent entity"""
+
+    def children(self):
+        """returns the item's children"""
+
+    def __iter__(self):
+        """iterates over the item's children"""
+        
+    def is_leaf(self):
+        """returns true if this node as no child"""
+
+    def is_root(self):
+        """returns true if this node has no parent"""
+
+    def root(self):
+        """return the root object"""
+
+
+## web specific interfaces ####################################################
+
+
+class IPrevNext(Interface):
+    """interface for entities which can be linked to a previous and/or next
+    entity
+    """
+    
+    def next_entity(self):
+        """return the 'next' entity"""
+    def previous_entity(self):
+        """return the 'previous' entity"""
+
+
+class IBreadCrumbs(Interface):
+    """interface for entities which can be "located" on some path"""
+    
+    def breadcrumbs(self, view, recurs=False):
+        """return a list containing some:
+        
+        * tuple (url, label)
+        * entity
+        * simple label string
+
+        defining path from a root to the current view
+
+        the main view is given as argument so breadcrumbs may vary according
+        to displayed view (may be None). When recursing on a parent entity,
+        the `recurs` argument should be set to True.
+        """
+
+
+class IDownloadable(Interface):
+    """interface for downloadable entities"""
+    
+    def download_url(self): # XXX not really part of this interface
+        """return an url to download entity's content"""
+    def download_content_type(self):
+        """return MIME type of the downloadable content"""
+    def download_encoding(self):
+        """return encoding of the downloadable content"""
+    def download_file_name(self):
+        """return file name of the downloadable content"""
+    def download_data(self):
+        """return actual data of the downloadable content"""
+
+
+class IEmbedable(Interface):
+    """interface for embedable entities"""
+    
+    def embeded_url(self):
+        """embed action interface"""
+    
+class ICalendarable(Interface):
+    """interface for itms that do have a begin date 'start' and an end
+date 'stop'"""    
+    
+class ICalendarViews(Interface):
+    """calendar views interface"""
+    def matching_dates(self, begin, end):
+        """
+        :param begin: day considered as begin of the range (`DateTime`)
+        :param end: day considered as end of the range (`DateTime`)
+        
+        :return:
+          a list of dates (`DateTime`) in the range [`begin`, `end`] on which
+          this entity apply
+        """
+        
+class ITimetableViews(Interface):
+    """timetable views interface"""
+    def timetable_date(self):
+        """XXX explain
+        
+        :return: date (`DateTime`)
+        """
+
+class IGeocodable(Interface):
+    """interface required by geocoding views such as gmap-view"""
+
+    @property
+    def latitude(self):
+        """returns the latitude of the entity"""
+
+    @property
+    def longitude(self):
+        """returns the longitude of the entity"""
+
+    def marker_icon(self):
+        """returns the icon that should be used as the marker
+        (returns None for default)
+        """
+