quantflow 0.2.9__tar.gz → 0.3.1__tar.gz

{quantflow-0.2.9 → quantflow-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: quantflow
-Version: 0.2.9
+Version: 0.3.1
 Summary: quantitative analysis
 License: BSD-3-Clause
 Author: Luca
@@ -15,8 +15,10 @@ Provides-Extra: cli
 Provides-Extra: data
 Requires-Dist: aio-fluid[http] (>=1.2.1,<2.0.0) ; extra == "data"
 Requires-Dist: asciichartpy (>=1.5.25,<2.0.0) ; extra == "cli"
-Requires-Dist: ccy (==1.6.0)
+Requires-Dist: async-cache (>=1.1.1,<2.0.0) ; extra == "cli"
+Requires-Dist: ccy (>=1.7.1,<2.0.0)
 Requires-Dist: click (>=8.1.7,<9.0.0) ; extra == "cli"
+Requires-Dist: holidays (>=0.63,<0.64) ; extra == "cli"
 Requires-Dist: polars[pandas,pyarrow] (>=1.11.0,<2.0.0)
 Requires-Dist: prompt-toolkit (>=3.0.43,<4.0.0) ; extra == "cli"
 Requires-Dist: pydantic (>=2.0.2,<3.0.0)
@@ -51,9 +53,13 @@ pip install quantflow
 
 ## Modules
 
+* [quantflow.cli](https://github.com/quantmind/quantflow/tree/main/quantflow/cli) command line client (requires `quantflow[cli,data]`)
 * [quantflow.data](https://github.com/quantmind/quantflow/tree/main/quantflow/data) data APIs (requires `quantflow[data]`)
 * [quantflow.options](https://github.com/quantmind/quantflow/tree/main/quantflow/options) option pricing and calibration
 * [quantflow.sp](https://github.com/quantmind/quantflow/tree/main/quantflow/sp) stochastic process primitives
+* [quantflow.ta](https://github.com/quantmind/quantflow/tree/main/quantflow/ta) timeseries analysis tools
+* [quantflow.utils](https://github.com/quantmind/quantflow/tree/main/quantflow/utils) utilities and helpers
+
 
 
 ## Command line tools

{quantflow-0.2.9 → quantflow-0.3.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "quantflow"
-version = "0.2.9"
+version = "0.3.1"
 description = "quantitative analysis"
 authors = ["Luca <luca@quantmind.com>"]
 license = "BSD-3-Clause"
@@ -15,7 +15,7 @@ Documentation = "https://quantmind.github.io/quantflow/"
 python = ">=3.11"
 scipy = "^1.14.1"
 pydantic = "^2.0.2"
-ccy = {version="1.6.0"}
+ccy = { version = "^1.7.1" }
 python-dotenv = "^1.0.1"
 polars = {version = "^1.11.0", extras=["pandas", "pyarrow"]}
 asciichartpy = { version = "^1.5.25", optional = true }
@@ -23,31 +23,44 @@ prompt-toolkit = { version = "^3.0.43", optional = true }
 aio-fluid = {version = "^1.2.1", extras=["http"], optional = true}
 rich = {version = "^13.9.4", optional = true}
 click = {version = "^8.1.7", optional = true}
+holidays = {version = "^0.63", optional = true}
+async-cache = {version = "^1.1.1", optional = true}
 
 [tool.poetry.group.dev.dependencies]
 black = "^24.1.1"
 pytest-cov = "^6.0.0"
-mypy = "^1.13.0"
+mypy = "^1.14.1"
 ghp-import = "^2.0.2"
 ruff = "^0.8.1"
 pytest-asyncio = "^0.25.0"
+isort = "^5.13.2"
 
 
 [tool.poetry.extras]
 data = ["aio-fluid"]
-cli = ["asciichartpy", "prompt-toolkit", "rich", "click"]
+cli = [
+    "asciichartpy",
+    "async-cache",
+    "prompt-toolkit",
+    "rich",
+    "click",
+    "holidays"
+]
 
 [tool.poetry.group.book]
 optional = true
 
 [tool.poetry.group.book.dependencies]
 jupyter-book = "^1.0.0"
-nbconvert = "^7.16.3"
 jupytext = "^1.13.8"
 plotly = "^5.20.0"
 jupyterlab = "^4.0.2"
 sympy = "^1.12"
 ipywidgets = "^8.0.7"
+sphinx-autodoc-typehints = "2.3.0"
+sphinx-autosummary-accessors = "^2023.4.0"
+sphinx-copybutton = "^0.5.2"
+autodocsumm = "^0.2.14"
 
 [tool.poetry.scripts]
 qf = "quantflow.cli.script:main"
@@ -84,6 +97,7 @@ warn_no_return = true
 [[tool.mypy.overrides]]
 module = [
     "asciichartpy.*",
+    "cache.*",
     "quantflow_tests.*",
     "IPython.*",
     "pandas.*",

{quantflow-0.2.9 → quantflow-0.3.1}/quantflow/__init__.py

@@ -1,3 +1,3 @@
 """Quantitative analysis and pricing"""
 
-__version__ = "0.2.9"
+__version__ = "0.3.1"

quantflow-0.3.1/quantflow/cli/app.py

@@ -0,0 +1,100 @@
+import os
+from dataclasses import dataclass, field
+from functools import partial
+from typing import Any
+
+import click
+from fluid.utils.http_client import HttpResponseError
+from prompt_toolkit import PromptSession
+from prompt_toolkit.completion import NestedCompleter
+from prompt_toolkit.formatted_text import HTML
+from prompt_toolkit.history import FileHistory
+from rich.console import Console
+from rich.text import Text
+
+from quantflow.data.vault import Vault
+
+from . import settings
+from .commands import quantflow
+from .commands.base import QuantGroup
+
+
+@dataclass
+class QfApp:
+    console: Console = field(default_factory=Console)
+    vault: Vault = field(default_factory=partial(Vault, settings.VAULT_FILE_PATH))
+    sections: list[QuantGroup] = field(default_factory=lambda: [quantflow])
+
+    def __call__(self) -> None:
+        os.makedirs(settings.SETTINGS_DIRECTORY, exist_ok=True)
+        history = FileHistory(str(settings.HIST_FILE_PATH))
+        session: PromptSession = PromptSession(history=history)
+
+        self.print("Welcome to QuantFlow!", style="bold green")
+        self.handle_command("help")
+
+        try:
+            while True:
+                try:
+                    text = session.prompt(
+                        self.prompt_message(),
+                        completer=self.prompt_completer(),
+                        complete_while_typing=True,
+                        bottom_toolbar=self.bottom_toolbar,
+                    )
+                except KeyboardInterrupt:
+                    break
+                else:
+                    self.handle_command(text)
+        except click.Abort:
+            self.console.print(Text("Bye!", style="bold magenta"))
+
+    def prompt_message(self) -> str:
+        name = ":".join([str(section.name) for section in self.sections])
+        return f"{name} > "
+
+    def prompt_completer(self) -> NestedCompleter:
+        return NestedCompleter.from_nested_dict(
+            {command: None for command in self.sections[-1].commands}
+        )
+
+    def set_section(self, section: QuantGroup) -> None:
+        self.sections.append(section)
+
+    def back(self) -> None:
+        self.sections.pop()
+
+    def print(self, text_alike: Any, style: str = "") -> None:
+        if isinstance(text_alike, str):
+            style = style or "cyan"
+            text_alike = Text(f"\n{text_alike}\n", style="cyan")
+        self.console.print(text_alike)
+
+    def error(self, err: str | Exception) -> None:
+        self.console.print(Text(f"\n{err}\n", style="bold red"))
+
+    def handle_command(self, text: str) -> None:
+        if not text:
+            return
+        command = self.sections[-1]
+        try:
+            command.main(text.split(), standalone_mode=False, obj=self)
+        except (
+            click.exceptions.MissingParameter,
+            click.exceptions.NoSuchOption,
+            click.exceptions.UsageError,
+            HttpResponseError,
+        ) as e:
+            self.error(e)
+
+    def bottom_toolbar(self) -> HTML:
+        sections = "/".join([str(section.name) for section in self.sections])
+        back = (
+            (' <b><style bg="ansired">back</style></b> ' "to exit the current section,")
+            if len(self.sections) > 1
+            else ""
+        )
+        return HTML(
+            f"Your are in <strong>{sections}</strong>, type{back} "
+            '<b><style bg="ansired">exit</style></b> to exit'
+        )

quantflow-0.3.1/quantflow/cli/commands/__init__.py

@@ -0,0 +1,18 @@
+from .base import QuantContext, quant_group
+from .crypto import crypto
+from .fred import fred
+from .stocks import stocks
+from .vault import vault
+
+
+@quant_group()
+def quantflow() -> None:
+    ctx = QuantContext.current()
+    if ctx.invoked_subcommand is None:
+        ctx.qf.print(ctx.get_help())
+
+
+quantflow.add_command(vault)
+quantflow.add_command(crypto)
+quantflow.add_command(stocks)
+quantflow.add_command(fred)

quantflow-0.3.1/quantflow/cli/commands/base.py

@@ -0,0 +1,134 @@
+from __future__ import annotations
+
+import enum
+from typing import TYPE_CHECKING, Any, Self, cast
+
+import click
+
+from quantflow.data.fmp import FMP
+from quantflow.data.fred import Fred
+
+if TYPE_CHECKING:
+    from quantflow.cli.app import QfApp
+
+
+FREQUENCIES = tuple(FMP().historical_frequencies())
+
+
+class HistoricalPeriod(enum.StrEnum):
+    day = "1d"
+    week = "1w"
+    month = "1m"
+    three_months = "3m"
+    six_months = "6m"
+    year = "1y"
+
+
+class QuantContext(click.Context):
+
+    @classmethod
+    def current(cls) -> Self:
+        return cast(Self, click.get_current_context())
+
+    @property
+    def qf(self) -> QfApp:
+        return self.obj  # type: ignore
+
+    def set_as_section(self) -> None:
+        group = cast(QuantGroup, self.command)
+        group.add_command(back)
+        self.qf.set_section(group)
+        self.qf.print(self.get_help())
+
+    def fmp(self) -> FMP:
+        if key := self.qf.vault.get("fmp"):
+            return FMP(key=key)
+        else:
+            raise click.UsageError("No FMP API key found")
+
+    def fred(self) -> Fred:
+        if key := self.qf.vault.get("fred"):
+            return Fred(key=key)
+        else:
+            raise click.UsageError("No FRED API key found")
+
+
+class QuantCommand(click.Command):
+    context_class = QuantContext
+
+
+class QuantGroup(click.Group):
+    context_class = QuantContext
+    command_class = QuantCommand
+
+
+@click.command(cls=QuantCommand)
+def exit() -> None:
+    """Exit the program"""
+    raise click.Abort()
+
+
+@click.command(cls=QuantCommand)
+def help() -> None:
+    """display the commands"""
+    if ctx := QuantContext.current().parent:
+        cast(QuantContext, ctx).qf.print(ctx.get_help())
+
+
+@click.command(cls=QuantCommand)
+def back() -> None:
+    """Exit the current section"""
+    ctx = QuantContext.current()
+    ctx.qf.back()
+    ctx.qf.handle_command("help")
+
+
+def quant_group() -> Any:
+    return click.group(
+        cls=QuantGroup,
+        commands=[exit, help],
+        invoke_without_command=True,
+        add_help_option=False,
+    )
+
+
+class options:
+    length = click.option(
+        "-l",
+        "--length",
+        type=int,
+        default=100,
+        show_default=True,
+        help="Number of data points",
+    )
+    height = click.option(
+        "-h",
+        "--height",
+        type=int,
+        default=20,
+        show_default=True,
+        help="Chart height",
+    )
+    chart = click.option("-c", "--chart", is_flag=True, help="Display chart")
+    period = click.option(
+        "-p",
+        "--period",
+        type=click.Choice(tuple(p.value for p in HistoricalPeriod)),
+        default="1d",
+        show_default=True,
+        help="Historical period",
+    )
+    index = click.option(
+        "-i",
+        "--index",
+        type=int,
+        default=-1,
+        help="maturity index",
+    )
+    frequency = click.option(
+        "-f",
+        "--frequency",
+        type=click.Choice(FREQUENCIES),
+        default="",
+        help="Frequency of data - if not provided it is daily",
+    )

quantflow-0.3.1/quantflow/cli/commands/crypto.py

@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+import asyncio
+
+import click
+import pandas as pd
+from asciichartpy import plot
+from cache import AsyncTTL
+from ccy.cli.console import df_to_rich
+
+from quantflow.data.deribit import Deribit
+from quantflow.options.surface import VolSurface
+from quantflow.utils.numbers import round_to_step
+
+from .base import QuantContext, options, quant_group
+from .stocks import get_prices
+
+
+@quant_group()
+def crypto() -> None:
+    """Crypto currencies commands"""
+    ctx = QuantContext.current()
+    if ctx.invoked_subcommand is None:
+        ctx.set_as_section()
+
+
+@crypto.command()
+@click.argument("currency")
+@options.length
+@options.height
+@options.chart
+def volatility(currency: str, length: int, height: int, chart: bool) -> None:
+    """Provides information about historical volatility for given cryptocurrency"""
+    ctx = QuantContext.current()
+    df = asyncio.run(get_volatility(ctx, currency))
+    df["volatility"] = df["volatility"].map(lambda p: round_to_step(p, "0.01"))
+    if chart:
+        data = df["volatility"].tolist()[:length]
+        ctx.qf.print(plot(data, {"height": height}))
+    else:
+        ctx.qf.print(df_to_rich(df))
+
+
+@crypto.command()
+@click.argument("currency")
+def term_structure(currency: str) -> None:
+    """Provides information about the term structure for given cryptocurrency"""
+    ctx = QuantContext.current()
+    vs = asyncio.run(get_vol_surface(currency))
+    ts = vs.term_structure().round({"ttm": 4})
+    ts["open_interest"] = ts["open_interest"].map("{:,d}".format)
+    ts["volume"] = ts["volume"].map("{:,d}".format)
+    ctx.qf.print(df_to_rich(ts))
+
+
+@crypto.command()
+@click.argument("currency")
+@options.index
+@options.height
+@options.chart
+def implied_vol(currency: str, index: int, height: int, chart: bool) -> None:
+    """Display the Volatility Surface for given cryptocurrency
+    at a given maturity index
+    """
+    ctx = QuantContext.current()
+    vs = asyncio.run(get_vol_surface(currency))
+    index_or_none = None if index < 0 else index
+    vs.bs(index=index_or_none)
+    df = vs.options_df(index=index_or_none)
+    if chart:
+        data = (df["implied_vol"] * 100).tolist()
+        ctx.qf.print(plot(data, {"height": height}))
+    else:
+        df[["ttm", "moneyness", "moneyness_ttm"]] = df[
+            ["ttm", "moneyness", "moneyness_ttm"]
+        ].map("{:.4f}".format)
+        df["implied_vol"] = df["implied_vol"].map("{:.2%}".format)
+        df["price"] = df["price"].map(lambda p: round_to_step(p, vs.tick_size_options))
+        df["forward_price"] = df["forward_price"].map(
+            lambda p: round_to_step(p, vs.tick_size_forwards)
+        )
+        ctx.qf.print(df_to_rich(df))
+
+
+@crypto.command()
+@click.argument("symbol")
+@options.height
+@options.length
+@options.chart
+@options.frequency
+def prices(symbol: str, height: int, length: int, chart: bool, frequency: str) -> None:
+    """Fetch OHLC prices for given cryptocurrency"""
+    ctx = QuantContext.current()
+    df = asyncio.run(get_prices(ctx, symbol, frequency))
+    if df.empty:
+        raise click.UsageError(
+            f"No data for {symbol} - are you sure the symbol exists?"
+        )
+    if chart:
+        data = list(reversed(df["close"].tolist()[:length]))
+        ctx.qf.print(plot(data, {"height": height}))
+    else:
+        ctx.qf.print(
+            df_to_rich(
+                df[["date", "open", "high", "low", "close", "volume"]].sort_values(
+                    "date"
+                )
+            )
+        )
+
+
+async def get_volatility(ctx: QuantContext, currency: str) -> pd.DataFrame:
+    async with Deribit() as client:
+        return await client.get_volatility(params=dict(currency=currency))
+
+
+@AsyncTTL(time_to_live=10)
+async def get_vol_surface(currency: str) -> VolSurface:
+    async with Deribit() as client:
+        loader = await client.volatility_surface_loader(currency)
+        return loader.surface()

quantflow-0.3.1/quantflow/cli/commands/fred.py

@@ -0,0 +1,118 @@
+from __future__ import annotations
+
+import asyncio
+
+import click
+import pandas as pd
+from asciichartpy import plot
+from ccy.cli.console import df_to_rich
+from fluid.utils.data import compact_dict
+from fluid.utils.http_client import HttpResponseError
+
+from quantflow.data.fred import Fred
+
+from .base import QuantContext, options, quant_group
+
+FREQUENCIES = tuple(Fred.freq)
+
+
+@quant_group()
+def fred() -> None:
+    """Federal Reserve of St. Louis data commands"""
+    ctx = QuantContext.current()
+    if ctx.invoked_subcommand is None:
+        ctx.set_as_section()
+
+
+@fred.command()
+@click.argument("category-id", required=False)
+def subcategories(category_id: str | None = None) -> None:
+    """List subcategories for a Fred category"""
+    ctx = QuantContext.current()
+    try:
+        data = asyncio.run(get_subcategories(ctx, category_id))
+    except HttpResponseError as e:
+        ctx.qf.error(e)
+    else:
+        df = pd.DataFrame(data["categories"], columns=["id", "name"])
+        ctx.qf.print(df_to_rich(df))
+
+
+@fred.command()
+@click.argument("category-id")
+@click.option("-j", "--json", is_flag=True, help="Output as JSON")
+def series(category_id: str, json: bool = False) -> None:
+    """List series for a Fred category"""
+    ctx = QuantContext.current()
+    try:
+        data = asyncio.run(get_series(ctx, category_id))
+    except HttpResponseError as e:
+        ctx.qf.error(e)
+    else:
+        if json:
+            ctx.qf.print(data)
+        else:
+            df = pd.DataFrame(
+                data["seriess"],
+                columns=[
+                    "id",
+                    "popularity",
+                    "title",
+                    "frequency",
+                    "observation_start",
+                    "observation_end",
+                ],
+            ).sort_values("popularity", ascending=False)
+            ctx.qf.print(df_to_rich(df))
+
+
+@fred.command()
+@click.argument("series-id")
+@options.length
+@options.height
+@options.chart
+@click.option(
+    "-f",
+    "--frequency",
+    type=click.Choice(FREQUENCIES),
+    default="d",
+    show_default=True,
+    help="Frequency of data",
+)
+def data(series_id: str, length: int, height: int, chart: bool, frequency: str) -> None:
+    """Display a series data"""
+    ctx = QuantContext.current()
+    try:
+        df = asyncio.run(get_serie_data(ctx, series_id, length, frequency))
+    except HttpResponseError as e:
+        ctx.qf.error(e)
+    else:
+        if chart:
+            data = list(reversed(df["value"].tolist()[:length]))
+            ctx.qf.print(plot(data, {"height": height}))
+        else:
+            ctx.qf.print(df_to_rich(df))
+
+
+async def get_subcategories(ctx: QuantContext, category_id: str | None) -> dict:
+    async with ctx.fred() as cli:
+        return await cli.subcategories(params=compact_dict(category_id=category_id))
+
+
+async def get_series(ctx: QuantContext, category_id: str) -> dict:
+    async with ctx.fred() as cli:
+        return await cli.series(params=compact_dict(category_id=category_id))
+
+
+async def get_serie_data(
+    ctx: QuantContext, series_id: str, length: int, frequency: str
+) -> dict:
+    async with ctx.fred() as cli:
+        return await cli.serie_data(
+            params=dict(
+                series_id=series_id,
+                limit=length,
+                frequency=frequency,
+                sort_order="desc",
+            )
+        )