Linting, type checking

5 files changed, 293 insertions, 130 deletions

diff --git a/utils/engine.py b/utils/engine.py
index e64d599..f4169ec 100644
--- a/utils/engine.py
+++ b/utils/engine.py
@@ -10,8 +10,9 @@ Pricing engine for exotic options.
 import math
 from statistics import mean, stdev
 from dataclasses import dataclass
-from typing import List
+from typing import List, Sequence
 
+from utils.misc import Number
 from utils.path import PathGenerator
 from utils.payoff import BasePayoff
 
@@ -23,6 +24,14 @@ __all__ = ['MCResult', 'PricingEngine']
 class MCResult:
     """
     Price of option along with its MC error.
+
+    Attributes
+    ----------
+    price : float
+        Spot Price.
+    path : float
+        MC standard error.
+
     """
     price: float
     stderr: float
@@ -35,42 +44,65 @@ class PricingEngine:
 
     Attributes
     ----------
-    payoff : Payoff object for calculating the options payoff.
-    path : PathGenerator object for generating the evolution of the underlying.
+    payoff : BasePayoff
+        Payoff object for calculating the options payoff.
+    path : PathGenerator
+        PathGenerator object for generating the evolution of the underlying.
 
     Methods
-    ----------
+    -------
     price()
+        Price the option using MC techniques.
 
     Examples
-    ----------
+    --------
     >>> from utils.engine import PricingEngine
     >>> from utils.path import PathGenerator
     >>> from utils.payoff import AsianArithmeticPayOff
     >>> path = PathGenerator(S=100., r=0.1, div=0.01, vol=0.3)
     >>> payoff = AsianArithmeticPayOff(option_right='Call', K=110)
     >>> engine = PricingEngine(payoff=payoff, path=path)
-    >>> print(engine.price(T=range(4)))
-    MCResult(price=12.003704847790525, stderr=0.2327352760696234)
+    >>> print(engine)
+    PricingEngine(payoff=AsianArithmeticPayOff(K=110, option_right=Call),
+                  path=PathGenerator(S=100.0, r=0.1, div=0.01, vol=0.3))
 
     """
     payoff: BasePayoff
     path: PathGenerator
 
-    def price(self, T: List[float], ntrials: int = 1E4,
-              antithetic: bool = True) -> MCResult:
+    def price(
+            self,
+            T: Sequence[Number],
+            ntrials: int = 10_000,
+            antithetic: bool = True
+    ) -> MCResult:
         """
         Price the option using MC techniques.
 
         Parameters
         ----------
-        T : Set of times {t1, t2, ..., tn} in years.
-        ntrials : Number of trials to simulate.
-        antithetic : Use antithetic variates technique.
+        T : Sequence of Numbers
+            Set of times {t1, t2, ..., tn} in years.
+        ntrials : int
+            Number of trials to simulate.
+        antithetic : bool
+            Use antithetic variates technique.
 
         Returns
-        ----------
-        MCResult : Price of the option.
+        -------
+        MCResult
+            Price of the option.
+
+        Examples
+        --------
+        >>> from utils.engine import PricingEngine
+        >>> from utils.path import PathGenerator
+        >>> from utils.payoff import AsianArithmeticPayOff
+        >>> path = PathGenerator(S=100., r=0.1, div=0.01, vol=0.3)
+        >>> payoff = AsianArithmeticPayOff(option_right='Call', K=110)
+        >>> engine = PricingEngine(payoff=payoff, path=path)
+        >>> print(engine.price(T=range(4)))
+        MCResult(price=12.003704847790525, stderr=0.2327352760696234)
 
         """
         if ntrials < len(T):
@@ -79,7 +111,7 @@ class PricingEngine:
 
         # Generation start
         ntrials = int(ntrials // len(T))
-        payoffs = [0] * ntrials
+        payoffs: List[float] = [0] * ntrials
         for idx in range(ntrials):
             # Generate a random path
             if not antithetic:
diff --git a/utils/enums.py b/utils/enums.py
index 6a607ea..aed4a97 100644
--- a/utils/enums.py
+++ b/utils/enums.py
@@ -9,6 +9,7 @@ Enumeration utility classes.
 
 from enum import Enum, auto
 
+
 __all__ = ['OptionRight', 'BarrierUpDown', 'BarrierInOut']
 
 
diff --git a/utils/misc.py b/utils/misc.py
index 708d759..f7743d1 100644
--- a/utils/misc.py
+++ b/utils/misc.py
@@ -7,24 +7,31 @@
 Miscellaneous utility methods.
 """
 
+from typing import Any, Union
 
-__all__ = ['is_num', 'is_pos']
 
+__all__ = ['Number', 'is_num', 'is_pos']
 
-def is_num(val: (int, float)) -> bool:
+
+_T = (int, float)
+Number = Union[int, float]
+
+
+def is_num(val: Any) -> bool:
     """
-    Check if the input value is a non-infinite number.
+    Check if the input value is a finite number.
 
     Parameters
     ----------
-    val : Value to check.
+    val : object
+        Value to check.
 
     Returns
-    ----------
-    is_num : Whether it is a non-infinite number.
+    -------
+    bool
 
     Examples
-    ----------
+    --------
     >>> from utils.misc import is_num
     >>> print(is_num(10))
     True
@@ -32,25 +39,26 @@ def is_num(val: (int, float)) -> bool:
     False
 
     """
-    if not isinstance(val, (int, float)):
+    if not isinstance(val, _T):
         return False
     return True
 
 
-def is_pos(val: (int, float)) -> bool:
+def is_pos(val: Any) -> bool:
     """
-    Check if the input value is a non-infinite positive number.
+    Check if the input value is a finite positive number.
 
     Parameters
     ----------
-    val : Value to check.
+    val : object
+        Value to check.
 
     Returns
-    ----------
-    is_pos : Whether it is a non-infinite positive number.
+    -------
+    bool
 
     Examples
-    ----------
+    --------
     >>> from utils.misc import is_pos
     >>> print(is_pos(10))
     True
diff --git a/utils/path.py b/utils/path.py
index 2fbb48f..41474ef 100644
--- a/utils/path.py
+++ b/utils/path.py
@@ -11,7 +11,9 @@ import math
 import random
 from copy import deepcopy
 from dataclasses import dataclass
-from typing import List, Tuple
+from typing import List, Sequence, Tuple
+
+from utils.misc import Number
 
 
 __all__ = ['PathGenerator']
@@ -24,14 +26,18 @@ class PathGenerator:
 
     Attributes
     ----------
-    S : Spot price.
-    r : Risk-free interest rate.
-    div : Dividend yield.
-    vol : Volatility.
-    net_r : Net risk free rate.
+    S : Number
+        Spot price.
+    r : Number
+        Risk-free interest rate.
+    div : Number
+        Dividend yield.
+    vol : Number
+        Volatility.
+    net_r
 
     Methods
-    ----------
+    -------
     generate(T)
         Generate a random path {S_t1, S_t2, ..., S_tn}.
     generate_antithetic(T)
@@ -39,42 +45,51 @@ class PathGenerator:
         [{S_t1, S_t2, ..., S_tn}, {S'_t1, S'_t2, ..., S'_tn}].
 
     Examples
-    ----------
+    --------
     >>> from utils.path import PathGenerator
     >>> path = PathGenerator(S=100., r=0.1, div=0.01, vol=0.3)
-    >>> print(path.generate(T=range(4)))
-    [100.0, 100.33539853588853, 122.76017088387074, 142.29540684005462]
-    >>> print(path.generate(T=range(4)))
-    [100.0, 73.03094019139712, 77.37310245438943, 66.54240939439934]
+    >>> print(path)
+    PathGenerator(S=100.0, r=0.1, div=0.01, vol=0.3)
 
     """
-    S: float
-    r: float
-    div: float
-    vol: float
+    S: Number
+    r: Number
+    div: Number
+    vol: Number
 
     @property
     def net_r(self) -> float:
         """Net risk free rate."""
-        return self.r - self.div
+        return float(self.r - self.div)
 
-    def generate(self, T: List[float]) -> List[float]:
+    def generate(self, T: Sequence[Number]) -> List[float]:
         """
         Generate a random path {S_t1, S_t2, ..., S_tn}.
 
         Parameters
         ----------
-        T : Set of times {t1, t2, ..., tn} in years.
+        T : Sequence of Numbers
+            Set of times {t1, t2, ..., tn} in years.
 
         Returns
-        ----------
-        spot_prices : Set of prices for the underlying {S_t1, S_t2, ..., S_tn}.
+        -------
+        spot_prices : List of floats
+            Set of prices for the underlying {S_t1, S_t2, ..., S_tn}.
+
+        Examples
+        --------
+        >>> from utils.path import PathGenerator
+        >>> path = PathGenerator(S=100., r=0.1, div=0.01, vol=0.3)
+        >>> print(path.generate(T=range(4)))
+        [100.0, 100.33539853588853, 122.76017088387074, 142.29540684005462]
+        >>> print(path.generate(T=range(4)))
+        [100.0, 73.03094019139712, 77.37310245438943, 66.54240939439934]
 
         """
         # Calculate dt time differences
         dts = [T[idx + 1] - T[idx] for idx in range(len(T) - 1)]
 
-        spot_prices = [0] * len(T)
+        spot_prices: List[float] = [0] * len(T)
         spot_prices[0] = self.S
         for idx, dt in enumerate(dts):
             # Calculate the drift e^{(r - (1/2) σ²) Δt}
@@ -89,27 +104,41 @@ class PathGenerator:
             spot_prices[idx + 1] = S_t
         return spot_prices
 
-    def generate_antithetic(self, T: List[float]) -> Tuple[List[float],
-                                                           List[float]]:
+    def generate_antithetic(
+            self, T: Sequence[Number]
+    ) -> Tuple[List[float], List[float]]:
         """
         Generate a random plus antithetic path
         [{S_t1, S_t2, ..., S_tn}, {S'_t1, S'_t2, ..., S'_tn}].
 
         Parameters
         ----------
-        T : Set of times {t1, t2, ..., tn} in years.
+        T : Sequence of Numbers
+            Set of times {t1, t2, ..., tn} in years.
 
         Returns
-        ----------
-        prices_tuple : Set of prices for the underlying
-                       [{S_t1, S_t2, ..., S_tn}, {S'_t1, S'_t2, ..., S'_tn}].
+        -------
+        prices_tuple : Tuple of two Lists of floats
+            Set of prices for the underlying
+            [{S_t1, S_t2, ..., S_tn}, {S'_t1, S'_t2, ..., S'_tn}].
+
+        Examples
+        --------
+        >>> from utils.path import PathGenerator
+        >>> path = PathGenerator(S=100., r=0.1, div=0.01, vol=0.3)
+        >>> print(path.generate_antithetic(T=range(4)))
+        ([100.0, 106.30304144532359, 122.02501765852367, 108.71120035365013],
+         [100.0, 102.92972513566257, 98.11245153613649, 120.49949282794978])
+        >>> print(path.generate_antithetic(T=range(4)))
+        ([100.0, 130.1595970941697, 103.35241529329348, 93.58800177914543],
+         [100.0, 84.06404968460234, 115.83835362960282, 139.97140935058962])
 
         """
         # Calculate dt time differences
         dts = [T[idx + 1] - T[idx] for idx in range(len(T) - 1)]
 
         # Create data structures
-        spot_prices = [0] * len(T)
+        spot_prices: List[float] = [0] * len(T)
         spot_prices[0] = self.S
 
         a_spot_prices = deepcopy(spot_prices)
diff --git a/utils/payoff.py b/utils/payoff.py
index fffbdba..7edeb87 100644
--- a/utils/payoff.py
+++ b/utils/payoff.py
@@ -8,21 +8,36 @@ Payoff of an option.
 """
 
 from abc import ABC, abstractmethod
-from dataclasses import dataclass
-from typing import List
+from typing import AnyStr, List, Union, Sequence
 
 from utils.enums import OptionRight, BarrierUpDown, BarrierInOut
+from utils.misc import Number
 
 
-__all__ = ['BasePayoff', 'VanillaPayOff', 'AsianArithmeticPayOff',
-           'DiscreteBarrierPayOff']
+__all__ = [
+    'BasePayoff',
+    'VanillaPayOff',
+    'AsianArithmeticPayOff',
+    'DiscreteBarrierPayOff'
+]
 
 
-@dataclass
 class BasePayoff(ABC):
     """Base class for calculating the payoff."""
-    K: float
-    option_right: (str, OptionRight)
+
+    def __init__(self, K: Number,
+                 option_right: Union[AnyStr, OptionRight]) -> None:
+        self.K: Number = K
+        # https://github.com/python/mypy/issues/3004
+        self.option_right = option_right  # type: ignore
+
+    def __repr__(self) -> str:
+        return (
+            f'{self.__class__.__name__}('
+            f'K={self.K!r}, '
+            f'option_right={self.option_right!r}'
+            ')'
+        )
 
     @property
     def option_right(self) -> OptionRight:
@@ -30,7 +45,7 @@ class BasePayoff(ABC):
         return self._option_right
 
     @option_right.setter
-    def option_right(self, val: (str, OptionRight)) -> None:
+    def option_right(self, val: Union[AnyStr, OptionRight]) -> None:
         """Set the option_right of the option."""
         if isinstance(val, str):
             if not hasattr(OptionRight, val):
@@ -44,17 +59,43 @@ class BasePayoff(ABC):
                 f'Expected str or OptionRight, instead got type {type(val)}!'
             )
 
-    def _calculate_call(self, S: float) -> float:
-        """Call option."""
-        return max(S - self.K, 0.)
+    def _calculate_call(self, S: Number) -> float:
+        """
+        Price call option for a given underlying price.
+
+        Parameters
+        ----------
+        S : Number
+            Price of underlying.
+
+        Returns
+        -------
+        float
+            Price of the call option.
+
+        """
+        return float(max(S - self.K, 0.0))
+
+    def _calculate_put(self, S: Number) -> float:
+        """
+        Price put option for a given underlying price.
+
+        Parameters
+        ----------
+        S : Number
+            Price of underlying.
 
-    def _calculate_put(self, S: float) -> float:
-        """Put option."""
-        return max(self.K - S, 0.)
+        Returns
+        -------
+        float
+            Price of the put option.
+
+        """
+        return float(max(self.K - S, 0.0))
 
     @abstractmethod
-    def calculate(self, S: float) -> float:
-        """Calulate the payoff for a given spot."""
+    def calculate(self, S: Sequence[Number]) -> float:
+        """Calulate the payoff for a given path."""
 
 
 class VanillaPayOff(BasePayoff):
@@ -63,46 +104,56 @@ class VanillaPayOff(BasePayoff):
 
     Attributes
     ----------
-    option_right : Right of the option.
-    K : Strike price.
+    option_right : OptionRight
+        Right of the option.
+    K : Number
+        Strike price.
 
     Methods
-    ----------
+    -------
     calculate(S)
-        Calulate the payoff given a spot price.
+        Calulate the payoff for a given path.
 
     Examples
-    ----------
+    --------
     >>> from utils.payoff import VanillaPayOff
     >>> payoff = VanillaPayOff(option_right='Call', K=150.)
-    >>> print(payoff.calculate(160.))
-    10.0
+    >>> print(payoff)
+    VanillaPayOff(K=150.0, option_right=Call)
 
     """
 
-    def calculate(self, S: (float, List[float])) -> float:
+    def calculate(self, S: Sequence[Number]) -> float:
         """
-        Calulate the payoff given a spot price.
+        Calulate the payoff for a given path.
 
         Parameters
         ----------
-        S : Spot price or list of spot prices.
+        S : Sequence of Numbers
+            Set of prices for the underlying {S_t1, S_t2, ..., S_tn}.
 
         Returns
-        ----------
-        payoff : Payoff.
+        -------
+        payoff : float
+            Payoff.
 
         Notes
-        ----------
-        If a list is given as input, the final entry will be taken to evaluate.
+        -----
+        The final entry will be taken to evaluate the payoff.
+
+        Examples
+        --------
+        >>> from utils.payoff import VanillaPayOff
+        >>> payoff = VanillaPayOff(option_right='Call', K=150.)
+        >>> print(payoff.calculate([160.]))
+        10.0
 
         """
-        if not isinstance(S, float):
-            S = S[-1]
+        # Calculate payoff using final price
         if self.option_right == OptionRight.Call:
-            payoff = self._calculate_call(S)
+            payoff = self._calculate_call(S[-1])
         else:
-            payoff = self._calculate_put(S)
+            payoff = self._calculate_put(S[-1])
         return payoff
 
 
@@ -112,34 +163,45 @@ class AsianArithmeticPayOff(BasePayoff):
 
     Attributes
     ----------
-    option_right : Right of the option.
-    K : Strike price.
+    option_right : OptionRight
+        Right of the option.
+    K : Number
+        Strike price.
 
     Methods
-    ----------
+    -------
     calculate(S)
         Calulate the payoff given a set of prices for the underlying.
 
     Examples
-    ----------
+    --------
     >>> from utils.payoff import AsianArithmeticPayOff
     >>> payoff = AsianArithmeticPayOff(option_right='Call', K=150)
-    >>> print(payoff.calculate([140, 150, 160, 170, 180]))
-    10.0
+    >>> print(payoff)
+    AsianArithmeticPayOff(K=150, option_right=Call)
 
     """
 
-    def calculate(self, S: List[float]) -> float:
+    def calculate(self, S: Sequence[Number]) -> float:
         """
         Calulate the payoff given a set of prices for the underlying.
 
         Parameters
         ----------
-        S : Set of prices for the underlying {S_t1, S_t2, ..., S_tn}.
+        S : Sequence of Numbers
+            Set of prices for the underlying {S_t1, S_t2, ..., S_tn}.
 
         Returns
-        ----------
-        payoff : Payoff.
+        -------
+        payoff : float
+            Payoff.
+
+        Examples
+        --------
+        >>> from utils.payoff import AsianArithmeticPayOff
+        >>> payoff = AsianArithmeticPayOff(option_right='Call', K=150)
+        >>> print(payoff.calculate([140, 150, 160, 170, 180]))
+        10.0
 
         """
         avg_sum = sum(S) / len(S)
@@ -150,7 +212,6 @@ class AsianArithmeticPayOff(BasePayoff):
         return payoff
 
 
-@dataclass(init=False)
 class DiscreteBarrierPayOff(BasePayoff):
     """
     Class for calculating the payoff of a discrete barrier European style
@@ -158,39 +219,56 @@ class DiscreteBarrierPayOff(BasePayoff):
 
     Attributes
     ----------
-    option_right : Right of the option.
-    K : Strike price.
-    B : Barrier price.
-    barrier_updown : Up or down type barrier option.
-    barrier_inout : In or out type barrier option.
+    option_right : OptionRight
+        Right of the option.
+    K : Number
+        Strike price.
+    B : Number
+        Barrier price.
+    barrier_updown : BarrierUpDown
+        Up or down type barrier option.
+    barrier_inout : BarrierInOut
+        In or out type barrier option.
 
     Methods
-    ----------
+    -------
     calculate(S)
         Calulate the payoff given a set of prices for the underlying.
 
     Examples
-    ----------
+    --------
     >>> from utils.payoff import DiscreteBarrierPayOff
-    >>> payoff = DiscreteBarrierPayOff(option_right='Call', K=100, B=90,
+    >>> payoff = DiscreteBarrierPayOff(option_right='Call', K=100, B=90, \
                                        barrier_updown='Down', barrier_inout='Out')
-    >>> print(payoff.calculate([100., 110., 120.]))
-    20.0
-    >>> print(payoff.calculate([100., 110., 120., 80., 110.]))
-    0.0
+    >>> print(payoff)
+    DiscreteBarrierPayOff(K=100, option_right=Call, B=90, barrier_updown=Down, barrier_inout=Out)
 
     """
-    B: float
-    barrier_updown: (str, BarrierUpDown)
-    barrier_inout: (str, BarrierInOut)
 
-    def __init__(self, option_right: (str, OptionRight), K: float, B: float,
-                 barrier_updown: (str, BarrierUpDown),
-                 barrier_inout: (str, BarrierInOut)):
+    def __init__(
+            self,
+            option_right: Union[AnyStr, OptionRight],
+            K: Number,
+            B: Number,
+            barrier_updown: Union[AnyStr, BarrierUpDown],
+            barrier_inout: Union[AnyStr, BarrierInOut]
+    ) -> None:
         super().__init__(K, option_right)
-        self.B = B
-        self.barrier_updown = barrier_updown
-        self.barrier_inout = barrier_inout
+        self.B: Number = B
+        # https://github.com/python/mypy/issues/3004
+        self.barrier_updown = barrier_updown  # type: ignore
+        self.barrier_inout = barrier_inout  # type: ignore
+
+    def __repr__(self) -> str:
+        return (
+            f'{self.__class__.__name__}('
+            f'K={self.K!r}, '
+            f'option_right={self.option_right!r}, '
+            f'B={self.B!r}, '
+            f'barrier_updown={self.barrier_updown!r}, '
+            f'barrier_inout={self.barrier_inout!r}'
+            ')'
+        )
 
     @property
     def barrier_updown(self) -> BarrierUpDown:
@@ -198,7 +276,7 @@ class DiscreteBarrierPayOff(BasePayoff):
         return self._barrier_updown
 
     @barrier_updown.setter
-    def barrier_updown(self, val: (str, BarrierUpDown)) -> None:
+    def barrier_updown(self, val: Union[AnyStr, BarrierUpDown]) -> None:
         """Set either up or down type barrier option."""
         if isinstance(val, str):
             if not hasattr(BarrierUpDown, val):
@@ -218,7 +296,7 @@ class DiscreteBarrierPayOff(BasePayoff):
         return self._barrier_inout
 
     @barrier_inout.setter
-    def barrier_inout(self, val: (str, BarrierInOut)) -> None:
+    def barrier_inout(self, val: Union[AnyStr, BarrierInOut]) -> None:
         """Set either up or down type barrier option."""
         if isinstance(val, str):
             if not hasattr(BarrierInOut, val):
@@ -232,32 +310,47 @@ class DiscreteBarrierPayOff(BasePayoff):
                 f'Expected str or BarrierInOut, instead got type {type(val)}!'
             )
 
-    def calculate(self, S: List[float]) -> float:
+    def calculate(self, S: Sequence[Number]) -> float:
         """
         Calulate the payoff given a set of prices for the underlying.
 
         Parameters
         ----------
-        S : Set of prices for the underlying {S_t1, S_t2, ..., S_tn}.
+        S : Sequence of Numbers
+            Set of prices for the underlying {S_t1, S_t2, ..., S_tn}.
 
         Returns
-        ----------
-        payoff : Payoff.
+        -------
+        payoff : float
+            Payoff.
+
+        Examples
+        --------
+        >>> from utils.payoff import DiscreteBarrierPayOff
+        >>> payoff = DiscreteBarrierPayOff(option_right='Call', K=100, B=90, \
+                                           barrier_updown='Down', barrier_inout='Out')
+        >>> print(payoff.calculate([100., 110., 120.]))
+        20.0
+        >>> print(payoff.calculate([100., 110., 120., 80., 110.]))
+        0.0
 
         """
         # Calculate the heavyside
+        H: List[int]
         if self.barrier_updown == BarrierUpDown.Up:
             H = [1 if self.B - x > 0 else 0 for x in S]
         else:
             H = [1 if x - self.B > 0 else 0 for x in S]
 
         # Calculate whether it has been activated
+        activation: int
         if self.barrier_inout == BarrierInOut.In:
             activation = 1 if min(H) == 0 else 0
         else:
             activation = min(H)
 
         # Calculate payoff using final price
+        payoff: float
         if self.option_right == OptionRight.Call:
             payoff = activation * self._calculate_call(S[-1])
         else: