src/pyutils/typez/rate.py

   1 #!/usr/bin/env python3
   2
   3 # © Copyright 2021-2023, 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         Raises:
  40             ValueError: if more than one of percentage, percent_change and
  41                 multiplier is provided
  42         """
  43         count = 0
  44         if multiplier is not None:
  45             if isinstance(multiplier, str):
  46                 multiplier = multiplier.replace("%", "")
  47                 m = float(multiplier)
  48                 m /= 100
  49                 self.multiplier: float = m
  50             else:
  51                 self.multiplier = multiplier
  52             count += 1
  53         if percentage is not None:
  54             self.multiplier = percentage / 100
  55             count += 1
  56         if percent_change is not None:
  57             self.multiplier = 1.0 + percent_change / 100
  58             count += 1
  59         if count != 1:
  60             raise ValueError(
  61                 "Exactly one of percentage, percent_change or multiplier is required."
  62             )
  63
  64     def apply_to(self, other):
  65         """Applies the rate to a base number.
  66
  67         Args:
  68             other: the base to apply the change rate to.
  69
  70         Returns:
  71             The result after the change.
  72         """
  73         return self.__mul__(other)
  74
  75     def of(self, other):
  76         """Applies the rate to a base number.
  77
  78         Args:
  79             other: the base to apply the change rate to.
  80
  81         Returns:
  82             The result after the change.
  83         """
  84         return self.__mul__(other)
  85
  86     def __float__(self):
  87         return self.multiplier
  88
  89     def __mul__(self, other):
  90         return self.multiplier * float(other)
  91
  92     __rmul__ = __mul__
  93
  94     def __truediv__(self, other):
  95         return self.multiplier / float(other)
  96
  97     def __add__(self, other):
  98         return self.multiplier + float(other)
  99
 100     __radd__ = __add__
 101
 102     def __sub__(self, other):
 103         return self.multiplier - float(other)
 104
 105     def __eq__(self, other):
 106         return self.multiplier == float(other)
 107
 108     def __ne__(self, other):
 109         return not self.__eq__(other)
 110
 111     def __lt__(self, other):
 112         return self.multiplier < float(other)
 113
 114     def __gt__(self, other):
 115         return self.multiplier > float(other)
 116
 117     def __le__(self, other):
 118         return self < other or self == other
 119
 120     def __ge__(self, other):
 121         return self > other or self == other
 122
 123     def __hash__(self):
 124         return self.multiplier
 125
 126     def __repr__(self, *, relative=False, places=3):
 127         if relative:
 128             percentage = (self.multiplier - 1.0) * 100.0
 129         else:
 130             percentage = self.multiplier * 100.0
 131         return f"{percentage:+.{places}f}%"