investment-python 0.1.0b1__tar.gz

investment_python-0.1.0b1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rui Xue
+
+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.

investment_python-0.1.0b1/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: investment-python
+Version: 0.1.0b1
+Summary: Add your description here
+Author: Rui Xue
+Author-email: Rui Xue <ruixue.fi@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Dist: matplotlib>=3.11.1
+Requires-Dist: pandas>=3.0.5
+Requires-Dist: requests>=2.34.2
+Requires-Dist: yfinance>=1.6.0
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# investment-python
+
+A command-line tool for pulling stock market quotes and fundamentals (price,
+P/E, ROE, P/B, dividend yield, and more) for a watch list of companies given
+as ticker symbols or a CSV file. It can sort the results, flag stocks trading
+outside a given price range, and export everything to CSV.
+
+## Requirements
+
+- Python 3.13+
+- [`uv`](https://docs.astral.sh/uv/) for dependency management and running the tool
+
+Install dependencies with:
+
+```
+uv sync
+```
+
+Then run the tool with `uv run investment ...`.
+
+## Usage
+### Fetch Metrics
+
+```
+uv run investment metrics METRIC_NAMES (--company-symbols SYMBOLS | --company-csv PATH_OR_URL) [options]
+```
+
+- `METRIC_NAMES` — required, positional. One or more metrics delimited by
+  comma, e.g. `PRICE,TRAILING_PE`. Choose from: `COMPANY_NAME`, `PRICE`,
+  `PRICE_IN_EURO`, `MARKET_STATE`, `TRAILING_PE`, `DIVIDEND_YIELD`,
+  `DIVIDEND_PAYOUT_RATIO`, `RETURN_ON_EQUITY`, `REGULAR_MARKET_CHANGE_PERCENT`,
+  `PRICE_TO_BOOK`.
+- `--company-symbols` — company ticker symbols as used on *Yahoo Finance*,
+  delimited by comma, e.g. `AAPL,ELISA.HE`. Mutually exclusive with
+  `--company-csv`; one of the two is required.
+- `--company-csv` — path or URL to a CSV file with a `Yahoo Company Symbol`
+  column.
+- `--sort-by` — optional. Sort results ascending by this metric; must be one
+  of the metrics given in `METRIC_NAMES`.
+- `--price-ranges` — optional. Flag companies whose price falls outside a
+  range, formatted as `COMPANY_ID1:MIN:MAX,COMPANY_ID2:MIN:`, e.g.
+  `AAPL:150:200,ELISA.HE:30:`. Leave `MIN` or `MAX` empty for no lower/upper
+  bound.
+- `--output-csv-name` — optional. Also write the metrics result to this CSV
+  file. When given, any companies that failed to fetch are additionally
+  written to `companies_with_error.csv`, and any companies outside their
+  price range (per `--price-ranges`) are written to `alert_on_companies.csv`.
+
+#### Example Command
+
+`uv run investment metrics COMPANY_NAME,PRICE,REGULAR_MARKET_CHANGE_PERCENT,PRICE_IN_EURO,TRAILING_PE,RETURN_ON_EQUITY,PRICE_TO_BOOK,DIVIDEND_YIELD --sort-by REGULAR_MARKET_CHANGE_PERCENT --company-symbols ELISA.HE,FIA1S.HE,NOVO-B.CO`
+
+### Benchmarking
+
+Compare a stock's price performance against a benchmark (an index or another
+stock) over a given period: both series are rebased to an index of 100 at the
+start date, and a beta coefficient (`Cov(stock, benchmark) / Var(benchmark)`,
+from daily returns) is printed.
+
+```
+uv run investment benchmark BENCHMARK_ID:COMPANY_ID --start-date START_DATE --end-date END_DATE [--graph-directory DIRECTORY]
+```
+
+- `BENCHMARK_ID:COMPANY_ID` — required, positional. The benchmark and company
+  ticker symbols, delimited by a colon, e.g. `VOO:T`.
+- `--start-date` — required. Start date of the period, in ISO format, e.g.
+  `2021-08-30`.
+- `--end-date` — required. End date of the period, in ISO format, e.g.
+  `2026-08-30`.
+- `--graph-directory` — optional. Save the chart as a PNG named
+  `COMPANY_ID_vs_BENCHMARK_ID.png` in this directory. If omitted, the chart is
+  not saved.
+
+The chart is always displayed in a window (this blocks until the window is
+closed).
+
+#### Example Command
+
+`uv run investment benchmark VOO:T --start-date 2021-08-30 --end-date 2026-08-30 --graph-directory ./charts`

investment_python-0.1.0b1/README.md

@@ -0,0 +1,79 @@
+# investment-python
+
+A command-line tool for pulling stock market quotes and fundamentals (price,
+P/E, ROE, P/B, dividend yield, and more) for a watch list of companies given
+as ticker symbols or a CSV file. It can sort the results, flag stocks trading
+outside a given price range, and export everything to CSV.
+
+## Requirements
+
+- Python 3.13+
+- [`uv`](https://docs.astral.sh/uv/) for dependency management and running the tool
+
+Install dependencies with:
+
+```
+uv sync
+```
+
+Then run the tool with `uv run investment ...`.
+
+## Usage
+### Fetch Metrics
+
+```
+uv run investment metrics METRIC_NAMES (--company-symbols SYMBOLS | --company-csv PATH_OR_URL) [options]
+```
+
+- `METRIC_NAMES` — required, positional. One or more metrics delimited by
+  comma, e.g. `PRICE,TRAILING_PE`. Choose from: `COMPANY_NAME`, `PRICE`,
+  `PRICE_IN_EURO`, `MARKET_STATE`, `TRAILING_PE`, `DIVIDEND_YIELD`,
+  `DIVIDEND_PAYOUT_RATIO`, `RETURN_ON_EQUITY`, `REGULAR_MARKET_CHANGE_PERCENT`,
+  `PRICE_TO_BOOK`.
+- `--company-symbols` — company ticker symbols as used on *Yahoo Finance*,
+  delimited by comma, e.g. `AAPL,ELISA.HE`. Mutually exclusive with
+  `--company-csv`; one of the two is required.
+- `--company-csv` — path or URL to a CSV file with a `Yahoo Company Symbol`
+  column.
+- `--sort-by` — optional. Sort results ascending by this metric; must be one
+  of the metrics given in `METRIC_NAMES`.
+- `--price-ranges` — optional. Flag companies whose price falls outside a
+  range, formatted as `COMPANY_ID1:MIN:MAX,COMPANY_ID2:MIN:`, e.g.
+  `AAPL:150:200,ELISA.HE:30:`. Leave `MIN` or `MAX` empty for no lower/upper
+  bound.
+- `--output-csv-name` — optional. Also write the metrics result to this CSV
+  file. When given, any companies that failed to fetch are additionally
+  written to `companies_with_error.csv`, and any companies outside their
+  price range (per `--price-ranges`) are written to `alert_on_companies.csv`.
+
+#### Example Command
+
+`uv run investment metrics COMPANY_NAME,PRICE,REGULAR_MARKET_CHANGE_PERCENT,PRICE_IN_EURO,TRAILING_PE,RETURN_ON_EQUITY,PRICE_TO_BOOK,DIVIDEND_YIELD --sort-by REGULAR_MARKET_CHANGE_PERCENT --company-symbols ELISA.HE,FIA1S.HE,NOVO-B.CO`
+
+### Benchmarking
+
+Compare a stock's price performance against a benchmark (an index or another
+stock) over a given period: both series are rebased to an index of 100 at the
+start date, and a beta coefficient (`Cov(stock, benchmark) / Var(benchmark)`,
+from daily returns) is printed.
+
+```
+uv run investment benchmark BENCHMARK_ID:COMPANY_ID --start-date START_DATE --end-date END_DATE [--graph-directory DIRECTORY]
+```
+
+- `BENCHMARK_ID:COMPANY_ID` — required, positional. The benchmark and company
+  ticker symbols, delimited by a colon, e.g. `VOO:T`.
+- `--start-date` — required. Start date of the period, in ISO format, e.g.
+  `2021-08-30`.
+- `--end-date` — required. End date of the period, in ISO format, e.g.
+  `2026-08-30`.
+- `--graph-directory` — optional. Save the chart as a PNG named
+  `COMPANY_ID_vs_BENCHMARK_ID.png` in this directory. If omitted, the chart is
+  not saved.
+
+The chart is always displayed in a window (this blocks until the window is
+closed).
+
+#### Example Command
+
+`uv run investment benchmark VOO:T --start-date 2021-08-30 --end-date 2026-08-30 --graph-directory ./charts`

investment_python-0.1.0b1/pyproject.toml

@@ -0,0 +1,53 @@
+[project]
+name = "investment-python"
+version = "0.1.0b1"
+description = "Add your description here"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Rui Xue", email = "ruixue.fi@gmail.com" }
+]
+requires-python = ">=3.13"
+dependencies = [
+    "matplotlib>=3.11.1",
+    "pandas>=3.0.5",
+    "requests>=2.34.2",
+    "yfinance>=1.6.0",
+]
+
+[project.scripts]
+investment = "investment.cli.main:main"
+
+[build-system]
+requires = ["uv_build>=0.11.6,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "investment"
+
+[dependency-groups]
+dev = [
+    "pandas-stubs>=3.0.5.260730",
+    "pyright>=1.1.411",
+    "pytest>=9.1.1",
+    "ruff>=0.16.4",
+]
+
+[tool.pytest.ini_options]
+markers = [
+    "integration: hits live external APIs (Yahoo Finance, ECB); slower and network-dependent.",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py313"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I"]
+
+[tool.pyright]
+pythonVersion = "3.13"
+include = ["src"]
+reportUnnecessaryTypeIgnoreComment = true
+reportUnnecessaryCast = true

investment_python-0.1.0b1/src/investment/benchmark/chart_data.py

@@ -0,0 +1,56 @@
+from typing import NamedTuple
+
+import pandas as pd
+
+from investment.marketquote.repository import fetch_historical_prices
+from investment.vo.value_objects import Period, PriceSeries
+
+
+class LabeledIndexSeries(NamedTuple):
+    symbol: str
+    index_series: pd.Series
+
+class ChartData(NamedTuple):
+    benchmark: tuple[str,PriceSeries]
+    stock: tuple[str,PriceSeries]
+    base:float=100
+
+
+    def _to_index(self, price_series:PriceSeries) -> pd.Series:
+        prices = pd.Series(price_series.cent_prices).sort_index()
+        return prices / prices.iloc[0] * self.base
+
+    def benchmark_index(self) -> LabeledIndexSeries:
+        """Return the benchmark's price series rebased to ``base`` at its first date."""
+        benchmark_id = self.benchmark[0]
+        price_series = self.benchmark[1]
+        return LabeledIndexSeries(benchmark_id, self._to_index(price_series))
+
+    def stock_index(self) -> LabeledIndexSeries:
+        """Return the stock's price series rebased to ``base`` at its first date."""
+        company_id = self.stock[0]
+        price_series = self.stock[1]
+        return LabeledIndexSeries(company_id, self._to_index(price_series))
+
+    def coefficient(self)->float:
+        """Return the stock's beta relative to the benchmark over the period.
+
+        Beta = Cov(stock returns, benchmark returns) / Var(benchmark returns),
+        computed from daily returns of the raw price series.
+        """
+        benchmark_prices = pd.Series(self.benchmark[1].cent_prices).sort_index()
+        stock_prices = pd.Series(self.stock[1].cent_prices).sort_index()
+        benchmark_returns = benchmark_prices.pct_change().dropna()
+        stock_returns = stock_prices.pct_change().dropna()
+        aligned = pd.concat(
+            [benchmark_returns, stock_returns], axis=1, join="inner", keys=["benchmark", "stock"]
+        )
+        covariance = aligned["stock"].cov(aligned["benchmark"])
+        variance = aligned["benchmark"].var()
+        return covariance / variance
+
+    @staticmethod
+    def generate(benchmark_id:str, company_id:str, period:Period) -> "ChartData":
+        benchmark_price_series = fetch_historical_prices(benchmark_id, period)
+        stock_price_series = fetch_historical_prices(company_id, period)
+        return ChartData((benchmark_id, benchmark_price_series), (company_id, stock_price_series))

investment_python-0.1.0b1/src/investment/cli/__main__.py

@@ -0,0 +1,7 @@
+"""Enables ``python -m investment.cli`` as an alternative to the
+``investment-python`` console script.
+"""
+from investment.cli.main import main
+
+if __name__ == "__main__":
+    main()

investment_python-0.1.0b1/src/investment/cli/main.py

@@ -0,0 +1,161 @@
+"""Command-line entry point for the investment toolkit.
+
+Usage examples::
+
+    investment-python price AAPL
+    investment-python price AAPL --date 2026-08-01
+    investment-python metrics PRICE,TRAILING_PE --company-symbols AAPL
+"""
+import argparse
+import logging
+import os
+import sys
+from enum import StrEnum
+from typing import Sequence
+
+from investment.cli.program_runner import _generate_benchmark_chart, _run_benchmark, _run_metrics
+from investment.marketquote import repository
+
+
+class Command(StrEnum):
+    METRICS = "metrics"
+    BENCHMARK = "benchmark"
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="investment", description="Fetch market quotes and fundamentals."
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+    def _build_metrics_parser() -> None:
+        metrics_parser = subparsers.add_parser(
+            Command.METRICS, help="Fetch metrics for symbols."
+        )
+        metrics_parser.add_argument(
+            "metric_names",
+            help="One or more metrics to fetch, delimited by comma, e.g. PRICE,TRAILING_PE. "
+            f"Choose from {', '.join(metric.name for metric in repository.Metric)}.",
+        )
+        company_source_group = metrics_parser.add_mutually_exclusive_group(required=True)
+        company_source_group.add_argument(
+            "--company-symbols",
+            help="Company ticker symbols delimited by comma, e.g. AAPL,ELISA.HE",
+        )
+        company_source_group.add_argument(
+            "--company-csv",
+            help="Path or URL to a company CSV file with a 'Yahoo Company Symbol' column, "
+            "e.g. https://gist.githubusercontent.com/rxue/7ec0914a8af1525d97e8dfd2ac5d61d7/raw/companies.csv",
+        )
+        metrics_parser.add_argument(
+            "--sort-by",
+            default=None,
+            help="Sort results by this metric, ascending. Must be one of the metrics in --names.",
+        )
+        metrics_parser.add_argument(
+            "--price-ranges",
+            default=None,
+            help="If given on the premises of price is also given, it should be in the format "
+            "like COMPANY_ID1:12:22,COMPANY_ID2:100:",
+        )
+        metrics_parser.add_argument(
+            "--output-csv-name",
+            default=None,
+            help="If given, also write the metrics result to this CSV file path.",
+        )
+    def _build_benchmark_parser() -> None:
+        benchmark_parser = subparsers.add_parser(
+            Command.BENCHMARK, help="Benchmark stocks against an index or another stock."
+        )
+        benchmark_parser.add_argument(
+            "benchmark_pair",
+            help="The benchmark and company ticker symbols, delimited by a colon, "
+            "e.g. VOO:T.",
+        )
+        benchmark_parser.add_argument(
+            "--start-date",
+            required=True,
+            help="Start date of the period, in ISO format, e.g. 2024-01-01.",
+        )
+        benchmark_parser.add_argument(
+            "--end-date",
+            required=True,
+            help="End date of the period, in ISO format, e.g. 2026-01-01.",
+        )
+        benchmark_parser.add_argument(
+            "--graph-directory",
+            default=None,
+            help="If given, save the chart as a PNG into this directory. "
+            "If omitted, the chart is not saved.",
+        )
+    _build_metrics_parser()
+    _build_benchmark_parser()
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> None:
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s %(levelname)s %(name)s.%(funcName)s: %(message)s",
+        stream=sys.stdout,
+    )
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    if args.command == Command.METRICS:
+        metrics, erratic_company_ids, metrics_records_out_of_range = _run_metrics(
+            names=args.metric_names,
+            company_symbols=args.company_symbols,
+            company_csv=args.company_csv,
+            sort_by=args.sort_by,
+            price_ranges_str=args.price_ranges,
+        )
+        print(metrics.to_string(index=False))
+        if not erratic_company_ids.empty:
+            print()
+            print("Companies fetched with error")
+            print(erratic_company_ids.to_string(index=False))
+        if metrics_records_out_of_range is not None:
+            print()
+            print("Stocks with price out of range")
+            print(metrics_records_out_of_range.to_string(index=False))
+
+        if args.output_csv_name:
+            metrics.to_csv(args.output_csv_name, index=False)
+            if not erratic_company_ids.empty:
+                erratic_company_ids.to_csv("companies_with_error.csv", index=False)
+            if not metrics_records_out_of_range.empty:
+                metrics_records_out_of_range.to_csv("alert_on_companies.csv", index=False)
+    elif args.command == Command.BENCHMARK:
+        try:
+            benchmark_id, company_id = args.benchmark_pair.split(":")
+        except ValueError:
+            parser.error(
+                f"argument benchmark_pair: invalid format: {args.benchmark_pair!r} "
+                "(expected BENCHMARK_ID:COMPANY_ID, e.g. VOO:T)"
+            )
+        chart_data = _run_benchmark(
+            benchmark_id=benchmark_id,
+            company_id=company_id,
+            start_date=args.start_date,
+            end_date=args.end_date,
+        )
+        benchmark_index = chart_data.benchmark_index()
+        stock_index = chart_data.stock_index()
+        print(
+            f"Coefficient ({stock_index.symbol} vs {benchmark_index.symbol}): "
+            f"{chart_data.coefficient():.4f}"
+        )
+        output_path = None
+        if args.graph_directory:
+            output_path = os.path.join(
+                args.graph_directory, f"{stock_index.symbol}_vs_{benchmark_index.symbol}.png"
+            )
+        chart_path = _generate_benchmark_chart(chart_data, output_path=output_path)
+        if chart_path is not None:
+            print(f"Chart saved to {chart_path}")
+
+    else:  # pragma: no cover - guarded by argparse's `required=True`
+        parser.error(f"Unknown command: {args.command}")
+
+
+if __name__ == "__main__":
+    main()

investment_python-0.1.0b1/src/investment/cli/program_runner.py

@@ -0,0 +1,153 @@
+"""Orchestration for the CLI ``metrics`` command."""
+
+import logging
+import time
+from datetime import date
+
+import matplotlib.pyplot as plt
+import pandas as pd
+
+from investment.benchmark.chart_data import ChartData
+from investment.marketquote import metrics, repository
+from investment.marketquote.filter import Range, records_out_of_range
+from investment.util.decorator import clock
+from investment.vo.value_objects import Period
+
+logger = logging.getLogger(__name__)
+
+
+@clock
+def _run_metrics(
+    names: str,
+    company_symbols: str | None = None,
+    company_csv: str | None = None,
+    sort_by: str | None = None,
+    price_ranges_str: str | None = None,
+) -> tuple[pd.DataFrame, pd.DataFrame, pd.DataFrame]:
+    def extract_price_ranges() -> dict[str, Range]:
+        if not price_ranges_str:
+            return {}
+        result: dict[str, Range] = {}
+        for entry in price_ranges_str.split(","):
+            company_id, start, end = entry.split(":")
+            result[company_id] = Range(
+                start=float(start) if start else None,
+                end=float(end) if end else None,
+            )
+        return result
+
+    def _load_company_symbols(csv_source: str) -> str:
+        """Load comma-delimited Yahoo ticker symbols from a company CSV file.
+
+        ``csv_source`` may be a local file path or an http(s) URL. The CSV must
+        contain a "Yahoo Company Symbol" column, e.g.
+        https://gist.githubusercontent.com/rxue/7ec0914a8af1525d97e8dfd2ac5d61d7/raw/companies.csv
+        """
+        companies = pd.read_csv(csv_source)
+        return ",".join(companies["Yahoo Company Symbol"].astype(str))
+
+    metric_names = [name.strip() for name in names.split(",")]
+    try:
+        metric_list = [repository.Metric[name] for name in metric_names]
+    except KeyError as exc:
+        valid_names = ", ".join(metric.name for metric in repository.Metric)
+        raise SystemExit(
+            f"investment metrics: error: argument --names: invalid choice: {exc.args[0]!r} "
+            f"(choose from {valid_names})"
+        ) from None
+
+    sort_by_metric = None
+    if sort_by is not None:
+        try:
+            sort_by_metric = repository.Metric[sort_by]
+        except KeyError:
+            valid_names = ", ".join(metric.name for metric in repository.Metric)
+            raise SystemExit(
+                f"investment metrics: error: argument --sort-by: invalid choice: {sort_by!r} "
+                f"(choose from {valid_names})"
+            ) from None
+        if sort_by_metric not in metric_list:
+            raise SystemExit(
+                f"investment metrics: error: argument --sort-by: {sort_by!r} must be one of the "
+                f"metrics in --names ({', '.join(metric_names)})"
+            )
+
+    if company_symbols:
+        company_ids = company_symbols
+    elif company_csv is not None:
+        company_ids = _load_company_symbols(company_csv)
+    else:
+        raise SystemExit(
+            "investment metrics: error: one of --company-symbols or --company-csv is required"
+        )
+    company_id_list = [symbol.strip() for symbol in company_ids.split(",")]
+    batch_size = 100
+    thread_amount = 10
+    if len(company_id_list) > batch_size:
+        rows = []
+        erratic_rows = []
+        for i in range(0, len(company_id_list), batch_size):
+            batch = company_id_list[i : i + batch_size]
+            metrics_records, erratic_metrics_records = repository.fetch_current_metrics_batch(
+                batch, metric_list, thread_amount
+            )
+            rows.extend(metrics_records)
+            erratic_metrics_records.extend(erratic_metrics_records)
+            logger.info("Executed one batch")
+            time.sleep(60)
+    else:
+        rows, erratic_rows = repository.fetch_current_metrics_batch(
+            company_id_list, metric_list, thread_amount
+        )
+
+    if sort_by_metric is not None:
+        rows = metrics.sort_records(rows, sort_by_metric)
+    records_out_of_range_df = pd.DataFrame()
+    if price_ranges_str is not None:
+        price_ranges = extract_price_ranges()
+        records_outside = records_out_of_range(rows, price_ranges)
+        records_out_of_range_df = pd.DataFrame([r.to_readable() for r in records_outside])
+    return (
+        pd.DataFrame([r.to_readable() for r in rows]),
+        pd.DataFrame([r.company_id for r in erratic_rows], columns=["non-existing company"]),
+        records_out_of_range_df,
+    )
+
+def _run_benchmark(benchmark_id:str,company_id:str,start_date:str,end_date:str) -> ChartData:
+    period = Period(from_date=date.fromisoformat(start_date), to_date=date.fromisoformat(end_date))
+    return ChartData.generate(benchmark_id, company_id, period)
+
+def _generate_benchmark_chart(
+    chart_data:ChartData, output_path:str|None=None, show:bool=True
+) -> str|None:
+    """Plot the benchmark's and stock's rebased index series.
+
+    Displays the chart in a window by default (``show=True``). Saved to
+    ``output_path`` only if given; returns that path, or ``None`` if not saved.
+    """
+    benchmark_index = chart_data.benchmark_index()
+    stock_index = chart_data.stock_index()
+
+    fig, ax = plt.subplots()
+    ax.plot(
+        benchmark_index.index_series.index.to_numpy(), benchmark_index.index_series.to_numpy(),
+        label=benchmark_index.symbol,
+    )
+    ax.plot(
+        stock_index.index_series.index.to_numpy(), stock_index.index_series.to_numpy(),
+        label=stock_index.symbol,
+    )
+    ax.axhline(chart_data.base, color="gray", linestyle="--", linewidth=0.8)
+    ax.set_title(
+        f"{stock_index.symbol} vs {benchmark_index.symbol} — indexed to {chart_data.base:.0f}"
+    )
+    ax.set_ylabel("Index value")
+    ax.legend()
+    fig.autofmt_xdate()
+
+    if output_path is not None:
+        fig.savefig(output_path, dpi=150)
+    if show:
+        plt.show()
+    plt.close(fig)
+    return output_path