DOC: no non-deliverable FXOptions and doc changes

pyproject.toml

@@ -15,7 +15,7 @@ features = ["pyo3/extension-module"]
 
 [project]
 name = "rateslib"
-version = "2.5.0"
+version = "2.5.dev0"
 description = "A fixed income library for trading interest rates"
 readme = "README.md"
 authors = [{ name = "J H M Darbyshire"}]

python/rateslib/errors.py

@@ -49,9 +49,10 @@
 )
 
 VE_MISMATCHED_FX_PAIR_ND_PAIR = (
-    "A non-deliverable FXOption must be configured with a non-deliverable currency `pair`"
-    "which includes the RHS currency of the `fx_pair` specific to the FXOption.\nGot "
-    "`pair': {0}' and RHS of `fx_pair`: '{1}'."
+    "Non-deliverable FXOptions into a third currency are not allowed.\n"
+    "Got nd-currency: '{0}' and option index pair: '{1}'.\n"
+    "FXOptions of this nature require quanto volatility adjustements that the basic models"
+    "do not include."
 )
 
 # Fixings

python/rateslib/instruments/iirs.py

@@ -218,6 +218,23 @@ class IIRS(_BaseInstrument):
         The value of the rate fixing. If a scalar, is used directly. If a string identifier, links
         to the central ``fixings`` object and data loader.
 
+        .. note::
+
+           The following parameters define **indexation**.
+
+    index_method : IndexMethod, str, :green:`optional (set by 'defaults')`
+        The interpolation method, or otherwise, to determine index values from reference dates.
+    index_lag: int, :green:`optional (set by 'defaults')`
+        The indexation lag, in months, applied to the determination of index values.
+    index_base: float, Dual, Dual2, Variable, :green:`optional`
+        The specific value applied as the base index value for all *Periods*.
+        If not given and ``index_fixings`` is a string fixings identifier that will be
+        used to determine the base index value.
+    index_fixings: float, Dual, Dual2, Variable, Series, str, 2-tuple or list, :green:`optional`
+        The index value for the reference date.
+        Best practice is to supply this value as string identifier relating to the global
+        ``fixings`` object.
+
         .. note::
 
            The following are **meta parameters**.

python/rateslib/instruments/zcis.py

@@ -43,6 +43,49 @@ class ZCIS(_BaseInstrument):
     An *indexed zero coupon swap (ZCIS)* composing a :class:`~rateslib.legs.ZeroFixedLeg`
     and a :class:`~rateslib.legs.ZeroIndexLeg`.
 
+    .. rubric:: Examples
+
+    .. ipython:: python
+       :suppress:
+
+       from rateslib.instruments import ZCIS
+       from datetime import datetime as dt
+       from rateslib import fixings
+       from pandas import Series
+
+    .. ipython:: python
+
+       fixings.add("CPI_UK", Series(index=[dt(1999, 10, 1), dt(1999, 11, 1)], data=[110.0, 112.0]))
+       zcis = ZCIS(
+           effective=dt(2000, 1, 10),
+           termination="2Y",
+           frequency="A",
+           fixed_rate=3.5,
+           currency="gbp",
+           leg2_index_fixings="CPI_UK",
+           leg2_index_method="daily",
+       )
+       zcis.cashflows()
+
+    .. ipython:: python
+       :suppress:
+
+       fixings.pop("CPI_UK")
+
+    .. rubric:: Pricing
+
+    The methods of a *ZCIS* require a *disc curve* applicable to both legs and a *leg2 index curve*.
+    The following input formats are allowed:
+
+    .. code-block:: python
+
+       curves = [index_curve, disc_curve]                         # two curves
+       curves = [None, disc_curve, leg2_index_curve, disc_curve]  # four curves
+       curves = {  # dict form is explicit
+           "disc_curve": disc_curve,
+           "leg2_index_curve": leg2_index_curve,
+       }
+
     .. role:: red
 
     .. role:: green
@@ -137,9 +180,25 @@ class ZCIS(_BaseInstrument):
            The following are **rate parameters**.
 
     fixed_rate : float or None
-        The fixed rate applied to the :class:`~rateslib.legs.FixedLeg`. If `None`
+        The fixed rate applied to the :class:`~rateslib.legs.ZeroFixedLeg`. If `None`
         will be set to mid-market when curves are provided.
+
+        .. note::
 
+           The following parameters define **indexation**.
+
+    leg2_index_method : IndexMethod, str, :green:`optional (set by 'defaults')`
+        The interpolation method, or otherwise, to determine index values from reference dates.
+    leg2_index_lag: int, :green:`optional (set by 'defaults')`
+        The indexation lag, in months, applied to the determination of index values.
+    leg2_index_base: float, Dual, Dual2, Variable, :green:`optional`
+        The specific value applied as the base index value for all *Periods*.
+        If not given and ``index_fixings`` is a string fixings identifier that will be
+        used to determine the base index value.
+    leg2_index_fixings: float, Dual, Dual2, Variable, Series, str, 2-tuple or list, :green:`optional`
+        The index value for the reference date.
+        Best practice is to supply this value as string identifier relating to the global
+        ``fixings`` object.
         .. note::
 
            The following are **meta parameters**.
@@ -162,9 +221,6 @@ class ZCIS(_BaseInstrument):
     ``leg2_fixings``, but a cookbook article is also produced for
     :ref:`working with fixings <cook-fixings-doc>`.
 
-    Examples
-    --------
-    Construct a curve to price the example.
 
     """  # noqa: E501
 

python/rateslib/legs/__init__.py

@@ -3,6 +3,7 @@
 from rateslib.legs.custom import CustomLeg
 from rateslib.legs.fixed import FixedLeg, ZeroFixedLeg, ZeroIndexLeg
 from rateslib.legs.float import FloatLeg, ZeroFloatLeg
+from rateslib.legs.protocols import _BaseLeg
 
 __all__ = [
     "FixedLeg",
@@ -14,4 +15,5 @@
     "CreditProtectionLeg",
     "CustomLeg",
     "Amortization",
+    "_BaseLeg",
 ]

python/rateslib/periods/credit.py

@@ -61,6 +61,25 @@ class CreditPremiumPeriod(_BasePeriod):
 
     For *analytic delta* purposes the :math:`\xi=-S`.
 
+    .. rubric:: Examples
+
+    .. ipython:: python
+       :suppress:
+
+       from rateslib.periods import CreditPremiumPeriod
+       from datetime import datetime as dt
+
+    .. ipython:: python
+
+       cp = CreditPremiumPeriod(
+           start=dt(2000, 3, 20),
+           end=dt(2000, 6, 20),
+           payment=dt(2000, 6, 20),
+           frequency="Q",
+           fixed_rate=1.00,
+       )
+       cp.cashflows()
+
     .. role:: red
 
     .. role:: green
@@ -346,10 +365,32 @@ class CreditProtectionPeriod(_BasePeriod):
 
     The immediate expected valuation of the *Period* cashflow is defined as;
 
-    [TODO: NEEDS INPUT]
+    .. math::
+
+       \mathbb{E^Q}[V(m_T)C_T] = -N(1-RR) \int_{max(m_{a.s}, m_{today})}^{m_{a.e}} w_{loc:col}(m_s) Q(m_s) \lambda(s) ds
+
+    where the integral is numerically determined.
 
     There is no *analytical delta* for this *Period* type and hence :math:`\xi` is not defined.
 
+    .. rubric:: Examples
+
+    .. ipython:: python
+       :suppress:
+
+       from rateslib.periods import CreditProtectionPeriod
+       from datetime import datetime as dt
+
+    .. ipython:: python
+
+       cp = CreditProtectionPeriod(
+           start=dt(2000, 3, 20),
+           end=dt(2000, 6, 20),
+           payment=dt(2000, 6, 20),
+           frequency="Q",
+       )
+       cp.cashflows()
+
     .. role:: red
 
     .. role:: green