quantlib-xloil 0.0.1__tar.gz

quantlib_xloil-0.0.1/.github/workflows/ci.yml

@@ -0,0 +1,30 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: windows-latest
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v6
+
+    - name: Set up Python
+      uses: actions/setup-python@v6
+      with:
+        python-version: '3.14'
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -r requirements.txt
+
+    - name: Run tests
+      run: |
+        pytest tests/unittests -v

quantlib_xloil-0.0.1/.gitignore

@@ -0,0 +1,221 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+# VS Code settings
+.vscode/

quantlib_xloil-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sebastian Schlenkrich
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

quantlib_xloil-0.0.1/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: quantlib_xloil
+Version: 0.0.1
+Summary: Interface package to make QuantLib pricing library functions available in Excel.
+Project-URL: Homepage, https://github.com/frame-consulting/QuantLibXlOil
+Project-URL: Issues, https://github.com/frame-consulting/QuantLibXlOil/issues
+Author-email: Sebastian Schlenkrich <sebastian.schlenkrich@frame-consult.de>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Requires-Dist: quantlib
+Requires-Dist: xloil
+Description-Content-Type: text/markdown
+
+# QuantLibXlOil
+
+QuantLibXlOil is an interface package to make functions of the open-source [QuantLib](https://github.com/lballabio/QuantLib) pricing library available in Excel.
+
+The interface builds on the Python bindings for QuantLib via [QuantLib-SWIG](https://github.com/lballabio/QuantLib-SWIG).
+
+We use [xlOil](https://github.com/cunnane/xloil) to make the QuantLib Python objects and functions available in Excel.
+
+The QuantLibXlOil package largely contains wrapper functions in Python which delegate calls to QuantLib constructors and method/function call. The wrapper functions are made available to Excel via xlOil's function decorator. In addition, the package provides converter functions between Excel data types and QuantLib types.
+
+## Why Another QuantLib Interface?
+
+Excel is widely adapted in the industry as calculation tool and GUI for a large variety of use cases.
+
+QuantLib has the classical [QuantLibXL](https://www.quantlib.org/quantlibxl/) interface for Excel. However, QuantLibXL was last updated for QuantLib v1.22 (April 2021). The QuantLibXL object and interface specification is quite complex and closely linked to QuantLib internals. This makes maintenance quite challenging.
+
+The QuantLib Python interface is probably the best QuantLib interface in terms of coverage and maintenance. With the QuantLibXlOil package, we aim at leveraging the matured QuantLib Python interface.
+
+As an additional objective, we want to disentangle QuantLib developments from Excel interface development. This is particularly relevant for QuantLib C++ internals. For example, switching from `boost::something` to `std::something` should not affect the Excel interface. This motivates building on top of an existing high-level language interface.
+
+Linking between Python and Excel is a well understood task. There are [several tools](https://xloil.readthedocs.io/en/stable/Introduction.html#why-xloil-was-created) that implement that bridge. We opt for xlOil because it is open-source and works well for the use cases tested.
+
+## Getting Started
+
+The manual way...
+
+### Setup Python Environment
+
+Set up a Python environment via `conda` or `pip` and with the following packages:
+
+- `quanlib-python`,
+- `numpy`,
+- `pandas` (Version 2).
+
+### Install xlOil
+
+xlOil is available via pip and `pip install xloil`.
+
+Install the xlOil Excel add-in by running `xloil install` from the command line of the Python environment.
+
+Open Excel and create a new Workbook. The *xlOil Py* add-in should appear as a new ribbon.
+
+Navigate to the *xlOil Py* ribbon and select the Python environment with `xloil` package installed in the *Environment* drop-down menu.
+
+Run `=xloVersion()` in a Workbook cell. This should output version and build date details in the Excel cells.
+
+Details on getting started with xlOil are documented [here](https://xloil.readthedocs.io/en/stable/xlOil_Python/GettingStarted.html#getting-started).
+
+### Install QuantLibXlOil
+
+Clone the QuantLibXlOil repository.
+
+Add the complete path to `C:\...\QuantLibXlOil\src\` in the *Search Path* tet field.
+
+Add `quantlib_xloil` to the *Load Modules* text field. Use comma separator and *no* blanks. The resulting input of the *Load Modules* text field should then be:
+
+```
+xloil.xloil_ribbon,quantlib_xloil
+```
+
+Restart Excel and open a blank Workbook.
+
+Now, the QuantLibXlOil functions should be available in Excel.
+
+Test the QuantLibXlOil functions by typing `=qlVersion()` in an empty cell. This should give the QuantLib version number.
+

quantlib_xloil-0.0.1/README.md

@@ -0,0 +1,66 @@
+# QuantLibXlOil
+
+QuantLibXlOil is an interface package to make functions of the open-source [QuantLib](https://github.com/lballabio/QuantLib) pricing library available in Excel.
+
+The interface builds on the Python bindings for QuantLib via [QuantLib-SWIG](https://github.com/lballabio/QuantLib-SWIG).
+
+We use [xlOil](https://github.com/cunnane/xloil) to make the QuantLib Python objects and functions available in Excel.
+
+The QuantLibXlOil package largely contains wrapper functions in Python which delegate calls to QuantLib constructors and method/function call. The wrapper functions are made available to Excel via xlOil's function decorator. In addition, the package provides converter functions between Excel data types and QuantLib types.
+
+## Why Another QuantLib Interface?
+
+Excel is widely adapted in the industry as calculation tool and GUI for a large variety of use cases.
+
+QuantLib has the classical [QuantLibXL](https://www.quantlib.org/quantlibxl/) interface for Excel. However, QuantLibXL was last updated for QuantLib v1.22 (April 2021). The QuantLibXL object and interface specification is quite complex and closely linked to QuantLib internals. This makes maintenance quite challenging.
+
+The QuantLib Python interface is probably the best QuantLib interface in terms of coverage and maintenance. With the QuantLibXlOil package, we aim at leveraging the matured QuantLib Python interface.
+
+As an additional objective, we want to disentangle QuantLib developments from Excel interface development. This is particularly relevant for QuantLib C++ internals. For example, switching from `boost::something` to `std::something` should not affect the Excel interface. This motivates building on top of an existing high-level language interface.
+
+Linking between Python and Excel is a well understood task. There are [several tools](https://xloil.readthedocs.io/en/stable/Introduction.html#why-xloil-was-created) that implement that bridge. We opt for xlOil because it is open-source and works well for the use cases tested.
+
+## Getting Started
+
+The manual way...
+
+### Setup Python Environment
+
+Set up a Python environment via `conda` or `pip` and with the following packages:
+
+- `quanlib-python`,
+- `numpy`,
+- `pandas` (Version 2).
+
+### Install xlOil
+
+xlOil is available via pip and `pip install xloil`.
+
+Install the xlOil Excel add-in by running `xloil install` from the command line of the Python environment.
+
+Open Excel and create a new Workbook. The *xlOil Py* add-in should appear as a new ribbon.
+
+Navigate to the *xlOil Py* ribbon and select the Python environment with `xloil` package installed in the *Environment* drop-down menu.
+
+Run `=xloVersion()` in a Workbook cell. This should output version and build date details in the Excel cells.
+
+Details on getting started with xlOil are documented [here](https://xloil.readthedocs.io/en/stable/xlOil_Python/GettingStarted.html#getting-started).
+
+### Install QuantLibXlOil
+
+Clone the QuantLibXlOil repository.
+
+Add the complete path to `C:\...\QuantLibXlOil\src\` in the *Search Path* tet field.
+
+Add `quantlib_xloil` to the *Load Modules* text field. Use comma separator and *no* blanks. The resulting input of the *Load Modules* text field should then be:
+
+```
+xloil.xloil_ribbon,quantlib_xloil
+```
+
+Restart Excel and open a blank Workbook.
+
+Now, the QuantLibXlOil functions should be available in Excel.
+
+Test the QuantLibXlOil functions by typing `=qlVersion()` in an empty cell. This should give the QuantLib version number.
+

quantlib_xloil-0.0.1/conftest.py

@@ -0,0 +1,4 @@
+import sys
+import os
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "src"))

quantlib_xloil-0.0.1/pyproject.toml

@@ -0,0 +1,33 @@
+[project]
+name = "quantlib_xloil"
+dynamic = ["version"]
+authors = [
+  { name="Sebastian Schlenkrich", email="sebastian.schlenkrich@frame-consult.de" },
+]
+description = "Interface package to make QuantLib pricing library functions available in Excel."
+readme = "README.md"
+requires-python = ">=3.9"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: Microsoft :: Windows",
+]
+license = "MIT"
+license-files = ["LICEN[CS]E*"]
+dependencies = [
+  "QuantLib",
+  "xloil",
+]
+
+[project.urls]
+Homepage = "https://github.com/frame-consulting/QuantLibXlOil"
+Issues = "https://github.com/frame-consulting/QuantLibXlOil/issues"
+
+[build-system]
+requires = ["hatchling >= 1.26"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+path = "src/quantlib_xloil/__about__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/quantlib_xloil"]

quantlib_xloil-0.0.1/requirements.txt

@@ -0,0 +1,12 @@
+
+# May come from Conda
+pytest
+QuantLib-Python
+
+# pip dependencies
+xloil
+
+hatch  # For packaging
+build  # Build wheel
+twine  # Uploading to PyPI
+

quantlib_xloil-0.0.1/src/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-0.0.1/src/quantlib_xloil/__about__.py

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

quantlib_xloil-0.0.1/src/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 *