jquantstats 0.9.2__tar.gz → 0.9.4__tar.gz

{jquantstats-0.9.2 → jquantstats-0.9.4}/.gitignore

@@ -127,3 +127,6 @@ report.html
 /prices.csv
 LICENSES.md
 /test_output/
+
+# local planning file
+plan.md

jquantstats-0.9.4/.rhiza/completions/README.md

@@ -0,0 +1,263 @@
+# Shell Completion for Rhiza Make Targets
+
+This directory contains shell completion scripts for Bash and Zsh that provide tab-completion for make targets in Rhiza-based projects.
+
+## Features
+
+- ✅ Tab-complete all available make targets
+- ✅ Show target descriptions in Zsh
+- ✅ Complete common make variables (DRY_RUN, BUMP, ENV, etc.)
+- ✅ Works with any Rhiza-based project
+- ✅ Auto-discovers targets from Makefile and included .mk files
+
+## Installation
+
+### Bash
+
+#### Method 1: Source in your shell config
+
+Add to your `~/.bashrc` or `~/.bash_profile`:
+
+```bash
+# Rhiza make completion
+if [ -f /path/to/project/.rhiza/completions/rhiza-completion.bash ]; then
+    source /path/to/project/.rhiza/completions/rhiza-completion.bash
+fi
+```
+
+Replace `/path/to/project` with the actual path to your Rhiza project.
+
+#### Method 2: System-wide installation
+
+```bash
+# Copy to bash completion directory
+sudo cp .rhiza/completions/rhiza-completion.bash /etc/bash_completion.d/rhiza
+
+# Reload completions
+source /etc/bash_completion.d/rhiza
+```
+
+#### Method 3: User-local installation
+
+```bash
+# Create local completion directory
+mkdir -p ~/.local/share/bash-completion/completions
+
+# Copy completion script
+cp .rhiza/completions/rhiza-completion.bash ~/.local/share/bash-completion/completions/make
+
+# Reload bash
+source ~/.bashrc
+```
+
+### Zsh
+
+#### Method 1: User-local installation (Recommended)
+
+```bash
+# Create completion directory
+mkdir -p ~/.zsh/completion
+
+# Copy completion script
+cp .rhiza/completions/rhiza-completion.zsh ~/.zsh/completion/_make
+
+# Add to ~/.zshrc (if not already present)
+echo 'fpath=(~/.zsh/completion $fpath)' >> ~/.zshrc
+echo 'autoload -U compinit && compinit' >> ~/.zshrc
+
+# Reload zsh
+source ~/.zshrc
+```
+
+#### Method 2: Source directly
+
+Add to your `~/.zshrc`:
+
+```zsh
+# Rhiza make completion
+if [ -f /path/to/project/.rhiza/completions/rhiza-completion.zsh ]; then
+    source /path/to/project/.rhiza/completions/rhiza-completion.zsh
+fi
+```
+
+#### Method 3: System-wide installation
+
+```bash
+# Copy to system completion directory
+sudo cp .rhiza/completions/rhiza-completion.zsh /usr/local/share/zsh/site-functions/_make
+
+# Reload zsh
+exec zsh
+```
+
+## Usage
+
+Once installed, you can tab-complete make targets:
+
+```bash
+# Tab-complete targets
+make <TAB>
+
+# Complete with prefix
+make te<TAB>  # Expands to: make test
+
+# Complete variables
+make BUMP=<TAB>  # Shows: patch, minor, major
+
+# Works with any target
+make doc<TAB>  # Shows: docs, docker-build, docker-run, etc.
+```
+
+### Zsh Benefits
+
+In Zsh, you'll also see descriptions for targets:
+
+```bash
+make <TAB>
+# Shows:
+# test        -- run all tests
+# fmt         -- check the pre-commit hooks and the linting
+# install     -- install
+# book        -- build documentation site via zensical
+# ...
+```
+
+## Common Variables
+
+The completion scripts understand these common variables:
+
+| Variable | Values | Description |
+|----------|--------|-------------|
+| `DRY_RUN` | `1` | Preview mode without making changes |
+| `BUMP` | `patch`, `minor`, `major` | Version bump type |
+| `ENV` | `dev`, `staging`, `prod` | Target environment |
+| `COVERAGE_FAIL_UNDER` | (number) | Minimum coverage threshold |
+| `PYTHON_VERSION` | (version) | Override Python version |
+
+Example usage:
+
+```bash
+# Tab-complete after typing DRY_
+make DRY_<TAB>     # Expands to: make DRY_RUN=1
+
+# Tab-complete variable values
+make BUMP=<TAB>    # Shows: patch minor major
+
+# Combine with targets
+make bump BUMP=<TAB>
+```
+
+## Troubleshooting
+
+### Bash: Completions not working
+
+1. Check if bash-completion is installed:
+   ```bash
+   # Debian/Ubuntu
+   sudo apt-get install bash-completion
+   
+   # macOS
+   brew install bash-completion@2
+   ```
+
+2. Ensure completion is enabled in your shell:
+   ```bash
+   # Add to ~/.bashrc if not present
+   if [ -f /etc/bash_completion ]; then
+       . /etc/bash_completion
+   fi
+   ```
+
+3. Reload your shell configuration:
+   ```bash
+   source ~/.bashrc
+   ```
+
+### Zsh: Completions not working
+
+1. Check if compinit is called in your `~/.zshrc`:
+   ```zsh
+   autoload -U compinit && compinit
+   ```
+
+2. Clear the completion cache:
+   ```bash
+   rm -f ~/.zcompdump
+   compinit
+   ```
+
+3. Ensure the script is in your fpath:
+   ```zsh
+   echo $fpath
+   ```
+
+4. Reload your shell configuration:
+   ```zsh
+   source ~/.zshrc
+   ```
+
+### No targets appearing
+
+1. Ensure you're in a directory with a Makefile:
+   ```bash
+   ls -la Makefile
+   ```
+
+2. Test that make can parse the Makefile:
+   ```bash
+   make -qp 2>/dev/null | head
+   ```
+
+3. Manually source the completion script to test:
+   ```bash
+   # Bash
+   source .rhiza/completions/rhiza-completion.bash
+   
+   # Zsh
+   source .rhiza/completions/rhiza-completion.zsh
+   ```
+
+## Optional Aliases
+
+You can add shortcuts in your shell config:
+
+```bash
+# Add to ~/.bashrc or ~/.zshrc
+alias m='make'
+
+# For bash:
+complete -F _rhiza_make_completion m
+
+# For zsh:
+compdef _rhiza_make m
+```
+
+Then use:
+```bash
+m te<TAB>  # Expands to: m test
+```
+
+## Technical Details
+
+### How it works
+
+1. **Target Discovery**: Parses `make -qp` output to find all targets
+2. **Description Extraction**: Looks for `##` comments after target names
+3. **Variable Detection**: Includes common Makefile variables
+4. **Dynamic Completion**: Regenerates list each time you tab
+
+### Performance
+
+- Completions are generated on-demand (when you press Tab)
+- For large Makefiles (100+ targets), there may be a small delay
+- Results are not cached to ensure targets are always current
+
+## See Also
+
+- [Tools Reference](../../docs/reference/TOOLS_REFERENCE.md) - Complete command reference
+- [Quick Reference](../../docs/guides/QUICK_REFERENCE.md) - Quick command reference
+- [Extending Rhiza](../../docs/guides/EXTENDING_RHIZA.md) - How to add custom targets
+
+---
+
+*Last updated: 2026-02-15*

{jquantstats-0.9.2 → jquantstats-0.9.4}/PKG-INFO

@@ -1,14 +1,16 @@
 Metadata-Version: 2.4
 Name: jquantstats
-Version: 0.9.2
+Version: 0.9.4
 Summary: Analytics for quants
-Project-URL: repository, https://github.com/jebel-quant/jquantstats
+Project-URL: Homepage, https://github.com/jebel-quant/jquantstats
+Project-URL: Repository, https://github.com/jebel-quant/jquantstats
 Author-email: tschm <thomas.schmelzer@gmail.com>
 License-Expression: MIT
 License-File: LICENSE
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Financial and Insurance Industry
 Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
@@ -20,7 +22,7 @@ Requires-Dist: jinja2>=3.1.0
 Requires-Dist: narwhals>=2.0.0
 Requires-Dist: numpy>=2.0.0
 Requires-Dist: plotly>=6.0.0
-Requires-Dist: polars>=1.18.0
+Requires-Dist: polars>=1.35.2
 Requires-Dist: scipy>=1.14.1
 Provides-Extra: plot
 Requires-Dist: kaleido==1.3.0; extra == 'plot'

{jquantstats-0.9.2 → jquantstats-0.9.4}/pyproject.toml

@@ -1,7 +1,7 @@
 # Main project metadata
 [project]
 name = 'jquantstats'
-version = "0.9.2"
+version = "0.9.4"
 description = "Analytics for quants"
 authors = [{name='tschm', email= 'thomas.schmelzer@gmail.com'}]
 readme = "README.md"
@@ -11,7 +11,7 @@ dependencies = [
     "narwhals>=2.0.0",
     "numpy>=2.0.0",
     "plotly>=6.0.0",
-    "polars>=1.18.0",
+    "polars>=1.35.2",
     "scipy>=1.14.1"
 ]
 license = "MIT"
@@ -26,11 +26,13 @@ classifiers = [
   "Programming Language :: Python :: 3.11",
   "Programming Language :: Python :: 3.12",
   "Programming Language :: Python :: 3.13",
+  "License :: OSI Approved :: MIT License",
 ]
 
 # Project URLs for documentation and reference
 [project.urls]
-repository = "https://github.com/jebel-quant/jquantstats"
+Homepage = "https://github.com/jebel-quant/jquantstats"
+Repository = "https://github.com/jebel-quant/jquantstats"
 
 # Optional dependencies that can be installed with extras (e.g., pip install jquantstats[plot])
 [project.optional-dependencies]
@@ -45,12 +47,29 @@ web = [
 dev = [
     "pandas>=2.2.3",       # required by quantstats (comparison tests only — not a runtime dependency)
     "pyarrow>=22.0.0",
-    "yfinance==1.3.0",
-    "ipython==9.13.0",
+    "yfinance==1.4.1",
+    "ipython==9.14.1",
     "quantstats==0.0.81",  # reference implementation used in test_quantstats.py for metric validation
     "httpx>=0.28.1",
     "marimo>=0.23.6",
 ]
+test = [
+    "pytest>=8.0",
+    "pytest-cov>=6.0",
+    "pytest-html>=4.0",
+    "pytest-mock>=3.0",
+    "pytest-xdist>=3.0",
+    "pytest-timeout>=2.0",
+    "pytest-benchmark>=5.2.3",
+    "hypothesis>=6.150.0",
+    "syrupy>=4.9.1",
+    "pygal>=3.1.0",
+    "python-dotenv>=1.0",
+]
+lint = [
+    "pre-commit>=4.0",
+    "ty>=0.0.30",
+]
 
 
 # Build system configuration
@@ -101,10 +120,15 @@ pyarrow = "pyarrow"
 httpx = "httpx"
 
 # Coverage configuration
+[tool.coverage.run]
+branch = true
+
 [tool.coverage.report]
+fail_under = 100
 exclude_lines = [
     "pragma: no cover",
     "if TYPE_CHECKING:",  # type-only imports are never executed at runtime
+    "@overload",  # overload stubs have no runtime body
 ]
 
 

{jquantstats-0.9.2 → jquantstats-0.9.4}/src/jquantstats/_plots/_data.py

@@ -967,7 +967,7 @@ class DataPlots:
         fig = go.Figure()
         for ticker in tickers:
             hist_returns = df[ticker].tail(sample_len).fill_null(0.0).cast(pl.Float64).to_numpy()
-            if hist_returns.size == 0:
+            if hist_returns.size == 0:  # pragma: no cover
                 continue
 
             simulated_metrics = [

{jquantstats-0.9.2 → jquantstats-0.9.4}/src/jquantstats/_plots/_portfolio.py

@@ -188,7 +188,7 @@ class PortfolioPlots:
             fig.update_yaxes(type="log", row=1, col=1)
             # Ensure the first y-axis is explicitly set for environments
             # where subplot updates may not propagate to layout alias.
-            if hasattr(fig.layout, "yaxis"):
+            if hasattr(fig.layout, "yaxis"):  # pragma: no branch — plotly figures always have .yaxis
                 fig.layout.yaxis.type = "log"
 
         return fig
@@ -212,7 +212,7 @@ class PortfolioPlots:
 
         if log_scale:
             fig.update_yaxes(type="log")
-            if hasattr(fig.layout, "yaxis"):
+            if hasattr(fig.layout, "yaxis"):  # pragma: no branch — plotly figures always have .yaxis
                 fig.layout.yaxis.type = "log"
 
     def lagged_performance_plot(self, lags: list[int] | None = None, log_scale: bool = False) -> go.Figure:
@@ -267,7 +267,7 @@ class PortfolioPlots:
             ValueError: If ``window`` is not a positive integer.
         """
         if not isinstance(window, int) or window <= 0:
-            raise ValueError
+            raise ValueError(f"window must be a positive integer, got {window!r}")  # noqa: TRY003
 
         rolling = self._portfolio.stats.rolling_sharpe(rolling_period=window)
 
@@ -308,7 +308,7 @@ class PortfolioPlots:
             ValueError: If ``window`` is not a positive integer.
         """
         if not isinstance(window, int) or window <= 0:
-            raise ValueError
+            raise ValueError(f"window must be a positive integer, got {window!r}")  # noqa: TRY003
 
         rolling = self._portfolio.stats.rolling_volatility(rolling_period=window)
 

{jquantstats-0.9.2 → jquantstats-0.9.4}/src/jquantstats/_portfolio_attribution.py

@@ -2,7 +2,6 @@
 
 from __future__ import annotations
 
-import contextlib
 from typing import TYPE_CHECKING, Self
 
 import polars as pl
@@ -65,8 +64,9 @@ class PortfolioAttributionMixin:
             cost_per_unit=self.cost_per_unit,
             cost_bps=self.cost_bps,
         )
-        with contextlib.suppress(AttributeError, TypeError):
-            object.__setattr__(self, "_tilt_cache", result)
+        # Direct write is safe: Portfolio is a frozen, slotted dataclass that
+        # declares every cache field, so object.__setattr__ cannot fail here.
+        object.__setattr__(self, "_tilt_cache", result)
         return result
 
     @property

{jquantstats-0.9.2 → jquantstats-0.9.4}/src/jquantstats/_portfolio_cost.py

@@ -2,10 +2,13 @@
 
 from __future__ import annotations
 
+import math
 from typing import TYPE_CHECKING
 
 import polars as pl
 
+from .exceptions import InvalidMaxBpsError, NegativeCostBpsError
+
 if TYPE_CHECKING:
     from .data import Data
 
@@ -120,7 +123,9 @@ class PortfolioCostMixin:
             ``returns`` column reduced by the per-period trading cost.
 
         Raises:
-            ValueError: If ``cost_bps`` is negative.
+            TypeError: If ``cost_bps`` is not a number.
+            ValueError: If ``cost_bps`` is not finite (NaN or infinity).
+            NegativeCostBpsError: If ``cost_bps`` is negative.
 
         Examples:
             >>> from jquantstats.portfolio import Portfolio
@@ -135,8 +140,13 @@ class PortfolioCostMixin:
             True
         """
         effective_bps = cost_bps if cost_bps is not None else self.cost_bps
+        if isinstance(effective_bps, bool) or not isinstance(effective_bps, int | float):
+            raise TypeError(f"cost_bps must be a number, got {type(effective_bps).__name__}")  # noqa: TRY003
+        effective_bps = float(effective_bps)
+        if not math.isfinite(effective_bps):
+            raise ValueError(f"cost_bps must be finite, got {effective_bps}")  # noqa: TRY003
         if effective_bps < 0:
-            raise ValueError
+            raise NegativeCostBpsError(effective_bps)
         base = self.returns
         daily_cost = self.turnover["turnover"] * (effective_bps / 10_000.0)
         return base.with_columns((pl.col("returns") - daily_cost).alias("returns"))
@@ -160,7 +170,7 @@ class PortfolioCostMixin:
             ``max_bps`` inclusive.
 
         Raises:
-            ValueError: If ``max_bps`` is not a positive integer.
+            InvalidMaxBpsError: If ``max_bps`` is not a positive integer.
 
         Examples:
             >>> from jquantstats.portfolio import Portfolio
@@ -183,11 +193,12 @@ class PortfolioCostMixin:
             [0, 1, 2, 3, 4, 5]
         """
         if not isinstance(max_bps, int) or max_bps < 1:
-            raise ValueError
+            raise InvalidMaxBpsError(max_bps)
         import numpy as np
 
+        from ._stats._core import _std_is_negligible
+
         periods = self.data._periods_per_year  # one Data object, outside the loop
-        _eps = np.finfo(np.float64).eps
         sqrt_periods = float(np.sqrt(periods))
         cost_levels = list(range(0, max_bps + 1))
 
@@ -204,7 +215,7 @@ class PortfolioCostMixin:
         sharpe_values: list[float] = []
         for mean_raw, std_raw in zip(means_row, stds_row, strict=False):
             mean_val = 0.0 if mean_raw is None else float(mean_raw)
-            if std_raw is None or float(std_raw) <= _eps * max(abs(mean_val), _eps) * 10:
+            if _std_is_negligible(std_raw, mean_val):
                 sharpe_values.append(float("nan"))
             else:
                 sharpe_values.append(mean_val / float(std_raw) * sqrt_periods)

{jquantstats-0.9.2 → jquantstats-0.9.4}/src/jquantstats/_portfolio_nav.py

@@ -2,12 +2,11 @@
 
 from __future__ import annotations
 
-import contextlib
 from typing import TYPE_CHECKING
 
 import polars as pl
 
-from .exceptions import MissingDateColumnError
+from .exceptions import MissingDateColumnError, NoAssetColumnsError
 
 
 class PortfolioNavMixin:
@@ -68,8 +67,9 @@ class PortfolioNavMixin:
                 pl.when(pl.col(c).is_finite()).then(pl.col(c)).otherwise(0.0).fill_null(0.0).alias(c) for c in assets
             )
 
-        with contextlib.suppress(AttributeError, TypeError):
-            object.__setattr__(self, "_profits_cache", result)
+        # Direct write is safe: Portfolio is a frozen, slotted dataclass that
+        # declares every cache field, so object.__setattr__ cannot fail here.
+        object.__setattr__(self, "_profits_cache", result)
         return result
 
     @property
@@ -78,12 +78,15 @@ class PortfolioNavMixin:
 
         Aggregates per-asset profits into a single ``'profit'`` column and
         validates that no day's total profit is NaN/null.
+
+        Raises:
+            NoAssetColumnsError: If the profits frame has no numeric asset columns.
         """
         df_profits = self.profits
         assets = [c for c in df_profits.columns if df_profits[c].dtype.is_numeric()]
 
         if not assets:
-            raise ValueError
+            raise NoAssetColumnsError("profits")
 
         non_assets = [c for c in df_profits.columns if c not in set(assets)]
 
@@ -121,8 +124,8 @@ class PortfolioNavMixin:
         result = self.nav_accumulated.with_columns(
             (pl.col("profit") / self.aum).alias("returns"),
         )
-        with contextlib.suppress(AttributeError, TypeError):
-            object.__setattr__(self, "_returns_cache", result)
+        # Direct write is safe: see the comment on the profits cache above.
+        object.__setattr__(self, "_returns_cache", result)
         return result
 
     @property

{jquantstats-0.9.2 → jquantstats-0.9.4}/src/jquantstats/_portfolio_turnover.py

@@ -2,7 +2,6 @@
 
 from __future__ import annotations
 
-import contextlib
 from typing import TYPE_CHECKING
 
 import polars as pl
@@ -61,8 +60,9 @@ class PortfolioTurnoverMixin:
         cols.append(daily_abs_chg)
         result = self.cashposition.select(cols)
 
-        with contextlib.suppress(AttributeError, TypeError):
-            object.__setattr__(self, "_turnover_cache", result)
+        # Direct write is safe: Portfolio is a frozen, slotted dataclass that
+        # declares every cache field, so object.__setattr__ cannot fail here.
+        object.__setattr__(self, "_turnover_cache", result)
         return result
 
     @property

jquantstats-0.9.4/src/jquantstats/_protocol.py

@@ -0,0 +1,75 @@
+"""Shared protocol definitions used across jquantstats subpackages.
+
+Design rationale
+----------------
+The analytics subpackages (``_stats``, ``_plots``, ``_reports``, ``_utils``)
+must not import the concrete `Data` / `Portfolio` classes at runtime — that
+would create circular imports, since those classes compose the subpackages.
+Instead, each consumer annotates against a structural Protocol:
+
+- `DataLike` and `StatsLike` (this module) are shared by every subpackage —
+  there is exactly one definition of each.
+- ``PortfolioLike`` is deliberately *not* shared: each subpackage declares its
+  own (``_plots/_protocol.py``, ``_reports/_protocol.py``,
+  ``_utils/_protocol.py``) listing only the members it actually consumes
+  (interface segregation). Keep it that way — a merged PortfolioLike would
+  re-couple the subpackages to the full Portfolio surface.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import Protocol, runtime_checkable
+
+import polars as pl
+
+
+class StatsLike(Protocol):  # pragma: no cover
+    """Structural interface for the statistics facade used by reports."""
+
+    def summary(self) -> pl.DataFrame:
+        """Full summary DataFrame (one row per metric, one column per asset)."""
+        ...
+
+
+@runtime_checkable
+class DataLike(Protocol):  # pragma: no cover
+    """Authoritative structural interface for Data consumers.
+
+    Union of the members required by the stats mixins, plots, reports, and
+    utils — annotating against the superset is harmless for consumers that
+    use only part of it, and keeps a single definition.
+    """
+
+    returns: pl.DataFrame
+    index: pl.DataFrame
+    benchmark: pl.DataFrame | None
+
+    @property
+    def all(self) -> pl.DataFrame:
+        """Combined DataFrame of date index, return, and benchmark columns."""
+        ...
+
+    @property
+    def assets(self) -> list[str]:
+        """Names of the asset return columns."""
+        ...
+
+    @property
+    def date_col(self) -> list[str]:
+        """Column names used as the date/time index."""
+        ...
+
+    @property
+    def stats(self) -> StatsLike:
+        """Statistics facade used by reports."""
+        ...
+
+    @property
+    def _periods_per_year(self) -> float:
+        """Estimated number of return periods per calendar year."""
+        ...
+
+    def items(self) -> Iterator[tuple[str, pl.Series]]:
+        """Iterate over (asset_name, returns_series) pairs."""
+        ...