This commit adds and improves numpydoc-style docstrings across several modules, enhancing the overall documentation of the library.

The following modules and their classes have been documented:
- `quantlib/time`: `Date`, `Period`, `Calendar`
- `quantlib/termstructures/yields`: `FlatForward`, `ForwardSpreadedTermStructure`, `ImpliedTermStructure`
- `quantlib/quotes`: `SimpleQuote`, `FuturesConvAdjustmentQuote`
- `quantlib/indexes`: `IborIndex`, `OvernightIndex`, `InflationIndex`, `ZeroInflationIndex`, `YoYInflationIndex`
- `quantlib/instruments`: `Instrument`, `Swap`, `VanillaSwap`, `EuropeanOption`, `Forward`
- `quantlib/instruments/bonds`: `Bond`, `Price`, `FixedRateBond`, `FloatingRateBond`, `ZeroCouponBond`, `CPIBond`

The docstrings now use fully qualified type hints to support documentation generation and cross-referencing. The `Parameters` sections have been moved to the class docstrings for consistency.

Additionally, a bug in the `is_end_of_month` method in `quantlib/time/calendar.pyx` has been corrected.

This branch has been rebased on top of the `ois` branch.

Author: google-labs-jules[bot]

.gitignore

@@ -6,6 +6,7 @@ quantlib.egg-info/*
 QuantLib.dll
 symbol_win*.def
 *.cpp
+!quantlib/cpp_layer/*.cpp
 *.so
 *.h
 *.pyc

MANIFEST.in

@@ -1,39 +1,31 @@
+wheel:
+	python -m build --wheel -n -C--global-option=build_ext -C--global-option=-j6
+
 build:
 	python setup.py build_ext --inplace -j 8
 
-build2:
-	python2 setup.py build_ext --inplace -j 8
-
 docs:
+	-rm -rf docs/source/_autosummary
 	make -C docs html
 
 install:
-	pip install .
+	pip install . -C--global-option=build_ext -C--global-option=-j6
 
 uninstall:
 	pip uninstall quantlib
 
-tests-preload:
-	LD_PRELOAD=/opt/QuantLib-1.1/lib/libQuantLib.so nosetests -v quantlib/test
-
 tests: build
 	python -m unittest discover -v
 
-tests2: build2
-	python2 -m unittest discover -v
-
-build_ex:
-	g++ -m32 -I/opt/local/include/ -I/opt/local/include/boost quantlib_test2.cpp \
-    -o test2 -L/opt/local/lib/ -lQuantLib
-
 clean:
 	find quantlib -name \*.so -exec rm {} +
 	find quantlib -name \*.pyc -exec rm {} +
-	find quantlib -name \*.cpp -exec rm {} +
+	find quantlib -path quantlib/cpp_layer -prune -o -name \*.cpp -exec rm {} +
 	find quantlib -name \*.c -exec rm {} +
 	find quantlib -name \*.h -exec rm {} +
 	-rm quantlib/termstructures/yields/{piecewise_yield_curve,discount_curve,forward_curve,zero_curve}.{pxd,pyx}
+	-rm quantlib/handle.{pxd,pyx}
 	rm -rf build
 	rm -rf dist
 
-.PHONY: build build2 docs clean
+.PHONY: build docs clean

Makefile

@@ -195,8 +195,8 @@
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, documentclass [howto/manual]).
 latex_documents = [
-  ('index', 'Quantlibcythonwrapper.tex', u'Quantlib cython wrapper Documentation',
-   u'Didrik Pinte \& Patrick Hénaff', 'manual'),
+  ('index', 'Quantlibcythonwrapper.tex', 'Quantlib cython wrapper Documentation',
+   'Didrik Pinte & Patrick Hénaff', 'manual'),
 ]
 
 # The name of an image file (relative to this directory) to place at the top of

docs/source/conf.py

@@ -7,15 +7,15 @@
  FOR A PARTICULAR PURPOSE.  See the license for more details.
 """
 from quantlib.instruments.api import AmericanExercise, VanillaOption, OptionType
-from quantlib.instruments.payoffs import PlainVanillaPayoff
+from quantlib.payoffs import PlainVanillaPayoff
 from quantlib.pricingengines.api import BaroneAdesiWhaleyApproximationEngine
 from quantlib.pricingengines.api import FdBlackScholesVanillaEngine
 from quantlib.processes.black_scholes_process import BlackScholesMertonProcess
 from quantlib.quotes import SimpleQuote
 from quantlib.settings import Settings
 from quantlib.time.api import Actual365Fixed, Date, May, TARGET
-from quantlib.termstructures.volatility.api import BlackConstantVol
-from quantlib.termstructures.yields.api import HandleYieldTermStructure, FlatForward
+from quantlib.termstructures.volatility.api import BlackConstantVol, HandleBlackVolTermStructure
+from quantlib.termstructures.yields.api import RelinkableHandleYieldTermStructure, FlatForward
 from quantlib.methods.finitedifferences.solvers.fdmbackwardsolver \
     import FdmSchemeDesc
 
@@ -25,7 +25,7 @@ def main():
     Settings.instance().evaluation_date = todays_date
     settlement_date = Date(17, May, 1998)
 
-    risk_free_rate = HandleYieldTermStructure()
+    risk_free_rate = RelinkableHandleYieldTermStructure()
     risk_free_rate.link_to(
         FlatForward(
             reference_date=settlement_date,
@@ -43,9 +43,11 @@ def main():
 
     # market data
     underlying = SimpleQuote(36.0)
-    volatility = BlackConstantVol(todays_date, TARGET(), 0.20,
+    volatility = HandleBlackVolTermStructure(
+            BlackConstantVol(todays_date, TARGET(), 0.20,
                                   Actual365Fixed())
-    dividend_yield = HandleYieldTermStructure()
+            )
+    dividend_yield = RelinkableHandleYieldTermStructure()
     dividend_yield.link_to(
         FlatForward(
             reference_date=settlement_date,

examples/american_option.py

@@ -9,7 +9,7 @@
 from quantlib.quotes import SimpleQuote
 from quantlib.settings import Settings
 from quantlib.time.api import TARGET, Actual365Fixed, today
-from quantlib.termstructures.yields.api import FlatForward, HandleYieldTermStructure
+from quantlib.termstructures.yields.api import FlatForward, RelinkableHandleYieldTermStructure
 from quantlib.termstructures.volatility.api import BlackConstantVol
 
 
@@ -36,8 +36,8 @@
 underlyingH = SimpleQuote(underlying)
 
 # bootstrap the yield/dividend/vol curves
-flat_term_structure = HandleYieldTermStructure()
-flat_dividend_ts = HandleYieldTermStructure()
+flat_term_structure = RelinkableHandleYieldTermStructure()
+flat_dividend_ts = RelinkableHandleYieldTermStructure()
 
 flat_term_structure.link_to(
     FlatForward(

examples/basic_example.py

@@ -44,7 +44,7 @@
 from quantlib.termstructures.yields.api import (
     PiecewiseYieldCurve, DepositRateHelper, BootstrapTrait, HandleYieldTermStructure
 )
-from quantlib.termstructures.volatility.api import BlackConstantVol
+from quantlib.termstructures.volatility.api import BlackConstantVol, HandleBlackVolTermStructure
 from quantlib.termstructures.yields.api import SwapRateHelper
 
 def dividendOption():
@@ -169,7 +169,7 @@ def dividendOption():
 
     print('Creating process')
 
-    bsProcess = BlackScholesProcess(underlying_priceH, HandleYieldTermStructure(riskFreeTS), flatVolTS)
+    bsProcess = BlackScholesProcess(underlying_priceH, HandleYieldTermStructure(riskFreeTS), HandleBlackVolTermStructure(flatVolTS))
 
 
     # ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

examples/data/df_SPX_24jan2011.pkl

@@ -1,16 +1,15 @@
-from __future__ import print_function
 # -*- coding: utf-8 -*-
 # <nbformat>3</nbformat>
 
 # <markdowncell>
 
 # Standardized Option Quotes Data Format
 # ======================================
-# 
+#
 # To facilitate model calibration, a standard input format has been defined, which contains all the
 # necessary data. The data is held in a [Panda](http://pandas.pydata.org) table, with one row per quote and
 # 8 columns, as follows:
-# 
+#
 # * dtTrade: Quote date, or time stamp
 # * Strike: Ditto
 # * dtExpiry: Option expiry date
@@ -19,23 +18,23 @@
 # * Type: European/American
 # * PBid: Bid price
 # * PAsk: Ask price
-# 
-# Note that we do not include the dividend yield nor the risk-free rate in the data set: The 
+#
+# Note that we do not include the dividend yield nor the risk-free rate in the data set: The
 # implied forward price and risk-free rate are estimated from the call/put parity.
-# 
+#
 # SPX Option Data Processing
 # --------------------------
-# 
+#
 # As an illustration, we provide below the procedure for converting raw SPX option data, as published by the [CBOE](http://www.cboe.com/DelayedQuote/QuoteTableDownload.aspx), into the standard input format.
-# 
+#
 # ### SPX Utility functions
-# 
+#
 # These functions parse the SPX option names, and extract expiry date and strike.
 
 # <codecell>
 
-import pandas
-import dateutil, datetime
+import pandas as pd
+import dateutil
 import re
 
 def ExpiryMonth(s):
@@ -58,26 +57,26 @@ def parseSPX(s):
     """
     Parse an SPX quote string, return expiry date and strike
     """
-    tokens = spx_symbol.split(s)
+    tokens = spx_symbol.split(s.iloc[0])
 
     if len(tokens) == 1:
-        return {'dtExpiry': None, 'strike': -1}
+        return {'Strike': -1, 'dtExpiry': None}
 
     year = 2000 + int(tokens[1])
     day = int(tokens[2])
     month = ExpiryMonth(tokens[3])
     strike = float(tokens[4])
 
-    dtExpiry = datetime.date(year, month, day)
+    dtExpiry = pd.Timestamp(year=year, month=month, day=day)
 
-    return ({'dtExpiry': dtExpiry, 'strike': strike})
+    return {'Strike': strike, 'dtExpiry': dtExpiry}
 
 
 # <markdowncell>
 
 # ### Reading the SPX raw data file
-# 
-# The csv file downloaded from the CBOE site can be converted into a standard panda table by the following function. 
+#
+# The csv file downloaded from the CBOE site can be converted into a standard panda table by the following function.
 
 # <codecell>
 
@@ -93,12 +92,12 @@ def read_SPX_file(option_data_file):
 
         lineTwo = fid.readline()
         dt = lineTwo.split('@')[0]
-        dtTrade = dateutil.parser.parse(dt).date()
+        dtTrade = pd.to_datetime(dt)
 
         print('Dt Calc: %s Spot: %f' % (dtTrade, spot))
 
     # read all option price records as a data frame
-    df = pandas.io.parsers.read_csv(option_data_file, header=0, sep=',', skiprows=[0,1])
+    df = pd.read_csv(option_data_file, header=0, sep=',', skiprows=[0,1])
 
     # split and stack calls and puts
     call_df = df[['Calls', 'Bid', 'Ask']]
@@ -109,35 +108,28 @@ def read_SPX_file(option_data_file):
     put_df = put_df.rename(columns = {'Puts':'Spec', 'Bid.1':'PBid',
     'Ask.1':'PAsk'})
     put_df['Type'] = 'P'
-
-    df_all = call_df.append(put_df,  ignore_index=True)
+    df_all = pd.concat([call_df, put_df],  ignore_index=True)
 
     # parse Calls and Puts columns for strike and contract month
     # insert into data frame
-
-    cp = [parseSPX(s) for s in df_all['Spec']]
-    df_all['Strike'] = [x['strike'] for x in cp]
-    df_all['dtExpiry'] = [x['dtExpiry'] for x in cp]
-
+    df_all = pd.concat([df_all,
+                        df_all[["Spec"]].apply(parseSPX, axis="columns", result_type="expand")],
+                        axis=1)
     del df_all['Spec']
 
     df_all = df_all[(df_all['Strike'] > 0) & (df_all['PBid']>0) \
                     & (df_all['PAsk']>0)]
 
     df_all['dtTrade'] = dtTrade
     df_all['Spot'] = spot
-
     return df_all
 
-option_data_file = \
-    '../data/SPX-Options-24jan2011.csv'
-
 if __name__ == '__main__':
+    option_data_file = '../data/SPX-Options-24jan2011.csv'
     df_SPX = read_SPX_file(option_data_file)
     print('%d records processed' % len(df_SPX))
 
     # save a csv file and pickled data frame
     df_SPX.to_csv('../data/df_SPX_24jan2011.csv', index=False)
-    df_SPX.to_pickle('../data/df_SPX_24jan2011.pkl', protocol=4)
+    df_SPX.to_pickle('../data/df_SPX_24jan2011.pkl')
     print('File saved')
-

examples/option_valuation.py

@@ -1,5 +1,3 @@
-from __future__ import division
-from __future__ import print_function
 # -*- coding: utf-8 -*-
 # <nbformat>3</nbformat>
 
@@ -22,7 +20,6 @@
 import pandas
 from pandas import DataFrame
 import datetime
-from six.moves import input
 
 from quantlib.models.equity.heston_model import (
     HestonModelHelper, HestonModel)