--- /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)
+ """
+