Skip to main content

Rust-powered collection of financial functions.

Project description

rust-lang.org License pypi versions

PyXIRR

Rust-powered collection of financial functions.

Features:

  • correct
  • blazingly fast
  • works with iterators
  • works with unordered input
  • no external dependencies

Installation

pip install pyxirr

Benchmarks

Rust implementation has been tested against existing xirr package (uses scipy.optimize under the hood) and the implementation from the Stack Overflow (pure python).

Implementation Sample size Execution time
pyxirr (Rust) 100 45.89 us
xirr (scipy) 100 790.76 us
pure Python 100 14.37 ms
pyxirr (Rust) 1000 404.03 us
xirr (scipy) 1000 3.47 ms
pure Python 1000 35.97 ms
pyxirr (Rust) 10000 3.58 ms
xirr (scipy) 10000 28.04 ms
pure Python 10000 24.23 s

PyXIRR is ~10-20x faster than other solutions!

Examples

from datetime import date
from pyxirr import xirr

dates = [date(2020, 1, 1), date(2021, 1, 1), date(2022, 1, 1)]
amounts = [-1000, 1000, 1000]

# feed columnar data
xirr(dates, amounts)
# feed iterators
xirr(iter(dates), (x for x in amounts))
# feed an iterable of tuples
xirr(zip(dates, amounts))
# feed a dictionary
xirr(dict(zip(dates, amounts)))

Numpy and Pandas support

import numpy as np
import pandas as pd

# feed numpy array
xirr(np.array([dates, amounts]))
xirr(np.array(dates), np.array(amounts))
# feed DataFrame (columns names doesn't matter; ordering matters)
xirr(pd.DataFrame({"a": dates, "b": amounts}))

API reference

Let's define type annotations:

# `None` if the calculation fails to converge or result is not finite (`inf` or `nan`)
FiniteOrNone = Optional[float]

DateLike = Union[datetime.date, datetime.datetime, numpy.datetime64, pandas.Timestamp]
Rate = float  # rate as decimal, not percentage, normally between [-1, 1]
Guess = Optional[Rate]
Amount = Union[int, float, Decimal]
Payment = Tuple[DateLike, Amount]

DateLikeArray = Iterable[DateLike]
AmountArray = Iterable[Amount]
CashFlowTable = Iterable[Payment]
CashFlowDict = Dict[DateLike, Amount]

Exceptions

  • InvalidPaymentsError. Occurs if either:
    • the amounts and dates arrays (AmountArray, DateLikeArray) are of different lengths
    • the given arrays do not contain at least one negative and at least one positive value

XIRR

# raises: InvalidPaymentsError
def xirr(
    dates: Union[CashFlowTable, CashFlowDict, DateLikeArray],
    amounts: Optional[AmountArray] = None,
    guess: Guess = None,
) -> FiniteOrNone

XNPV

# raises: InvalidPaymentsError
def xnpv(
    rate: Rate,
    dates: Union[CashFlowTable, CashFlowDict, DateLikeArray],
    amounts: Optional[AmountArray] = None,
) -> FiniteOrNone

IRR

Compute the Internal Rate of Return (IRR)

# raises: InvalidPaymentsError
def irr(amounts: AmountArray, guess: Guess = None) -> FiniteOrNone

NPV

Compute the Net Present Value.

# raises: InvalidPaymentsError
def npv(rate: Rate, amounts: AmountArray) -> FiniteOrNone

FV

Compute the future value.

def fv(
    rate: Rate, # Rate of interest per period
    nper: int, # Number of compounding periods
    pmt: Amount, # Payment
    pv: Amount, # Present value
    pmt_at_begining: bool = False  # When payments are due
) -> FiniteOrNone

Roadmap

  • NumPy support
  • XIRR
  • XNPV
  • NPV
  • IRR
  • FV
  • PV
  • MIRR

Development

Running tests with pyo3 is a bit tricky. In short, you need to compile your tests without extension-module feature to avoid linking errors. See the following issues for the details: #341, #771.

If you are using pyenv, make sure you have the shared library installed (check for ${PYENV_ROOT}/versions/<version>/lib/libpython3.so file).

$ PYTHON_CONFIGURE_OPTS="--enable-shared" pyenv install <version>

Install dev-requirements

$ pip install -r dev-requirements.txt

Building

$ maturin develop

Testing

$ LD_LIBRARY_PATH=${PYENV_ROOT}/versions/3.8.6/lib cargo test --no-default-features

Building and distribution

This library uses maturin to build and distribute python wheels.

$ docker run --rm -v $(pwd):/io konstin2/maturin build --release --manylinux 2010 --strip
$ maturin upload target/wheels/pyxirr-${version}*

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pyxirr-0.4.1.tar.gz (163.6 kB view hashes)

Uploaded Source

Built Distributions

pyxirr-0.4.1-cp39-none-win_amd64.whl (119.6 kB view hashes)

Uploaded CPython 3.9 Windows x86-64

pyxirr-0.4.1-cp39-cp39-manylinux1_x86_64.whl (185.2 kB view hashes)

Uploaded CPython 3.9

pyxirr-0.4.1-cp39-cp39-macosx_10_9_universal2.whl (334.6 kB view hashes)

Uploaded CPython 3.9 macOS 10.9+ universal2 (ARM64, x86-64)

pyxirr-0.4.1-cp38-none-win_amd64.whl (119.6 kB view hashes)

Uploaded CPython 3.8 Windows x86-64

pyxirr-0.4.1-cp38-cp38-manylinux1_x86_64.whl (185.3 kB view hashes)

Uploaded CPython 3.8

pyxirr-0.4.1-cp38-cp38-macosx_10_9_universal2.whl (334.7 kB view hashes)

Uploaded CPython 3.8 macOS 10.9+ universal2 (ARM64, x86-64)

pyxirr-0.4.1-cp37-none-win_amd64.whl (119.6 kB view hashes)

Uploaded CPython 3.7 Windows x86-64

pyxirr-0.4.1-cp37-cp37m-manylinux1_x86_64.whl (185.3 kB view hashes)

Uploaded CPython 3.7m

pyxirr-0.4.1-cp37-cp37m-macosx_10_9_universal2.whl (334.7 kB view hashes)

Uploaded CPython 3.7m macOS 10.9+ universal2 (ARM64, x86-64)

pyxirr-0.4.1-cp36-none-win_amd64.whl (119.6 kB view hashes)

Uploaded CPython 3.6 Windows x86-64

pyxirr-0.4.1-cp36-cp36m-manylinux1_x86_64.whl (185.3 kB view hashes)

Uploaded CPython 3.6m

pyxirr-0.4.1-cp36-cp36m-macosx_10_9_universal2.whl (334.7 kB view hashes)

Uploaded CPython 3.6m macOS 10.9+ universal2 (ARM64, x86-64)

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page