Commit 78ecb3f8 authored by Jean-Paul Smets's avatar Jean-Paul Smets

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
parent d90c6e8a
# -*- coding: utf-8 -*-
############################################################################## ##############################################################################
# #
# Copyright (c) 2009 Nexedi SARL and Contributors. All Rights Reserved. # Copyright (c) 2009 Nexedi SARL and Contributors. All Rights Reserved.
...@@ -31,117 +32,171 @@ Products.ERP5.interfaces.amount ...@@ -31,117 +32,171 @@ Products.ERP5.interfaces.amount
from zope.interface import Interface from zope.interface import Interface
class IAmount(Interface): class IAmountCore(Interface):
"""Amount interface specification """Amount Core interface specification
An amount represents a quantity of a given resource IAmountCore defines the minimal set of getters required
in a given quantity unit. Optional efficiency can be to implement an amount.
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
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
""" """
# Core API
def getQuantity(): def getQuantity():
""" """
Returns the quantity of the resource Returns the quantity of the resource
in the unit specified by the Amount in the unit specified by the Amount
NOTE: declaration is redundant with IAmountGetter
""" """
def getResource(): def getResource():
""" """
Returns the resource category relative URL Returns the resource category relative URL
of the Amount of the Amount
NOTE: declaration is redundant with IAmountGetter
""" """
def getQuantityUnit(): def getQuantityUnit():
""" """
Returns the quantity unit category relative URL Returns the quantity unit category relative URL
of the Amount of the Amount
NOTE: declaration is redundant with IAmountGetter
""" """
def isCancellationAmount(): def isCancellationAmount():
""" """
A cancellation amount must be interpreted A cancellation amount must be interpreted
reversely wrt. to the sign of quantity. reversely wrt. to the sign of quantity.
For example, a negative credit for a cancellation
amount is a negative credit, not a positive
debit.
For example, a negative credit for a cancellation A negative production quantity for a cancellation
amount is a negative credit, not a positive amount is a cancelled production, not
debit. a consumption
A negative production quantity for a cancellation NOTE: declaration is redundant with IAmountGetter
amount is a cancelled production, not
a consumption
""" """
# Net Quantity API
def getEfficiency(): def getEfficiency():
""" """
Returns the ratio of loss for the given amount. This Returns the ratio of loss for the given amount. This
is only used in Path such as Transformation. In other is only used in Path such as Transformation. In other
words, efficiency of movements is always 100%. words, efficiency of movements is always 100%.
NOTE: declaration is redundant with IAmountGetter
"""
def getBaseContributionList():
"""
The list of bases this amount contributes to.
XXX: explain better
"""
def getBaseApplicationList():
"""
The list of bases this amount has been applied on. Only set if the
amount comes from a transformation.
XXX: explain better
""" """
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 getNetQuantity(): def getNetQuantity():
""" """
Returns the quantity multiplied by the efficiency ratio. 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
""" """
# Price API def getConvertedQuantity(quantity_unit=None, measure=None):
def getPrice():
""" """
Returns the unit price of the resource Returns the quantity of the resource converted in the
default management unit of the resource.
quantity_unit -- optional quantity unit to use
for conversion.
measure -- optional quantity unit to use
for conversion.
""" """
def getTotalPrice(): def getNetConvertedQuantity(quantity_unit=None, measure=None):
""" """
Returns total price ie. the unit price of the resource Returns the net quantity of the resource converted in the
multiplied by the quantity. default management unit of the resource.
quantity_unit -- optional quantity unit to use
for conversion.
measure -- optional quantity unit to use
for conversion.
""" """
# Conversion API class IAmountPrice(Interface):
def getConvertedQuantity(): """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 quantity of the resource converted in the Returns the input unit price of the resource
management unit of the resource.
NOTE: redundant with IPriceGetter
""" """
def getNetConvertedQuantity(): def getUnitPrice(base_contribution=None, rounding=False):
""" """
Returns the net quantity of the resource converted in the Returns the unit price of the resource, taking into
management unit of the resource. 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.
""" """
# Transformation API def getTotalPrice(base_contribution=None, rounding=False):
def getBaseContributionList():
"""The list of bases this amount contributes to.
""" """
Returns total price ie. the unit price of the resource
multiplied by the quantity, taking into
account rounding and contributions (ex. taxes).
def getBaseApplicationList(): base_contribution -- optional base_contribution.
"""The list of bases this amount has been applied on. Only set if the If defined, a complex process is launched
amount comes from a transformation. 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): def __add__(value):
"""Add an amount to another amount """Add an amount to another amount
...@@ -165,3 +220,26 @@ class IAmount(Interface): ...@@ -165,3 +220,26 @@ class IAmount(Interface):
'value' is a float '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
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment