Revised interfaces in relation with variation handling. variated and variation...

Revised interfaces in relation with variation handling. variated and variation range are now split, in order to exhibit the difference between leaf movements (ex. Delivery Cell) and movement containers (ex. Delivery Line whenever it contains Delivery Cells). APIs need more revision, with some parameters currently missing and a few not relevant.

git-svn-id: https://svn.erp5.org/repos/public/erp5/trunk@33138 20353a03-c40f-0410-a6d1-a30d3c3de9de

product/ERP5/interfaces/mapped_value.py

+# -*- coding: utf-8 -*-
+##############################################################################
+#
+# Copyright (c) 2010 Nexedi SA and Contributors. All Rights Reserved.
+#                    Jean-Paul Smets-Solanes <jp@nexedi.com>
+#
+# WARNING: This program as such is intended to be used by professional
+# programmers who take the whole responsability of assessing all potential
+# consequences resulting from its eventual inadequacies and bugs
+# End users who are looking for a ready-to-use solution with commercial
+# garantees and support are strongly adviced to contract a Free Software
+# Service Company
+#
+# This program is Free Software; you can redistribute it and/or
+# modify it under the terms of the GNU General Public License
+# as published by the Free Software Foundation; either version 2
+# of the License, or (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
+#
+##############################################################################
+
+from Products.ERP5.interfaces.predicate import IPredicate
+
+_MARKER = []
+
+class IMappedValue(IPredicate):
+  """Mapped Value document interface specification
+
+  A Mapped Value provides 
+  """
+  def getMappedValuePropertyList():
+    """
+    """
+
+  def getMappedValueBaseCategoryList():
+    """
+    """
+
+  def getProperty(key, d=_MARKER, **kw):
+    """
+    """
+
+  def getPropertyList(key, d=None):
+    """
+    XXX- useful ?
+    """
+
+  def getAcquiredCategoryMembershipList(category, spec=(), filter=None,
+      portal_type=(), base=0, keep_default=1, checked_permission=None, **kw):
+    """
+    """
+
+
+

product/ERP5/interfaces/predicate.py

 # -*- coding: utf-8 -*-
 ##############################################################################
 #
-# Copyright (c) 2002 Nexedi SARL and Contributors. All Rights Reserved.
+# Copyright (c) 2002-2010 Nexedi SA and Contributors. All Rights Reserved.
 #                    Jean-Paul Smets-Solanes <jp@nexedi.com>
 #
 # WARNING: This program as such is intended to be used by professional
@@ -33,31 +33,38 @@ Products.ERP5.interfaces.predicate
 from zope.interface import Interface
 
 class IPredicate(Interface):
-  """
-    A Predicate allows to make a statement about a document.
-    A statement can be related to:
+  """Predicate document interface specification
+
+  A Predicate allows to make a statement about a document.
+  A statement can be related to:
 
-    - the attributes of the document (ex. price >= 3.0)
+  - the attributes of the document (ex. price >= 3.0)
 
-    - the categories of the document (ex. )
+  - the categories of the document (ex. )
 
-    The Predicate class is an abstract class, which is
-    implemented by subclasses.
+  The Predicate class is an abstract class, which is
+  implemented by subclasses.
   """
 
   def test(context, tested_base_category_list=None):
-    """A Predicate can be tested on a given context.
-
-      Parameters can passed in order to ignore some conditions:
-      - tested_base_category_list:  this is the list of category that we do
+    """
+    A Predicate can be tested on a given context. Parameters can
+    passed in order to ignore some conditions:
+    
+    tested_base_category_list -- a list of category that we do
         want to test. For example, we might want to test only the
         destination or the source of a predicate.
+        (XXX-JPS - is this really needed ? is this appropriate
+         naming - probably not)
     """
 
   def asSQLExpression():
     """
-      A Predicate can be rendered as an sql expression. This
-      can be useful to create reporting trees based on the
-      ZSQLCatalog
-    """
-
+    A Predicate can be rendered as an sql expression. This
+    can be useful to create reporting trees based on the
+    ZSQLCatalog. This SQL expression is however partial since
+    python scripts which are used by the test method of the predicate
+    can be converted to SQL. If a python script is defined to 
+    implement test, results obtained through asSQLExpression
+    must be additionnaly tested by invoking test().
+    """
\ No newline at end of file

product/ERP5/interfaces/variated.py

 # -*- coding: utf-8 -*-
 ##############################################################################
 #
-# Copyright (c) 2002 Nexedi SARL and Contributors. All Rights Reserved.
+# Copyright (c) 2002-2010 Nexedi SA and Contributors. All Rights Reserved.
 #                    Jean-Paul Smets-Solanes <jp@nexedi.com>
 #
 # WARNING: This program as such is intended to be used by professional
@@ -33,9 +33,21 @@ Products.ERP5.interfaces.variated
 from zope.interface import Interface
 
 class IVariated(Interface):
-  """
-    Common Interface for all objects which can be
-    variated.
+  """IVariated interface specification
+
+  IVariated defines methods to access and modify
+  discrete variations (categories) and variation
+  properties. It also provides variation range methods
+  which are often invoked from variated objects.
+
+  IVariated is normally used to specify discrete variations
+  of a movement.
+
+  IVariated is also used on all objects which define
+  a variation range, such as Resources, Delivery Lines
+  which contain Delivery Cells. In this case, categories
+  specify a subset of the total variation range, rather
+  than a specific discrete variation.
   """
 
   # The following methods are intended to access to the
@@ -43,76 +55,213 @@ class IVariated(Interface):
   # are based on categories. General variations are encapsulated
   # into VariationValue instances.
 
-  # Discrete Variation accessors
-  def getVariationCategoryList():
+  # Discrete Variation Accessors
+  def getVariationBaseCategoryList(omit_optional_variation=0,
+                                   omit_individual_variation=0):
+    """
+    returns a list of base category ids which are used
+    to define discrete variation dimensions for this instance
+
+    Used in: Resource, Delivery Line, Delivery Cell
+
+    omit_optional_variation -- 
+
+    omit_individual_variation --
     """
-      returns a list or relative URLs which defines
-      a discrete variation (ie. a list of category
-      memberships)
+
+  def getVariationBaseCategoryItemList(self, display_id='title_or_id',
+        omit_optional_variation=0, omit_individual_variation=0):
+    """
+    returns a list of (base_category.id, base_category.display_id())
+    which can be displayed in an ERP5 Form and define 
+    to define discrete variation dimensions for this instance
+
+    Used in: Resource, Delivery Line, Delivery Cell
+
+    display_id -- 
+
+    omit_optional_variation -- 
+
+    omit_individual_variation --
+    """
+
+  def getVariationCategoryList(self, base_category_list=(),
+        omit_optional_variation=0, omit_individual_variation=0):
     """
+    returns a list or relative URLs which defines
+    a discrete variation (ie. a list of category
+    memberships)
+
+    Used in: Resource, Delivery Line, Delivery Cell
+
+    base_category_list --
+
+    omit_optional_variation -- 
+
+    omit_individual_variation --
+    """
+
+  def setVariationCategoryList(node_list, base_category_list=()):
+    """
+    modifies the discrete variation of a variated instance by
+    providing a list of relative URLs
+
+    Used in: Resource, Delivery Line, Delivery Cell
+
+    base_category_list --
+    """
+
+  def getVariationCategoryItemList(base_category_list=(), base=1,
+        display_id='logical_path', display_base_category=1,
+        current_category=None, omit_optional_variation=0,
+        omit_individual_variation=0, **kw):
+    """
+    returns a list of (category.getRelativeUrl(), category.display_id())
+    which define the discrete variations  of a variated instance
+    in a way which be displayed in an ERP5 Form.
+
+    Used in: Resource, Delivery Line, Delivery Cell
+
+    base_category_list --
+
+    base --
 
-  def setVariationCategoryList(node_list):
+    display_id --
+
+    display_base_category --
+
+    base_category_list --
+
+    current_category --
+
+    omit_optional_variation --
+
+    omit_individual_variation --
+
+    **kw -- 
     """
-      modifies the discrete variation of an
-      variated instance by providing a list
-      of relative URLs
+
+  # Discrete Variation Range Accessors
+  def getVariationRangeBaseCategoryList():
     """
+    returns a list of base categories which are acceptable
+    as discrete variation dimensions
 
-  def getVariationBaseCategoryList(node_list):
+    Used in: Resource, Delivery Line, Delivery Cell
     """
-      returns a list of base category ids
-      which are used to define discrete variations
-      for this instance
+
+  def getVariationRangeBaseCategoryItemList(base=1, 
+                                            display_id='getTitle'):
     """
+    returns a list of (base_category.id, base_category.display_id())
+    which are acceptable as discrete variation dimensions of
+    the variated instance and are easy to display in an ERP5Form
+    
+    Used in: Resource, Delivery Line, Delivery Cell
 
-  def setVariationBaseCategoryList(node_list):
+    display_id --
     """
-      modifies the list of base category ids
-      which are used to define discrete variations
-      for this instance
+
+  def getVariationRangeCategoryList(base_category_list=(), base=1,
+        root=1, current_category=None, omit_individual_variation=0):
     """
+    returns a list of categories which are acceptable
+    as discrete variation values of the current variated instance
+
+    Used in: Resource, Delivery Line, Delivery Cell
+
+    base_category_list -- 
+
+    base -- 
 
-  # General Variation accessors
-  def getVariationValue():
+    root -- 
+
+    current_category -- 
+
+    omit_individual_variation -- 
     """
-      Returns a VariationValue object. 
+
+  def getVariationRangeCategoryItemList(base_category_list=(), base=1, 
+        root=1, display_method_id='getCategoryChildLogicalPathItemList',
+        display_base_category=1, current_category=None, **kw):
     """
+    returns a list of (category.id, category.display_id()) which are acceptable
+    as discrete variation values. This is mostly useful in ERP5Form 
+    instances to generate selection menus.
+
+    Used in: Resource, Delivery Line, Delivery Cell
 
-  def setVariationValue(value):
+    base_category_list -- 
+
+    base -- 
+
+    root -- 
+
+    display_method_id -- 
+
+    display_base_category -- 
+
+    current_category -- 
+
+    **kw --
     """
-      Sets the VariationValue.
+
+  # Variated Value API
+  def setVariated(variated):
     """
+    Sets all variation categories and properties of the current
+    variated instance to the categories and properties of
+    variated instance provided as parameter.
 
+    Used in: Resource, Delivery Line, Delivery Cell
 
-  # The following methods are intended to access the
-  # variation range of a variated object. A Variation range can
-  # be defined in a Resource instance or in any object
-  # which has a relation with a Resource (Amount, Transformation)
+    variated -- 
+    """
 
-  # Discrete Variation Range accessors
+  def compareVariated(variated):
+    """
+    Compares current variated instance with another
+    variated instance provided as parameter.
+
+    Used in: Resource, Delivery Line, Delivery Cell
 
-  def getVariationRangeCategoryList(base_category_list=(), base=1):
+    variated --     
     """
-      returns a list of categories which are acceptable
-      as discrete variation values
+
+  # Serialization API
+  def getVariationText(self):
     """
+    returns a human readable, computer parsable,
+    non ambiguous string representation of the variation
+    categories and properties of the current instance.
 
-  def getVariationRangeCategoryItemList(base_category_list=(),
-                          display_id='getTitle', base=1, current_category=None):
+    Used in: Delivery Line (terminal), Delivery Cell
     """
-      returns a list of (category.id, category.display_id()) which are acceptable
-      as discrete variation values
+
+  def setVariationText(variation_text):
     """
+    parses variation_text to set variation properties
+    and categories of the current instance
 
-  def getVariationRangeBaseCategoryList(base_category_list=(), base=1):
+    Used in: Delivery Line (terminal), Delivery Cell
+    Could be used in: Resource, Delivery Line (non terminal)
     """
-      returns a list of base categories which are acceptable
-      as discrete variation values
+
+  def setVariationUid():
     """
+    returns a unique UID integer representation of the variation
+    categories and properties of the current instance based
+    on a UID mapping of variation_text
 
-  def getVariationRangeBaseCategoryItemList(base_category_list=(),
-                          display_id='getTitle', base=1, current_category=None):
+    Used in: Delivery Line (terminal), Delivery Cell
+    Could be used in: Resource, Delivery Line (non terminal)
     """
-      returns a list of base category items which are acceptable
-      as discrete variation values
+
+  def setVariationUid(variation_uid):
     """
+    sets variation properties and categories of the current instance
+    by looking up variation to UID mapping
+
+    Used in: Delivery Line (terminal), Delivery Cell
+    Could be used in: Resource, Delivery Line (non terminal)
+    """
\ No newline at end of file

product/ERP5/interfaces/variation_range.py

+# -*- coding: utf-8 -*-
+##############################################################################
+#
+# Copyright (c) 2002-2010 Nexedi SA and Contributors. All Rights Reserved.
+#                    Jean-Paul Smets-Solanes <jp@nexedi.com>
+#
+# WARNING: This program as such is intended to be used by professional
+# programmers who take the whole responsability of assessing all potential
+# consequences resulting from its eventual inadequacies and bugs
+# End users who are looking for a ready-to-use solution with commercial
+# garantees and support are strongly adviced to contract a Free Software
+# Service Company
+#
+# This program is Free Software; you can redistribute it and/or
+# modify it under the terms of the GNU General Public License
+# as published by the Free Software Foundation; either version 2
+# of the License, or (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
+#
+##############################################################################
+"""
+Products.ERP5.interfaces.variated
+"""
+
+from zope.interface import Interface
+
+class IVariationRange(Interface):
+  """IVariationRange interface specification
+
+  Common Interface for all objects which define a variation
+  range.
+  """
+
+  # provides VariationRange accessors
+
+  # Discrete Variation Range Accessors
+  def setVariationBaseCategoryList(base_category_id_list):
+    """
+    modifies the list of base category ids which are used to
+    define discrete variation dimensions for this instance.
+    Normally provided by the VariationRange property sheet.
+
+    Used in: Resource, Delivery Line
+
+    base_category_id_list -- 
+    """
+
+  # Matrix Handling API
+  def getLineVariationRangeCategoryItemList():
+    """
+    returns possible variation dimensions displayed in line.
+
+    Used in: Resource, Delivery Line
+
+    XXX - missing default display ID
+    """
+
+  def getColumnVariationRangeCategoryItemList():
+    """
+    returns possible variation dimensions displayed in column
+
+    Used in: Resource, Delivery Line
+
+    XXX - missing default display ID
+    """
+
+  def getTabVariationRangeCategoryItemList():
+    """
+    returns possible variation dimensions displayed in tab
+
+    Used in: Resource, Delivery Line
+
+    XXX - missing default display ID
+    """
+
+  def getMatrixVariationRangeBaseCategoryList(self):
+    """
+    return possible variation dimensions for a matrix
+
+    Used in: Resource, Delivery Line
+
+    XXX - missing default display ID
+    """
\ No newline at end of file