Reviewed documentation of Amount interface and split the different parts of...

Reviewed documentation of Amount interface and split the different parts of the interface for better readabilit (although such parts are private).

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

product/ERP5/interfaces/amount.py

+# -*- coding: utf-8 -*-
 ##############################################################################
 #
 # Copyright (c) 2009 Nexedi SARL and Contributors. All Rights Reserved.
@@ -31,52 +32,34 @@ Products.ERP5.interfaces.amount
 
 from zope.interface import Interface
 
-class IAmount(Interface):
-  """Amount interface specification
-
-    An amount represents a quantity of a given resource
-    in a given quantity unit. Optional efficiency can be
-    specified in order to represent a loss ratio to take
-    into account in calculations. Loss ratio is normally
-    used only in Path.
-
-    The Amount interface is useful each time
-    we need to add or substract amounts of resources
-    independently of a movement. This is the case for example
-    for all Transformation related classes.
-
-    Equations:
-      net_quantity = quantity * efficiency
+class IAmountCore(Interface):
+  """Amount Core interface specification
 
-    TODO:
-      1. make sure getTotalPrice has or does not
-         have extra parameters (ex. rounding)
-      2. remove profit_quantity everywhere
-      3. remove target_quantity everywhere
-      4. consider how to make Interface compatible
-         with accessor generation (ex. getResource,
-         getQuantity, etc.)
-      5. consider creating an IPriceable interface
-         which is common to deliveries and amounts
+  IAmountCore defines the minimal set of getters required
+  to implement an amount.
   """
-
-  # Core API
   def getQuantity():
     """
     Returns the quantity of the resource
     in the unit specified by the Amount
+
+    NOTE: declaration is redundant with IAmountGetter
     """
 
   def getResource():
     """
     Returns the resource category relative URL
     of the Amount
+
+    NOTE: declaration is redundant with IAmountGetter
     """
 
   def getQuantityUnit():
     """
     Returns the quantity unit category relative URL
     of the Amount
+
+    NOTE: declaration is redundant with IAmountGetter
     """
 
   def isCancellationAmount():
@@ -91,57 +74,129 @@ class IAmount(Interface):
     A negative production quantity for a cancellation
     amount is a cancelled production, not
     a consumption
+
+    NOTE: declaration is redundant with IAmountGetter
     """
 
-  # Net Quantity API
   def getEfficiency():
     """
     Returns the ratio of loss for the given amount. This
     is only used in Path such as Transformation. In other
     words, efficiency of movements is always 100%.
+
+    NOTE: declaration is redundant with IAmountGetter
     """
 
-  def getNetQuantity():
+  def getBaseContributionList():
     """
-      Returns the quantity multiplied by the efficiency ratio.
+    The list of bases this amount contributes to. 
+
+    XXX: explain better
     """
 
-  # Price API
-  def getPrice():
+  def getBaseApplicationList():
+    """
+    The list of bases this amount has been applied on. Only set if the
+    amount comes from a transformation.
+
+    XXX: explain better
     """
-      Returns the unit price of the resource
+
+class IAmountConversion(Interface):
+  """Amount Conversion interface specification
+
+  IAmountConversion defines methods which can be used
+  to convert an amount from one quantity unit and to another,
+  taking into account efficiency.
   """
 
-  def getTotalPrice():
+  def getNetQuantity():
     """
-      Returns total price ie. the unit price of the resource
-      multiplied by the quantity.
+    Take into account efficiency in quantity. This is
+    only useful in Path which define a loss ratio, such
+    as Transformation. 
+
+    Formula:
+      net_quantity = quantity / efficiency
     """
 
-  # Conversion API
-  def getConvertedQuantity():
+  def getConvertedQuantity(quantity_unit=None, measure=None):
     """
     Returns the quantity of the resource converted in the
-      management unit of the resource.
+    default management unit of the resource.
+
+    quantity_unit -- optional quantity unit to use
+                     for conversion.
+
+    measure -- optional quantity unit to use
+               for conversion.
     """
 
-  def getNetConvertedQuantity():
+  def getNetConvertedQuantity(quantity_unit=None, measure=None):
     """
     Returns the net quantity of the resource converted in the
-      management unit of the resource.
+    default management unit of the resource.
+
+    quantity_unit -- optional quantity unit to use
+                     for conversion.
+
+    measure -- optional quantity unit to use
+               for conversion.
     """
 
-  # Transformation API
-  def getBaseContributionList():
-    """The list of bases this amount contributes to. 
+class IAmountPrice(Interface):
+  """Amount Price interface specification
+
+  IAmountPrice defines methods to compute total price
+  and unit price of a resource, taking into account 
+  contributions and roundings.
+  """
+  def getPrice():
     """
+    Returns the input unit price of the resource
 
-  def getBaseApplicationList():
-    """The list of bases this amount has been applied on. Only set if the
-    amount comes from a transformation.
+    NOTE: redundant with IPriceGetter
+    """
+
+  def getUnitPrice(base_contribution=None, rounding=False):
+    """
+    Returns the unit price of the resource, taking into 
+    account rounding and contributions (ex. taxes).
+
+    base_contribution -- optional base_contribution.
+                If defined, a complex process is launched
+                to add or remove to the price various amounts
+                calculated from applicable trade models if 
+                any.
+                
+    rounding -- optional rounding parameter. If set to True,
+                find and applies appropriate rounding model.
+    """
+
+  def getTotalPrice(base_contribution=None, rounding=False):
+    """
+    Returns total price ie. the unit price of the resource
+    multiplied by the quantity, taking into 
+    account rounding and contributions (ex. taxes).
+
+    base_contribution -- optional base_contribution.
+                If defined, a complex process is launched
+                to add or remove to the price various amounts
+                calculated from applicable trade models if 
+                any.
+                
+    rounding -- optional rounding parameter. If set to True,
+                find and applies appropriate rounding model.
     """
 
-  # Make it possible to add amounts
+class IAmountArithmetic(Interface):
+  """Amount Arithmetic interface specification
+
+  IAmountArithmetic defines methods to add, substract,
+  multiply or device amounts of resources. No rounding
+  should happen. All amounts should be converted to 
+  the default management unit using getNetConvertedQuantity.
+  """
   def __add__(value):
     """Add an amount to another amount
 
@@ -165,3 +220,26 @@ class IAmount(Interface):
 
       'value' is a float
     """
+
+class IAmount(IAmountCore, IAmountConversion, IAmountPrice, IAmountArithmetic):
+  """Amount interface specification
+
+    An amount represents a quantity of a given resource
+    in a given quantity unit. Optional efficiency can be
+    specified in order to represent a loss ratio to take
+    into account in calculations. Loss ratio is normally
+    used only in Path.
+
+    The Amount interface is useful each time
+    one needs to add or substract amounts of resources
+    independently of a movement. This is the case for example
+    for all Transformation related classes.
+
+    TODO-XXX:
+      1. Try to merge IAmountPrice and IPriceable
+         interface (used for deliveried)
+      2. remove profit_quantity and target_quantity everywhere
+      3. consider how to make Interface compatible
+         with accessor generation (ex. getResource,
+         getQuantity, etc.)
+  """
\ No newline at end of file