pfund-plot 0.0.1.dev1__py3-none-any.whl → 0.0.1.dev3__py3-none-any.whl

pfund_plot/__init__.py

@@ -1 +1,35 @@
-import pfund_plot
+from importlib.metadata import version
+
+import hvplot
+import panel as pn
+
+from pfund_plot.config_handler import get_config, configure
+from pfund_plot.plots.dataframe import (
+    dataframe_plot as dataframe,
+    dataframe_plot as df,
+)
+from pfund_plot.plots.candlestick import (
+    candlestick_plot as candlestick,
+    candlestick_plot as ohlc,
+    candlestick_plot as kline,
+)
+
+
+hvplot.extension('bokeh', 'plotly')
+pn.extension('tabulator', 'perspective')
+# used to throttle updates in panel plots
+# NOTE: without it, e.g. dragging a slider will cause the plot to update rapidly and lead to an error
+pn.config.throttled = True
+
+
+__version__ = version("pfund_plot")
+__all__ = (
+    "__version__",
+    "get_config",
+    "configure",
+    "candlestick",
+    "ohlc",
+    "kline",
+    "dataframe",
+    "df",
+)

pfund_plot/cli/__init__.py

@@ -0,0 +1,4 @@
+from pfund_plot.cli.main import pfund_plot_group
+
+
+__all__ = ["pfund_plot_group"]

pfund_plot/cli/commands/config.py

@@ -0,0 +1,81 @@
+import click
+
+from pfeed.const.enums import DataTool
+from pfund_plot.const.paths import PROJ_NAME
+
+
+@click.group()
+def config():
+    """Manage configuration settings."""
+    pass
+
+
+@config.command()
+@click.pass_context
+def list(ctx):
+    """List all available options."""
+    from pprint import pformat
+    from dataclasses import asdict
+    config_dict = asdict(ctx.obj['config'])
+    content = click.style(pformat(config_dict), fg='green')
+    click.echo(f"{PROJ_NAME} config:\n{content}")
+
+
+@config.command()
+@click.pass_context
+def reset(ctx):
+    """Reset the configuration to defaults."""
+    ctx.obj['config'].reset()
+    click.echo(f"{PROJ_NAME} config reset successfully.")
+
+
+@config.command()
+@click.option('--data-tool', '--dt', type=click.Choice(DataTool, case_sensitive=False), help='Set the data tool')
+@click.option('--max-points', '--mp', type=int, help='Set the maximum number of points to display in the plot')
+@click.option('--data-path', '--dp', type=click.Path(resolve_path=True), help='Set the data path')
+@click.option('--cache-path', '--cp', type=click.Path(resolve_path=True), help='Set the cache path')
+def set(**kwargs):
+    """Configures pfund_plot settings."""
+    from pfund_plot.config_handler import configure
+    provided_options = {k: v for k, v in kwargs.items() if v is not None}
+    if not provided_options:
+        raise click.UsageError(f"No options provided. Please run '{PROJ_NAME} config set --help' to see all available options.")
+    else:
+        configure(write=True, **kwargs)
+        click.echo(f"{PROJ_NAME} config updated successfully.")
+
+
+@config.command()
+@click.option('--config-file', '-c', is_flag=True, help=f'Open the {PROJ_NAME}_config.yml file')
+@click.option('--default-editor', '-E', is_flag=True, help='Use default editor')
+def open(config_file, default_editor):
+    """Opens config files, e.g. pfund_plot_config.yml."""
+    from pfund_plot.const.paths import CONFIG_FILE_PATH
+    
+    if sum([config_file]) > 1:
+        click.echo('Please specify only one file to open')
+        return
+    else:
+        if config_file:
+            file_path = CONFIG_FILE_PATH
+        else:
+            click.echo(f'Please specify a file to open, run "{PROJ_NAME} config open --help" for more info')
+            return
+    
+    if default_editor:
+        click.edit(filename=file_path)
+    else:
+        open_with_vscode(file_path)
+        
+        
+def open_with_vscode(file_path):
+    import subprocess
+    try:
+        subprocess.run(["code", str(file_path)], check=True)
+        click.echo(f"Opened {file_path} with VS Code")
+    except subprocess.CalledProcessError:
+        click.echo("Failed to open with VS Code. Falling back to default editor.")
+        click.edit(filename=file_path)
+    except FileNotFoundError:
+        click.echo("VS Code command 'code' not found. Falling back to default editor.")
+        click.edit(filename=file_path)

pfund_plot/cli/commands/plot.py

@@ -0,0 +1,7 @@
+import click
+
+
+@click.command()
+def plot():
+    # TODO: add plot function
+    print('plotting!!!')

pfund_plot/cli/main.py

@@ -0,0 +1,20 @@
+import click
+from trogon import tui
+
+from pfund_plot.config_handler import get_config
+from pfund_plot.cli.commands.plot import plot
+from pfund_plot.cli.commands.config import config
+
+
+@tui(command='tui', help="Open terminal UI")
+@click.group(context_settings={"help_option_names": ["-h", "--help"]})
+@click.pass_context
+@click.version_option()
+def pfund_plot_group(ctx):
+    """PFundPlot's CLI"""
+    ctx.ensure_object(dict)
+    ctx.obj['config'] = get_config(verbose=False)
+
+
+pfund_plot_group.add_command(plot)
+pfund_plot_group.add_command(config)

pfund_plot/composites/composite.py

@@ -0,0 +1,13 @@
+# TEMP
+# composites are plots combined together on the same canvas
+# it can be used to perform comparison analysis, create a graph that has the price line, equity curve etc. 
+
+# use plotly for composite plots
+class CompositePlot:
+    def __init__(self, plots):
+        self.plots = plots
+
+    def render(self):
+        # Implement logic to combine plots
+        # This is non-trivial and may require standardizing on a single backend
+        pass

pfund_plot/config_handler.py

@@ -0,0 +1,136 @@
+import os
+import shutil
+from dataclasses import dataclass, asdict
+
+import yaml
+
+from pfund_plot.const.paths import (
+    PROJ_NAME, 
+    DATA_PATH,
+    CACHE_PATH,
+    CONFIG_PATH, 
+    CONFIG_FILE_PATH
+)
+
+
+__all__ = [
+    'get_config',
+    'configure',
+]
+
+
+@dataclass
+class ConfigHandler:
+    data_path: str = str(DATA_PATH)
+    cache_path: str = str(CACHE_PATH)
+    
+    _instance = None
+    _verbose = False
+
+    @classmethod
+    def get_instance(cls):
+        if cls._instance is None:
+            cls._instance = cls.load()
+        return cls._instance
+
+    @classmethod
+    def set_verbose(cls, verbose: bool):
+        cls._verbose = verbose
+    
+    @classmethod
+    def load(cls):
+        '''Loads user's config file and returns a ConfigHandler object'''
+        CONFIG_FILE_PATH.parent.mkdir(parents=True, exist_ok=True)
+        # Create default config from dataclass fields
+        default_config = {
+            field.name: field.default 
+            for field in cls.__dataclass_fields__.values()
+            if not field.name.startswith('_')  # Skip private fields
+        }
+        needs_update = False
+        if CONFIG_FILE_PATH.is_file():
+            with open(CONFIG_FILE_PATH, 'r') as f:
+                saved_config = yaml.safe_load(f) or {}
+                if cls._verbose:
+                    print(f"{PROJ_NAME} config loaded from {CONFIG_FILE_PATH}.")
+                # Check for new or removed fields
+                new_fields = set(default_config.keys()) - set(saved_config.keys())
+                removed_fields = set(saved_config.keys()) - set(default_config.keys())
+                needs_update = bool(new_fields or removed_fields)
+                
+                if cls._verbose and needs_update:
+                    if new_fields:
+                        print(f"New config fields detected: {new_fields}")
+                    if removed_fields:
+                        print(f"Removed config fields detected: {removed_fields}")
+                        
+                # Filter out removed fields and merge with defaults
+                saved_config = {k: v for k, v in saved_config.items() if k in default_config}
+                config = {**default_config, **saved_config}
+        else:
+            config = default_config
+            needs_update = True
+        config_handler = cls(**config)
+        if needs_update:
+            config_handler.dump()
+        return config_handler
+    
+    @classmethod
+    def reset(cls):
+        '''Resets the config by deleting the user config directory and reloading the config'''
+        shutil.rmtree(CONFIG_PATH)
+        if cls._verbose:
+            print(f"{PROJ_NAME} config successfully reset.")
+        return cls.load()
+    
+    def dump(self):
+        with open(CONFIG_FILE_PATH, 'w') as f:
+            yaml.dump(asdict(self), f, default_flow_style=False)
+            if self._verbose:
+                print(f"{PROJ_NAME} config saved to {CONFIG_FILE_PATH}.")
+    
+    def __post_init__(self):
+        self._initialize_configs()
+    
+    def _initialize_configs(self):
+        for path in [self.data_path, self.cache_path]:
+            if not os.path.exists(path):
+                os.makedirs(path)
+                if self._verbose:
+                    print(f'{PROJ_NAME} created {path}')
+                
+
+def configure(
+    data_path: str | None = None,
+    cache_path: str | None = None,
+    verbose: bool = False,
+    write: bool = False,
+):
+    '''Configures the global config object.
+    It will override the existing config values from the existing config file or the default values.
+    Args:
+        write: If True, the config will be saved to the config file.
+    '''
+    NON_CONFIG_KEYS = ['verbose', 'write']
+    config_updates = locals()
+    for k in NON_CONFIG_KEYS:
+        config_updates.pop(k)
+    config_updates.pop('NON_CONFIG_KEYS')
+
+    config = get_config(verbose=verbose)
+
+    # Apply updates for non-None values
+    for k, v in config_updates.items():
+        if v is not None:
+            setattr(config, k, v)
+            
+    if write:
+        config.dump()
+        
+    config._initialize_configs()
+    return config
+
+
+def get_config(verbose: bool = False) -> ConfigHandler:
+    ConfigHandler.set_verbose(verbose)
+    return ConfigHandler.get_instance()

pfund_plot/const/enums/__init__.py

@@ -0,0 +1,6 @@
+from pfund_plot.const.enums.notebook_type import NotebookType
+from pfund_plot.const.enums.dashboard_type import DashboardType
+from pfund_plot.const.enums.plotting_backend import PlottingBackend
+from pfund_plot.const.enums.display_mode import DisplayMode
+from pfund_plot.const.enums.data_type import DataType
+from pfund_plot.const.enums.dataframe_backend import DataFrameBackend

pfund_plot/const/enums/dashboard_type.py

@@ -0,0 +1,8 @@
+from enum import StrEnum
+
+
+class DashboardType(StrEnum):
+    DASH = 'DASH'
+    STREAMLIT = 'STREAMLIT'
+    GRADIO = 'GRADIO'
+    TAIPY = 'TAIPY'

pfund_plot/const/enums/data_type.py

@@ -0,0 +1,6 @@
+from enum import StrEnum
+
+
+class DataType(StrEnum):
+    dataframe = 'dataframe'
+    datafeed = 'datafeed'  # pfeed's feed object

pfund_plot/const/enums/dataframe_backend.py

@@ -0,0 +1,6 @@
+from enum import StrEnum
+
+
+class DataFrameBackend(StrEnum):
+    tabulator = 'tabulator'
+    perspective = 'perspective'

pfund_plot/const/enums/display_mode.py

@@ -0,0 +1,7 @@
+from enum import StrEnum
+
+
+class DisplayMode(StrEnum):
+    notebook = "notebook"
+    browser = "browser"
+    desktop = "desktop"

pfund_plot/const/enums/notebook_type.py

@@ -0,0 +1,7 @@
+from enum import StrEnum
+
+
+class NotebookType(StrEnum):
+    jupyter = 'jupyter'
+    marimo = 'marimo'
+    vscode = 'vscode'

pfund_plot/const/enums/plotting_backend.py

@@ -0,0 +1,6 @@
+from enum import StrEnum
+
+
+class PlottingBackend(StrEnum):
+    bokeh = 'bokeh'
+    plotly = 'plotly'

pfund_plot/const/paths.py

@@ -0,0 +1,15 @@
+from pathlib import Path
+from platformdirs import user_data_dir, user_config_dir, user_cache_dir
+
+
+# project paths
+PROJ_NAME = Path(__file__).resolve().parents[1].name
+MAIN_PATH = Path(__file__).resolve().parents[2]
+PROJ_PATH = MAIN_PATH / PROJ_NAME
+
+
+# user paths
+DATA_PATH = Path(user_data_dir()) / PROJ_NAME
+CACHE_PATH = Path(user_cache_dir()) / PROJ_NAME
+CONFIG_PATH = Path(user_config_dir()) / PROJ_NAME / 'config'
+CONFIG_FILE_PATH = CONFIG_PATH / f'{PROJ_NAME}_config.yml'

pfund_plot/main.py

@@ -0,0 +1,18 @@
+import atexit
+
+from pfund_plot.cli import pfund_plot_group
+
+
+def exit_cli():
+    """Application Exitpoint."""
+    print("Cleanup actions here...")
+
+
+def run_cli() -> None:
+    """Application Entrypoint."""
+    # atexit.register(exit_cli)
+    pfund_plot_group(obj={})
+
+
+if __name__ == '__main__':
+    run_cli()

pfund_plot/plots/candlestick.py

@@ -0,0 +1,234 @@
+from __future__ import annotations
+from typing import TYPE_CHECKING
+if TYPE_CHECKING:
+    from narwhals.typing import IntoFrameT, FrameT
+    from pfeed.types.core import tDataFrame
+    from pfeed.feeds.base_feed import BaseFeed
+    from pfund_plot.types.literals import tDISPLAY_MODE
+    from pfund_plot.types.core import tOutput
+    from holoviews.core.overlay import Overlay
+    from panel.layout import Panel
+    
+import panel as pn
+import narwhals as nw
+from bokeh.models import HoverTool, CrosshairTool
+
+from pfund_plot.const.enums import DisplayMode, PlottingBackend, DataType
+from pfund_plot.utils.validate import validate_data_type
+from pfund_plot.renderer import render
+
+
+__all__ = ['candlestick_plot']
+
+
+REQUIRED_COLS = ['ts', 'open', 'high', 'low', 'close', 'volume']
+DEFAULT_STYLE = {
+    'title': 'Candlestick Chart',
+    'ylabel': 'price',
+    'xlabel': 'time',
+}
+# needs a default value for "responsive"=True to work properly in notebook environment
+DEFAULT_HEIGHT_FOR_NOTEBOOK = 280
+
+
+def _validate_df(df: IntoFrameT) -> FrameT:
+    import datetime
+    df: FrameT = nw.from_native(df)
+    if isinstance(df, nw.LazyFrame):
+        df = df.collect()
+    # convert all columns to lowercase
+    df = df.rename({col: col.lower() for col in df.columns})
+    # rename 'date' to 'ts'
+    if 'date' in df.columns and 'ts' not in df.columns:
+        df = df.rename({'date': 'ts'})
+    missing_cols = [col for col in REQUIRED_COLS if col not in df.columns]
+    if missing_cols:
+        raise ValueError(f"Missing required columns: {missing_cols}")
+    ts_value = df.select('ts').row(0)[0]
+    # convert ts to datetime if not already
+    if not isinstance(ts_value, datetime.datetime):
+        # REVIEW: this might mess up the datetime format
+        df = df.with_columns(
+            nw.col('ts').str.to_datetime(format=None),
+        )
+    return df
+
+
+def _get_style(df: FrameT, display_mode: DisplayMode, height: int | None, width: int | None) -> dict:
+    style = DEFAULT_STYLE.copy()
+    if height is not None:
+        style['height'] = height
+    else:
+        if display_mode == DisplayMode.notebook:
+            style['height'] = DEFAULT_HEIGHT_FOR_NOTEBOOK
+    if width is not None:
+        style['width'] = width
+    product_or_symbol = None
+    if 'symbol' in df.columns:
+        product_or_symbol = df.select('symbol').row(0)[0]
+    elif 'product' in df.columns:
+        product_or_symbol = df.select('product').row(0)[0]
+    if product_or_symbol:
+        style['title'] = f"{product_or_symbol} {style['title']}"
+    return style
+
+
+def _create_hover_tool(df: FrameT) -> HoverTool:
+    from pfund_plot.utils.utils import is_daily_data
+    ts_format = '%Y-%m-%d' if is_daily_data(df) else '%Y-%m-%d %H:%M:%S'
+    return HoverTool(
+        tooltips=[
+            ('ts', f'@ts{{{ts_format}}}'),
+            ('open', '@open'),
+            ('high', '@high'),
+            ('low', '@low'),
+            ('close', '@close'),
+            ('volume', '@volume'),
+        ],
+        formatters={'@ts': 'datetime'},
+        mode='vline',
+    )
+
+
+def candlestick_plot(
+    data: tDataFrame | BaseFeed, 
+    streaming: bool = False, 
+    display_mode: tDISPLAY_MODE = "notebook", 
+    num_data: int = 100,
+    raw_figure: bool = False,
+    slider_step: int = 100,
+    show_volume: bool = True,
+    streaming_freq: int = 1000,  # in milliseconds
+    # styling
+    up_color: str = 'green',
+    down_color: str = 'red',
+    bg_color: str = 'white',
+    height: int | None = None,
+    width: int | None = None,
+    grid: bool = True,
+) -> tOutput:
+    '''
+    Args:
+        data: the data to plot, either a dataframe or pfeed's feed object
+        streaming: if True, the plot will be updated in real-time as new data is received
+        display_mode: where to display the plot, either "notebook", "browser", or "desktop"
+        streaming_freq: the update frequency of the streaming data in milliseconds
+        raw_figure: if True, returns the raw figure object (e.g. bokeh.plotting.figure or plotly.graph_objects.Figure)
+            if False, returns the holoviews.core.overlay.Overlay object
+        num_data: the initial number of data points to display.
+            This can be changed by a slider in the plot.
+        up_color: the color of the up candle, hex code is supported
+        down_color: the color of the down candle, hex code is supported
+        bg_color: the background color of the plot, hex code is supported
+        height: the height of the plot
+        width: the width of the plot
+    '''
+    # TODO: add volume plot when show_volume is True
+    # TODO: add range selector
+    # TODO: date input
+    # TODO: using tick data to update the current candlestick
+    
+    
+    display_mode, plotting_backend = DisplayMode[display_mode.lower()], PlottingBackend.bokeh
+    data_type: DataType = validate_data_type(data, streaming, import_hvplot=True)
+    if data_type == DataType.datafeed:
+        # TODO: get streaming data in the format of dataframe, and then call _validate_df
+        # df = data.get_realtime_data(...)
+        pass
+    else:
+        df = data
+    df: FrameT = _validate_df(df)
+    
+    
+    # Define reactive values    
+    max_num_data = pn.rx(df.shape[0])
+    
+    # Main Component: candlestick plot
+    def _create_plot(_df: FrameT, _num_data: int):
+        plot_df: tDataFrame = _df.tail(_num_data).to_native()
+        return (
+            plot_df
+            .hvplot
+            .ohlc(
+                'ts', ['open', 'low', 'high', 'close'],
+                hover_cols=REQUIRED_COLS,
+                tools=[
+                    _create_hover_tool(_df), 
+                    CrosshairTool(dimensions='height', line_color='gray', line_alpha=0.3)
+                ],
+                grid=grid,
+                pos_color=up_color,
+                neg_color=down_color,
+                responsive=True,
+                bgcolor=bg_color,
+            )
+            .opts(**_get_style(_df, display_mode, height, width))
+        )
+
+    # Side Components 1: data points slider
+    points_slider = pn.widgets.IntSlider(
+        name='Number of Most Recent Data Points', 
+        value=min(num_data, max_num_data.rx.value),
+        start=num_data,
+        end=max_num_data,
+        step=slider_step,
+    )
+    
+    # Side Components 2: show all data button
+    show_all_data_button = pn.widgets.Button(
+        name='Show All',
+        button_type='primary',
+    )
+    def max_out_slider(event):
+        points_slider.value = max_num_data.rx.value
+    show_all_data_button.on_click(max_out_slider)
+    
+
+    periodic_callback = None
+    if raw_figure:
+        fig: Overlay = _create_plot(df, _num_data=num_data)
+    else:
+        if not streaming:
+            plot_pane = pn.pane.HoloViews(
+                pn.bind(_create_plot, _df=df, _num_data=points_slider)
+            )
+        else:
+            # NOTE: do NOT bind the plot to the slider, otherwise the change of slider value and the periodic callback 
+            # will BOTH trigger the plot update, causing an error, probably a race condition
+            plot_pane = pn.pane.HoloViews(_create_plot(df, points_slider.value))
+            
+            def _update_plot():
+                # FIXME
+                # TEMP: fake streaming data
+                import pandas as pd
+                nonlocal df
+                pandas_df = df.to_native()
+                last_ts = pandas_df['ts'].iloc[-1]
+                new_ts = last_ts + pd.Timedelta(days=1)
+                new_row = pd.DataFrame({
+                    'date': [new_ts.date()],
+                    'ts': [new_ts],
+                    'symbol': ['AAPL'],
+                    'product': ['AAPL_USD_STK'],
+                    'open': [pandas_df['open'].iloc[-1] * 1.01],  # 1% higher than last price
+                    'high': [pandas_df['high'].iloc[-1] * 1.02],
+                    'low': [pandas_df['low'].iloc[-1] * 0.99],
+                    'close': [pandas_df['close'].iloc[-1] * 1.015],
+                    'volume': [int(pandas_df['volume'].iloc[-1] * 0.8)]
+                })
+                df2 = pd.concat([pandas_df, new_row], ignore_index=True)
+                df = nw.from_native(df2)
+
+                # this will also update the slider's end value since it's a reactive object
+                max_num_data.rx.value = df.shape[0]
+                
+                plot_pane.object = _create_plot(df, points_slider.value)
+
+            periodic_callback = pn.state.add_periodic_callback(_update_plot, period=streaming_freq, start=False)  # period in milliseconds
+        fig: Panel = pn.Column(
+            plot_pane,
+            pn.Row(points_slider, show_all_data_button, align='center'),
+            sizing_mode='stretch_both',
+            name=DEFAULT_STYLE['title'],
+        )
+    return render(fig, display_mode, raw_figure=raw_figure, plotting_backend=plotting_backend, periodic_callback=periodic_callback)