Metadata-Version: 2.2
Name: pyquantlib
Version: 0.7.0
Summary: Python bindings for QuantLib
Keywords: quantlib,quantitative-finance,derivatives,pricing,risk,fixed-income,options,finance,pybind11
Author-Email: Yassine Idyiahia <yassine.id@gmail.com>
Maintainer-Email: Yassine Idyiahia <yassine.id@gmail.com>
License: BSD 3-Clause License
         
         Copyright (c) 2025 Yassine Idyiahia
         All rights reserved.
         
         Redistribution and use in source and binary forms, with or without
         modification, are permitted provided that the following conditions are met:
         
         1. Redistributions of source code must retain the above copyright notice, this
            list of conditions and the following disclaimer.
         
         2. Redistributions in binary form must reproduce the above copyright notice,
            this list of conditions and the following disclaimer in the documentation
            and/or other materials provided with the distribution.
         
         3. Neither the name of the copyright holder nor the names of its
            contributors may be used to endorse or promote products derived from
            this software without specific prior written permission.
         
         THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
         AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
         IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
         DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
         FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
         DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
         SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
         CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
         OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
         OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
         
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Programming Language :: C++
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Typing :: Typed
Project-URL: Homepage, https://github.com/quantales/pyquantlib
Project-URL: Documentation, https://pyquantlib.readthedocs.io
Project-URL: Repository, https://github.com/quantales/pyquantlib
Project-URL: Issues, https://github.com/quantales/pyquantlib/issues
Project-URL: Changelog, https://pyquantlib.readthedocs.io/en/latest/changelog.html
Requires-Python: >=3.10
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: ruff>=0.4.0; extra == "dev"
Requires-Dist: pybind11-stubgen>=2.5.0; extra == "dev"
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: numpy>=1.20.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=7.0; extra == "docs"
Requires-Dist: furo>=2024.0; extra == "docs"
Requires-Dist: myst-parser>=3.0; extra == "docs"
Requires-Dist: sphinx-copybutton>=0.5; extra == "docs"
Provides-Extra: examples
Requires-Dist: jupyter>=1.0.0; extra == "examples"
Requires-Dist: matplotlib>=3.5.0; extra == "examples"
Requires-Dist: pandas>=1.3.0; extra == "examples"
Requires-Dist: numpy>=1.20.0; extra == "examples"
Provides-Extra: all
Requires-Dist: pyquantlib[dev,docs,examples]; extra == "all"
Description-Content-Type: text/markdown

# PyQuantLib: Modern Python bindings for QuantLib

[![Documentation](https://readthedocs.org/projects/pyquantlib/badge/?version=latest)](https://pyquantlib.readthedocs.io/en/latest/?badge=latest)
[![macOS](https://github.com/quantales/pyquantlib/actions/workflows/macos.yml/badge.svg)](https://github.com/quantales/pyquantlib/actions/workflows/macos.yml)
[![Linux](https://github.com/quantales/pyquantlib/actions/workflows/linux.yml/badge.svg)](https://github.com/quantales/pyquantlib/actions/workflows/linux.yml)
[![Windows](https://github.com/quantales/pyquantlib/actions/workflows/windows.yml/badge.svg)](https://github.com/quantales/pyquantlib/actions/workflows/windows.yml)
[![codecov](https://codecov.io/github/quantales/pyquantlib/graph/badge.svg?token=Q1HNBAK7S1)](https://codecov.io/github/quantales/pyquantlib)
[![PyPI](https://img.shields.io/pypi/v/pyquantlib.svg)](https://pypi.org/project/pyquantlib/)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.18529027.svg)](https://doi.org/10.5281/zenodo.18529027)
[![License](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg)](https://github.com/quantales/pyquantlib/blob/main/LICENSE)
[![Python](https://img.shields.io/badge/Python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/quantales/pyquantlib/blob/main/CONTRIBUTING.md)

## Overview

PyQuantLib provides Python bindings for [QuantLib](https://www.quantlib.org/), the open-source library for quantitative finance. Built with [pybind11](https://github.com/pybind/pybind11), it offers a more Pythonic API than existing alternatives.

## Features

- **Pythonic API**: Pass Python objects directly to functions (implicit conversion)
- **Zero-copy NumPy**: Buffer protocol for efficient, bidirectional data exchange
- **Type hints**: IDE-friendly with complete `.pyi` stub files
- **Python subclassing**: Extend QuantLib classes without C++ recompilation
- **Modern build**: scikit-build-core, CMake presets, cross-platform CI/CD

## Installation

```bash
pip install pyquantlib
```

Pre-built wheels are available for Python 3.10--3.13 on Linux (x86_64), macOS (ARM), and Windows (x64). QuantLib is statically linked -- no separate installation required.

### From Source

Building from source requires QuantLib built with specific CMake flags. See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed instructions.

#### Prerequisites

- Python 3.10+
- CMake 3.18+
- C++17 compatible compiler
- Boost headers
- **QuantLib 1.40+** built with `std::shared_ptr` support (see below)

#### QuantLib Build Requirement

> **Important**: PyQuantLib requires QuantLib built from source with specific settings.

**Required CMake flags:**

```bash
cmake -DBUILD_SHARED_LIBS=OFF \
      -DCMAKE_POSITION_INDEPENDENT_CODE=ON \
      -DQL_USE_STD_SHARED_PTR=ON \
      -DCMAKE_MSVC_RUNTIME_LIBRARY=MultiThreadedDLL \  # Windows only
      -DCMAKE_BUILD_TYPE=Release \
      ...
```

| Flag | Why Required |
|------|--------------|
| `BUILD_SHARED_LIBS=OFF` | Static build prevents Settings singleton issues on Linux/macOS |
| `CMAKE_POSITION_INDEPENDENT_CODE=ON` | Required for static libs in Python modules |
| `QL_USE_STD_SHARED_PTR=ON` | pybind11 uses `std::shared_ptr` as default holder |
| `CMAKE_MSVC_RUNTIME_LIBRARY=MultiThreadedDLL` | **Windows only**: Python extensions require dynamic runtime (`/MD`) |

**Note**: Pre-built packages (Homebrew, vcpkg, apt) use shared builds and `boost::shared_ptr` -- they are **not compatible**. You must build QuantLib from source. See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed build instructions.

```bash
pip install git+https://github.com/quantales/pyquantlib.git
```

## Quick Start

```python
import pyquantlib as ql

# Set evaluation date
today = ql.Date(15, 6, 2025)
ql.Settings.evaluationDate = today

# Market data
spot = ql.SimpleQuote(100.0)
rate = ql.SimpleQuote(0.05)
vol = ql.SimpleQuote(0.20)

# Term structures (pass quotes directly, handles created internally)
dc = ql.Actual365Fixed()
risk_free = ql.FlatForward(today, rate, dc)
dividend = ql.FlatForward(today, 0.0, dc)
volatility = ql.BlackConstantVol(today, ql.TARGET(), vol, dc)

# Black-Scholes process (pass objects directly)
process = ql.GeneralizedBlackScholesProcess(spot, dividend, risk_free, volatility)

# European call option
payoff = ql.PlainVanillaPayoff(ql.Call, 100.0)
exercise = ql.EuropeanExercise(today + ql.Period("1Y"))
option = ql.VanillaOption(payoff, exercise)

# Price with analytic Black-Scholes
option.setPricingEngine(ql.AnalyticEuropeanEngine(process))

print(f"NPV:   {option.NPV():.4f}")
print(f"Delta: {option.delta():.4f}")
print(f"Gamma: {option.gamma():.4f}")
print(f"Vega:  {option.vega():.4f}")
print(f"Theta: {option.theta():.4f}")
```

Output:
```
NPV:   10.4506
Delta: 0.6368
Gamma: 0.0188
Vega:  37.5240
Theta: -6.4140
```

## Module Organization

```python
import pyquantlib as ql          # Concrete classes
from pyquantlib.base import ...  # Abstract base classes (for subclassing)
```

Coverage includes dates and calendars, market quotes, yield and volatility term structures, stochastic processes, instruments, and pricing engines. See the [API Reference](https://pyquantlib.readthedocs.io/en/latest/api/index.html) for the complete list.

## Development

See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.

```bash
# Clone and install in development mode
git clone https://github.com/quantales/pyquantlib.git
cd pyquantlib
python -m venv venv
source venv/bin/activate  # or venv\Scripts\activate on Windows
python -m pip install --upgrade pip
pip install -r requirements-dev.txt
pip install -e .

# Run tests
pytest
```

## Documentation

Full documentation is available at [pyquantlib.readthedocs.io](https://pyquantlib.readthedocs.io/). For the latest additions, see the [changelog](https://pyquantlib.readthedocs.io/en/latest/changelog.html).

## Examples

See the [examples](examples/) directory for Jupyter notebooks demonstrating PyQuantLib usage.

## License

BSD 3-Clause License. See [LICENSE](LICENSE) for details.

## Acknowledgments

- [QuantLib](https://www.quantlib.org/) - Quantitative finance library
- [pybind11](https://github.com/pybind/pybind11) - C++/Python bindings
- [scikit-build-core](https://github.com/scikit-build/scikit-build-core) - Build system

