Add percentage kwarg to pricing.gross_margin() function

so it can return the "industry standard" value instead

rattail/pricing.py

@@ -1,8 +1,8 @@
-# -*- coding: utf-8 -*-
+# -*- coding: utf-8; -*-
 ################################################################################
 #
 #  Rattail -- Retail Software Framework
-#  Copyright © 2010-2017 Lance Edgar
+#  Copyright © 2010-2019 Lance Edgar
 #
 #  This file is part of Rattail.
 #
@@ -24,26 +24,37 @@
 Pricing Utilities
 """
 
-from __future__ import unicode_literals
+from __future__ import unicode_literals, absolute_import
 
 
 __all__ = ['gross_margin']
 
 
-def gross_margin(price, cost):
+def gross_margin(price, cost, percentage=False):
     """
     Calculate and return a gross margin percentage based on ``price`` and
     ``cost``.
 
+    Please note, that for historical reasons, the default behavior is to return
+    the margin as a decimal value from 0.0 through 100.0 (or beyond, perhaps).
+
+    However the "industry standard" seems to be to use a decimal value between
+    0.000 and 1.000 instead.  Specify ``percentage=True`` for this behavior.
+
     If ``price`` is empty (or zero), returns ``None``.
 
-    If ``cost`` is empty (or zero), returns ``100``.
+    If ``cost`` is empty (or zero), returns ``100`` (or ``1`` if
+    ``percentage=True``).
     """
-
     if not price:
         return None
 
     if not cost:
+        if percentage:
+            return 1
         return 100
 
-    return 100 * (price - cost) / price
+    margin = (price - cost) / price
+    if percentage:
+        return margin
+    return 100 * margin