Merge pull request #17 from CodaProtocol/feature/random-currency

Add Currency.random() function

Author: yourbuddyconner

CodaClient.py

@@ -1,5 +1,6 @@
 #!/usr/bin/python3
 
+import random
 import requests
 import time
 import json
@@ -9,13 +10,27 @@
 from enum import Enum
 
 class CurrencyFormat(Enum):
+  """An Enum representing different formats of Currency in coda.
+
+  Constants:
+      WHOLE - represents whole coda (1 whole coda == 10^9 nanocodas)
+      NANO - represents the atomic unit of coda
+  """
   WHOLE = 1
   NANO = 2
 
 class CurrencyUnderflow(Exception):
   pass
 
 class Currency():
+  """A convenience wrapper around interacting with coda currency values.
+
+  This class supports performing math on Currency values of differing formats.
+  Currency instances can be added or subtracted. Currency instances can also be
+  scaled through multiplication (either against another Currency instance or a
+  int scalar).
+  """
+
   @classmethod
   def __nanocodas_from_int(_cls, n):
     return n * 1000000000
@@ -32,7 +47,40 @@ def __nanocodas_from_string(_cls, s):
       else:
         raise Exception('invalid coda currency format: %s' % s)
 
+  @classmethod
+  def random(_cls, lower_bound, upper_bound):
+    """Generates a random Currency instance between a provided lower_bound and upper_bound
+
+    Arguments:
+        lower_bound {Currency} -- A Currency instance representing the lower bound for the randomly generated value
+        upper_bound {Currency} -- A Currency instance representing the upper bound for the randomly generated value
+
+    Returns:
+        Currency - A randomly generated Currency instance between the lower_bound and upper_bound
+    """
+    if not (isinstance(lower_bound, Currency) and isinstance(upper_bound, Currency)):
+      raise Exception('invalid call to Currency.random: lower and upper bound must be instances of Currency')
+    if not upper_bound.nanocodas() >= lower_bound.nanocodas():
+      raise Exception('invalid call to Currency.random: upper_bound is not greater than lower_bound')
+    if lower_bound == upper_bound:
+      return lower_bound
+    bound_range = upper_bound.nanocodas() - lower_bound.nanocodas()
+    delta = random.randint(0, bound_range)
+    return lower_bound + Currency(delta, format=CurrencyFormat.NANO)
+
   def __init__(self, value, format=CurrencyFormat.WHOLE):
+    """Constructs a new Currency instance. Values of different CurrencyFormats may be passed in to construct the instance.
+
+    Arguments:
+        value {int|float|string} - The value to construct the Currency instance from
+        format {CurrencyFormat} - The representation format of the value
+
+    Return:
+        Currency - The newly constructed Currency instance
+
+    In the case of format=CurrencyFormat.WHOLE, then it is interpreted as value * 10^9 nanocodas.
+    In the case of format=CurrencyFormat.NANO, value is only allowed to be an int, as there can be no decimal point for nanocodas.
+    """
     if format == CurrencyFormat.WHOLE:
       if isinstance(value, int):
         self.__nanocodas = Currency.__nanocodas_from_int(value)
@@ -51,13 +99,23 @@ def __init__(self, value, format=CurrencyFormat.WHOLE):
       raise Exception('invalid Currency format %s' % format)
 
   def decimal_format(self):
+    """Computes the string decimal format representation of a Currency instance.
+
+    Return:
+        str - The decimal format representation of the Currency instance
+    """
     s = str(self.__nanocodas)
     if len(s) > 9:
       return s[:-9] + '.' + s[-9:]
     else:
       return '0.' + ('0' * (9 - len(s))) + s
 
   def nanocodas(self):
+    """Accesses the raw nanocodas representation of a Currency instance.
+
+    Return:
+        int - The nanocodas of the Currency instance represented as an integer
+    """
     return self.__nanocodas
 
   def __str__(self):

tests/test_currency.py

@@ -38,3 +38,9 @@ def test_mul_int():
 
 def test_mul_currency():
   assert (Currency(5) * Currency(2, format=CurrencyFormat.NANO)).nanocodas() == 10 * precision
+
+def test_random():
+  assert (Currency.random(Currency(5), Currency(5)).nanocodas() == 5 * precision)
+  for _ in range(25):
+    rand = Currency.random(Currency(3, format=CurrencyFormat.NANO), Currency(5, format=CurrencyFormat.NANO))
+    assert (3 <= rand.nanocodas () and rand.nanocodas() <= 5)