quantlib-xloil 0.0.1__py3-none-any.whl

quantlib_xloil/README.md

@@ -0,0 +1,145 @@
+# QuantLib-Python Wrappers for Excel
+
+This folder contains wrapper functions for QuantLib object creation and method calls.
+
+We follow the file structure of the [QuantLib-SWIG](https://github.com/lballabio/QuantLib-SWIG/tree/master/SWIG) interface specification to ensure transparency what the functions do.
+
+## Implementation Guidelines
+
+We apply the following guidelines for function implementation to ensure consistency across the Excel interface.
+
+The guidelines aim at mimicking the classical [QuantLibXL](https://github.com/eehlers/QuantLibAddin-Old/tree/master/QuantLibAddin/gensrc/metadata/functions) interface. If necessary or if it is deemed an improvement, we deviate from the QuantLibXL interface.
+
+### Function Names
+
+We use lower camel case function names with `ql` as prefix.
+
+Constructor function are identified by the class name, e.g., `Schedule`. We do not use `CreateSomeObject`, `MakeSomeObject` unless the SWIG interface specifies that function.
+
+Class member functions are identified by the class name concatenated with member function name. Class name corresponds to the class where the function is declared.
+
+### Function Argument Names and Types
+
+Function argument names follow the names of the SWIG interface names.
+
+Argument types are specified as type annotations. Build-in types (`str`, `int`, `float`, `bool`) are used directly.
+
+Dates from Excel are supplied as serial numbers. We use the `qDate` argument [converter function](https://xloil.readthedocs.io/en/stable/xlOil_Python/TypeConversion.html#custom-type-conversion) for type annotation.
+
+QuantLib object types are used directly as type annotations. User-created QuantLib object are stored in the xlOil cache and are supplied by xlOil as objects to the function.
+
+For enumerations and enumerated classes (e.g. calendars, day count conventions) we also use converter functions.
+
+Lists of inputs are specified as `xlo.Array(dims=1)`. This is applied for any underlying object types. Note that type checking and error handling is advised in the interface function.
+
+### Return Types
+
+Function results are returned as is.
+
+If the result type has a custom argument converter then a corresponding custom return [type conversion] (https://xloil.readthedocs.io/en/stable/xlOil_Python/TypeConversion.html#custom-return-conversion) should be implemented as well.
+
+Return type converters are use the function name prefix `x`, e.g., `xDate(...)` for conversion from `ql.Date` to excel serial number.
+
+### Function Annotations
+
+xlOil function annotations are specified as follows:
+
+```
+@xlo.func(
+    help='One-line docstring.',
+    args={
+        'Arg1': 'Help on Arg1 parameter.',
+        'Arg1': 'Help on Arg1 parameter.',
+    },
+    group=EXCEL_GROUP_NAME,
+    )
+def qlFunctionName(arg1 : Type1, arg2 : Type2, Trigger = None):
+    ...
+    return someThing
+```
+
+The arguments `help` and `args` are shown in Excel in the *Insert Function* (*fx*) dialog.
+
+Use Excel help strings for function and arguments equal/similar as in the classical [QuantLibXL](https://github.com/eehlers/QuantLibAddin-Old/tree/master/QuantLibAddin/gensrc/metadata/functions) interface.
+
+Help string is a capitalised sentence finished with punctuation.
+
+Excel argument names `Arg1` and `Arg2` equal function argument names but with starting capital letter.
+
+No Python docstring or Python docstring equals the Excel help string.
+
+### Additional Trigger Function Argument
+
+Functions should include an additional `Trigger` argument as specified in the section above. We use a capitalized variable (only) here, because optional parameters are not picked up in the Excel help strings. 
+
+QuantLib functions (may) depend on session data and QuantLib's internal state. As a consequence, updates may not be propagated through Excel's dependency tree.
+
+For example, the `Index.fixing(...)` method depends on the session-specific `evaluationDate`. However,  Excel cannot recognise a change in `evaluationDate` and re-calculate an `Index.fixing(...)`.
+
+Another example is the method `Instrument.NPV()`. This method requires a preceding call of `Instrument.setPricingEngine(engine)`. However, Excel on its own cannot determine that the pricing engine needs to be linked to the instrument before an NPV can be calculated. 
+
+To mitigate above limitation, the `Trigger` argument allows specifying additional input cells. That way, the QuantLib dependencies can be reflected in Excel's dependency graph by the user.
+
+### Enumerations and Enumerated Classes
+
+QuantLib uses various enumerations, e.g., for business day conventions (`Preceding`, `ModifiedFollowing`, `Following`) and volatility types (`Normal`, `ShiftedLognormal`).
+
+Similarly, class objects may specify behaviour of functions. Typical examples are `DayCounter` and `Calendar`.
+
+Enumerations and enumerated classes are represented by string identifiers in Excel.
+
+The string identifiers are mapped to QuantLib objects via (constant) dictionaries as follows.
+
+```
+QL_TYPE_NAME = {
+    'STRINGIDENTIER' : ql.Type1,
+    'STRINGIDENTIER' : ql.Type2,
+    ...
+}
+```
+
+Here, `TYPE_NAME` represents the QuantLib type, e.g. `BUSINESS_DAY_CONVENTION`, `CALENDAR`. Camel case names are replaced by upper case names with underscores.
+
+Dictionary keys are upper case.
+
+Dictionary entries are ordered alphabetically by key.
+
+Several identifiers may point to the same QuantLib object, e.g. `MODIFIEDFOLLOWING` and `MF` may point to `ql.ModifiedFollowing` business day convention.
+
+Text identifiers follow the [QuantLibXL enumerations specification](https://github.com/eehlers/QuantLibAddin-Old/tree/master/QuantLibAddin/gensrc/metadata/enumerations).
+
+### Argument Converter Functions
+
+[Argument converters](https://xloil.readthedocs.io/en/stable/xlOil_Python/TypeConversion.html#custom-type-conversion) are specified by `@xlo.converter()` decorator.
+
+Argument converter functions typically take an input string (from Excel) and convert it into a QuantLib class object or QuantLib enumeration (int) object.
+
+Argument converters also need to handle default values for QuantLib wrapper functions. Default values typically are QuantLib class object or QuantLib enumeration
+
+We use the following pattern and naming conventions for argument converters.
+
+```
+def _qSomeQuantLibType(s : string) -> ql.SomeQuantLibType
+    if isinstance(s, ql.SomeQuantLibType):
+        return s
+    [do actual conversion]
+    return quantlib_object
+
+@xlo.converter()
+def qSomeQuantLibType(s : string) -> ql.SomeQuantLibType
+    return _qSomeQuantLibType(s)
+
+def qlSomeQuantLibFunction(arg : qSomeQuantLibType = ql.SomeDefault())
+    ...
+    return
+```
+
+The similarities in prefixes `_q`, `q` and `ql.` and the common use of `SomeQuantLibType` naming aims at improving AI coding support.
+
+Note that the decorated functions `qSomeQuantLibType` are not accessible in Python. As a consequence, conversion implementation is delegated to separate functions `_qSomeQuantLibType`. The separate functions allow for testing conversions and manually calling conversions (if necessary).
+
+## Testing
+
+Each function should be covered by a test [here](../../tests/).
+
+Details on test case specification are documented [here](../../tests/README.md).

quantlib_xloil/__about__.py

@@ -0,0 +1 @@
+__version__ = "0.0.1"

quantlib_xloil/__init__.py

@@ -0,0 +1,14 @@
+from __about__ import __version__
+
+from quantlib_xloil.calendars import *
+from quantlib_xloil.cashflows import *
+from quantlib_xloil.currencies import *
+from quantlib_xloil.date import *
+from quantlib_xloil.daycounters import *
+from quantlib_xloil.interpolatedyieldcurves import *
+from quantlib_xloil.indexes import *
+from quantlib_xloil.quantlib_ import *
+from quantlib_xloil.rounding import *
+from quantlib_xloil.scheduler import *
+from quantlib_xloil.settings import *
+from quantlib_xloil.termstructures import *

quantlib_xloil/calendars.py

@@ -0,0 +1,351 @@
+import QuantLib as ql
+import xloil as xlo
+
+from .config import EXCEL_GROUP_NAME
+from .date import qDate, qPeriod, qWeekday, qTimeUnit
+from .utilities import first_key, UNKNOWN_KEY, UNKNOWN_VALUE, enum_value
+
+# Todo BespokeCalendars, explicit JointCalendars, JointCalenders and USCalenders
+
+QL_CALENDAR= {
+    "ARGENTINA": ql.Argentina,
+    "AUSTRALIA": ql.Australia, 
+    "AUSTRIA": ql.Austria,
+    "BOTSWANA": ql.Botswana,
+    "BRAZIL": ql.Brazil,
+    "CANADA": ql.Canada,
+    "CHILE": ql.Chile,
+    "CHINA": ql.China, 
+    "CZECHREPUBLIC": ql.CzechRepublic,
+    "DENMARK": ql.Denmark,
+    "FINLAND": ql.Finland,
+    "FRANCE": ql.France,
+    "GERMANY": ql.Germany,
+    "HONGKONG": ql.HongKong,
+    "HUNGARY": ql.Hungary,
+    "ICELAND": ql.Iceland,
+    "INDIA": ql.India,
+    "INDONESIA": ql.Indonesia,
+    "ISRAEL": ql.Israel,
+    "ITALY": ql.Italy,
+    "JAPAN": ql.Japan,
+    #"MALTA": ql.Malta,
+    "MEXICO": ql.Mexico,
+    #"MONTENEGRO": ql.Montenegro,
+    "NEWZEALAND": ql.NewZealand,
+    #"NORTHMACEDONIA": ql.NorthMacedonia,
+    "NORWAY": ql.Norway,
+    "POLAND": ql.Poland,
+    "ROMANIA": ql.Romania,
+    "RUSSIA": ql.Russia,
+    "SAUDIARABIA": ql.SaudiArabia,
+    #"SERBIA": ql.Serbia,
+    "SINGAPORE": ql.Singapore,
+    "SLOVAKIA": ql.Slovakia,
+    #"SLOVENIA": ql.Slovenia,
+    "SOUTHAFRICA": ql.SouthAfrica,
+    "SOUTHKOREA": ql.SouthKorea,
+    "SWEDEN": ql.Sweden,
+    "SWITZERLAND": ql.Switzerland,
+    "TAIWAN": ql.Taiwan,
+    "TARGET": ql.TARGET,
+    "THAILAND": ql.Thailand,
+    "TURKEY": ql.Turkey,
+    "UKRAINE": ql.Ukraine,
+    "UNITEDSTATES": ql.UnitedStates(ql.UnitedStates.NYSE),
+    "UNITEDKINGDOM": ql.UnitedKingdom,
+    #"UZBEKISTAN": ql.Uzbekistan,
+    "NULLCALENDAR": ql.NullCalendar,
+    "WEEKENDSONLY": ql.WeekendsOnly,
+    "JOINTCALENDAR": ql.JointCalendar,
+    UNKNOWN_KEY: UNKNOWN_VALUE,
+}
+
+QL_BUSINESSDAYCONVENTION = {
+    "FOLLOWING": ql.Following,
+    "PRECEDING": ql.Preceding,
+    "MODIFIEDFOLLOWING": ql.ModifiedFollowing,
+    "MODIFIEDPRECEDING": ql.ModifiedPreceding,
+    "UNADJUSTED": ql.Unadjusted,
+    "HALFMONTHMODIFIEDFOLLOWING": ql.HalfMonthModifiedFollowing,
+    "NEAREST": ql.Nearest,
+}
+
+QL_JOINTCALENDARRULE = {
+    "JOINHOLIDAYS": ql.JoinHolidays,
+    "JOINBUSINESSDAYS": ql.JoinBusinessDays,
+}
+
+def _qCalendar(name : str) -> ql.Calendar:
+    if isinstance(name, ql.Calendar): # capture default argument values
+        return name
+    if isinstance(name, str):
+        name = name.strip().upper()
+        if name in QL_CALENDAR:
+            return QL_CALENDAR[name]()
+    raise ValueError(f"Unknown calendar: {name}")
+
+@xlo.converter()
+def qCalendar(calendarname : str) -> ql.Calendar:
+    return _qCalendar(calendarname)
+
+@xlo.returner(target=ql.Calendar, register=True)
+def xCalendar(calendar : ql.Calendar):
+    return calendar.name()
+
+def _qBusinessDayConvention(conventionname : str):
+    return enum_value(conventionname, QL_BUSINESSDAYCONVENTION)
+
+@xlo.converter()
+def qBusinessDayConvention(conventionname : str):
+    return _qBusinessDayConvention(conventionname)
+
+
+def _qJointCalendarRule(rule_name : str):
+    return enum_value(rule_name, QL_JOINTCALENDARRULE)
+
+@xlo.converter()
+def qJointCalendarRule(rule_name : str):
+    return _qJointCalendarRule(rule_name)
+
+@xlo.func(
+    help='Return a QuantLib Calendar object given its name.',
+    args={
+        'CalendarName': 'The name of the calendar.',
+    },
+    group=EXCEL_GROUP_NAME,
+)
+
+def qlCalendar(calendar_name: str, Trigger = None) -> ql.Calendar:
+    return _qCalendar(calendar_name)
+
+@xlo.func(
+    help='Check if a day is a weekend day.',
+    args={
+        'Weekday': 'The day of the week (0=Sunday, 1=Monday, ..., 6=Saturday).',
+    },
+    group=EXCEL_GROUP_NAME,
+)  
+def qlCalendarisWeekend(calendar: qCalendar, weekday: qWeekday, Trigger = None) -> bool:
+    return calendar.isWeekend(weekday)
+#weekday in (ql.Saturday, ql.Sunday)
+
+@xlo.func(
+    help='Return the first day of the month for a given date.',
+    args={
+        'Date': 'The date for which to find the start of the month.',
+    },
+    group=EXCEL_GROUP_NAME,
+)
+
+def qlCalendarStartOfMonth(calendar : qCalendar, date : qDate, Trigger = None) -> ql.Date:
+    return calendar.startOfMonth(date) 
+#l.Date(ql.startOfMonth(date))
+
+@xlo.func(
+    help='Return the last day of the month for a given date.',
+    args={
+        'Date': 'The date for which to find the end of the month.',
+    },
+    group=EXCEL_GROUP_NAME,
+)
+def qlCalendarEndOfMonth(calendar : qCalendar, date : qDate, Trigger = None) -> ql.Date:
+    return calendar.endOfMonth(date) 
+#ql.Date(ql.endOfMonth(date))
+
+@xlo.func(
+    help='Check if a date is a business day.',
+    args={
+        'Date': 'The date to check.',
+    },
+    group=EXCEL_GROUP_NAME,
+)
+def qlCalendarIsBusinessDay(calendar : qCalendar, date : qDate, Trigger = None) -> bool:
+    return calendar.isBusinessDay(date)
+
+@xlo.func(
+    help='Check if a date is a holiday.',
+    args={
+        'Date': 'The date to check.',
+    },
+    group=EXCEL_GROUP_NAME,
+)
+def qlCalendarIsHoliday(calendar : qCalendar, date : qDate, Trigger = None) -> bool:
+    return calendar.isHoliday(date) 
+
+@xlo.func(
+    help='Check if a date is the end of the month.',
+    args={
+        'Date': 'The date to check.',
+    },
+    group=EXCEL_GROUP_NAME,
+)
+def qlCalendarIsEndOfMonth(calendar : qCalendar, date : qDate, Trigger = None) -> bool:
+    return calendar.isEndOfMonth(date)
+
+@xlo.func(
+    help='Check if a date is the start of the month.',
+    args={
+        'Date': 'The date to check.',
+    },
+    group=EXCEL_GROUP_NAME,
+)
+def qlCalendarIsStartOfMonth(calendar : qCalendar, date : qDate, Trigger = None) -> bool:
+    return calendar.isStartOfMonth(date)
+
+@xlo.func(
+    help='Add a holiday to the calendar.',
+    args={
+        'Date': 'The date to add as a holiday.',
+    },
+    group=EXCEL_GROUP_NAME,
+)
+def qlCalendarAddHoliday(calendar : qCalendar, date : qDate, Trigger = None) -> None:
+    calendar.addHoliday(date)
+
+@xlo.func(
+    help='Remove a holiday from the calendar.',
+    args={
+        'Date': 'The date to remove as a holiday.',
+    },
+    group=EXCEL_GROUP_NAME,
+)
+def qlCalendarRemoveHoliday(calendar :qCalendar, date : qDate, Trigger = None) -> None:
+    calendar.removeHoliday(date)
+
+@xlo.func(
+    help='Reset the added and removed holidays for the calendar.',
+    args={},
+    group=EXCEL_GROUP_NAME,
+)
+def qlCalendarResetAddedAndRemovedHolidays(calendar : qCalendar, Trigger = None) -> None:
+    calendar.resetAddedAndRemovedHolidays()
+
+
+@xlo.func(
+    help='Adjust a date according to the calendar and business day convention.',
+    args={
+        'Date': 'The date to adjust.',
+        'Calendar': 'The calendar to use for adjustment.',
+        'Convention': 'The business day convention to apply.',
+    },
+    group=EXCEL_GROUP_NAME,
+)
+
+def qlCalendarAdjust(calendar : qCalendar, date : qDate,  convention : qBusinessDayConvention = "Following", Trigger = None) -> ql.Date:
+    return  calendar.adjust(date, convention)
+
+@xlo.func(
+    help='Advance a date by a given number of time units according to the calendar and business day convention.',
+    args={
+        'Date': 'The date to advance.',
+        'Calendar': 'The calendar to use for advancement.',
+        'n': 'The number of time units to advance',
+        'unit': 'The time unit to advance (e.g. "DAYS", "MONTHS", "YEARS").',
+        'Convention': 'The business day convention to apply.',
+        'EndOfMonth': 'Whether to adjust to the end of the month.',
+    },
+    group=EXCEL_GROUP_NAME,
+)   
+def qlCalendarAdvance(calendar : qCalendar, date : qDate, n : int, unit : qTimeUnit, convention : qBusinessDayConvention = "Following", end_of_month : bool = False, Trigger = None) -> ql.Date:
+    return calendar.advance(date, n, unit, convention, end_of_month)
+   
+@xlo.func(
+    help='Advance a date by a given period according to the calendar and business day convention.',
+    args={
+        'Date': 'The date to advance.',
+        'Calendar': 'The calendar to use for advancement.',
+        'Period': 'The period by which to advance.',
+        'Convention': 'The business day convention to apply.',
+        'EndOfMonth': 'Whether to adjust to the end of the month.',
+    },
+    group=EXCEL_GROUP_NAME,
+)
+def qlCalendarAdvance2(calendar : qCalendar, date : qDate, period : qPeriod, convention : qBusinessDayConvention = "Following", end_of_month : bool = False, Trigger = None) -> ql.Date:
+    return calendar.advance(date, period, convention, end_of_month)
+
+
+@xlo.func(
+    help='Return the number of business days between two QuantLib Dates according to the calendar.',
+    args={
+        'Calendar': 'The calendar to use.',
+        'FromDate': 'The starting date.',
+        'ToDate': 'The ending date.',
+        'IncludeFirst': 'Whether to include the first date.',
+        'IncludeLast': 'Whether to include the last date.',
+    },
+    group=EXCEL_GROUP_NAME,
+)
+def qlCalendarBusinessDaysBetween(calendar : qCalendar, from_date : qDate, to_date : qDate, includeFirst : bool = True, includeLast : bool = False, Trigger = None) -> int:
+    return calendar.businessDaysBetween(from_date, to_date, includeFirst, includeLast)
+
+@xlo.func(
+    help='Return the list of holidays in the calendar.',
+    args={
+        'Calendar': 'The calendar for which to list holidays.',
+    },
+    group=EXCEL_GROUP_NAME,
+)
+def qlCalendarHolidayList(calendar : qCalendar, from_date : qDate, to_date : qDate,Trigger = None) -> list:
+    return list(calendar.holidayList(from_date, to_date)) 
+
+
+@xlo.func(
+    help='Return the list of business days in the calendar.',
+    args={
+        'Calendar': 'The calendar for which to list business days.',
+    },
+    group=EXCEL_GROUP_NAME,
+)
+def qlCalendarBusinessDayList(calendar : qCalendar, from_date : qDate, to_date : qDate, Trigger = None) -> list:
+    return list(calendar.businessDayList(from_date, to_date))
+
+@xlo.func(
+    help='Return the name of the calendar.',
+    args={
+        'Calendar': 'The calendar for which to get the name.',
+    },
+    group=EXCEL_GROUP_NAME,
+)
+def qlCalendarName(calendar : qCalendar, Trigger = None) -> str:
+    return calendar.name()
+
+@xlo.func(
+    help='Check if the calendar is empty.',
+    args={
+        'Calendar': 'The calendar to check.',
+    },
+    group=EXCEL_GROUP_NAME,
+)
+def qlCalendarEmpty(calendar : qCalendar, Trigger = None) -> bool:
+    return calendar.empty()
+
+@xlo.func(
+    help='Return a calendar that represents the union of two calendars.',
+    args={
+        'Calendar1': 'The first calendar.',
+        'Calendar2': 'The second calendar.',
+        'Rule': 'The rule for combining the calendars.',
+    },
+    group=EXCEL_GROUP_NAME,
+)
+def qlCalendarJointCalendar(calendar1 : qCalendar, calendar2 : qCalendar, rule : qJointCalendarRule =  "JOINHOLIDAYS") -> ql.Calendar:
+    return ql.JointCalendar(calendar1, calendar2, rule)
+
+@xlo.func(
+    help='Return a calendar that represents the union of three calendars.',
+    args={
+        'Calendar1': 'The first calendar.',
+        'Calendar2': 'The second calendar.',
+        'Calendar3': 'The third calendar.',
+        'Rule': 'The rule for combining the calendars.',
+    },
+    group=EXCEL_GROUP_NAME,
+)
+def qlCalendarJointCalendar2(calendar1 : qCalendar, calendar2 : qCalendar, calendar3 : qCalendar, rule : qJointCalendarRule =  "JOINHOLIDAYS", Trigger = None) -> ql.Calendar:
+    return ql.JointCalendar(calendar1, calendar2, calendar3, rule)
+
+
+
+
+