src/pyutils/typez/rate.py

   1 #!/usr/bin/env python3
   2
   3 # © Copyright 2021-2022, Scott Gasch
   4
   5 """A class to represent a rate of change."""
   6
   7 from typing import Optional
   8
   9
  10 class Rate(object):
  11     """A class to represent a rate of change."""
  12
  13     def __init__(
  14         self,
  15         multiplier: Optional[float] = None,
  16         *,
  17         percentage: Optional[float] = None,
  18         percent_change: Optional[float] = None,
  19     ):
  20         """Constructs a new :class:`Rate` from a multiplier, percentage, or
  21         percent change.  One and only one of these may be passed.  These are
  22         a little confusing so here's an example...
  23
  24         .. note::
  25
  26             A multiplier of 1.5x is the same as a percentage of 150% and
  27             is also the same as a 50% change.  Let's examine an original
  28             amount of 100.  Multiplying it by a 1.5x multiplier yields 150.
  29             Multiplying it by 150% yields 150.  Increasing it by 50% also
  30             yields 150.
  31
  32         Args:
  33             multiplier: provides the number that you would multiply a base
  34                 amount by to modify it
  35             percentage: provides the multiplier as a percentage
  36             percent_change: provides the multiplier as a percent change to
  37                 the base amount
  38         """
  39         count = 0
  40         if multiplier is not None:
  41             if isinstance(multiplier, str):
  42                 multiplier = multiplier.replace('%', '')
  43                 m = float(multiplier)
  44                 m /= 100
  45                 self.multiplier: float = m
  46             else:
  47                 self.multiplier = multiplier
  48             count += 1
  49         if percentage is not None:
  50             self.multiplier = percentage / 100
  51             count += 1
  52         if percent_change is not None:
  53             self.multiplier = 1.0 + percent_change / 100
  54             count += 1
  55         if count != 1:
  56             raise Exception(
  57                 'Exactly one of percentage, percent_change or multiplier is required.'
  58             )
  59
  60     def apply_to(self, other):
  61         """Applies the rate to a base number.
  62
  63         Args:
  64             other: the base to apply the change rate to.
  65
  66         Returns:
  67             The result after the change.
  68         """
  69         return self.__mul__(other)
  70
  71     def of(self, other):
  72         """Applies the rate to a base number.
  73
  74         Args:
  75             other: the base to apply the change rate to.
  76
  77         Returns:
  78             The result after the change.
  79         """
  80         return self.__mul__(other)
  81
  82     def __float__(self):
  83         return self.multiplier
  84
  85     def __mul__(self, other):
  86         return self.multiplier * float(other)
  87
  88     __rmul__ = __mul__
  89
  90     def __truediv__(self, other):
  91         return self.multiplier / float(other)
  92
  93     def __add__(self, other):
  94         return self.multiplier + float(other)
  95
  96     __radd__ = __add__
  97
  98     def __sub__(self, other):
  99         return self.multiplier - float(other)
 100
 101     def __eq__(self, other):
 102         return self.multiplier == float(other)
 103
 104     def __ne__(self, other):
 105         return not self.__eq__(other)
 106
 107     def __lt__(self, other):
 108         return self.multiplier < float(other)
 109
 110     def __gt__(self, other):
 111         return self.multiplier > float(other)
 112
 113     def __le__(self, other):
 114         return self < other or self == other
 115
 116     def __ge__(self, other):
 117         return self > other or self == other
 118
 119     def __hash__(self):
 120         return self.multiplier
 121
 122     def __repr__(self, *, relative=False, places=3):
 123         if relative:
 124             percentage = (self.multiplier - 1.0) * 100.0
 125         else:
 126             percentage = self.multiplier * 100.0
 127         return f'{percentage:+.{places}f}%'