portpy-quant 0.1.0__tar.gz

portpy_quant-0.1.0/.env.example

@@ -0,0 +1,3 @@
+ALPACA_ENDPOINT=https://paper-api.alpaca.markets/v2
+ALPACA_KEY=your_alpaca_api_key_id
+ALPACA_SECRET=your_alpaca_api_secret_key

portpy_quant-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,54 @@
+name: CI
+
+# If a commit introduces a bug, breaks a Python version, # or violates formatting 
+# rules, GitHub marks the commit.
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install portpy with dev extras
+        run: pip install -e ".[dev]"
+
+      - name: Lint
+        run: ruff check src tests
+
+      - name: Type check
+        run: mypy src/portpy
+
+      - name: Run tests (excluding network-dependent tests)
+        run: pytest -q -m "not network" --cov=portpy --cov-report=term-missing
+
+  build:
+    runs-on: ubuntu-latest
+    needs: test
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install build tool
+        run: pip install build
+      - name: Build sdist and wheel
+        run: python -m build
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/

portpy_quant-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,50 @@
+name: Docs
+
+# Builds and publishes the mkdocs site to GitHub Pages on every push to main.
+# Requires GitHub Pages to be enabled for this repo with source = GitHub Actions
+# (Settings -> Pages -> Build and deployment -> Source). --- Already DONE
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - "src/**"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install portpy with dev extras
+        run: pip install -e ".[dev]"
+      - name: Build site
+        run: mkdocs build --strict
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

portpy_quant-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,28 @@
+name: Publish to PyPI
+
+# Only runs when a version tag (e.g. v1.0.0) is pushed, never on normal commits.
+# Requires a PYPI_API_TOKEN secret to be configured in the repository settings.
+
+on:
+  workflow_dispatch:
+  push:
+    tags:
+      - "v*.*.*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install build tool
+        run: pip install build twine
+      - name: Build sdist and wheel
+        run: python -m build
+      - name: Publish to PyPI
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+        run: twine upload dist/*

portpy_quant-0.1.0/.gitignore

@@ -0,0 +1,63 @@
+# Environment variables
+.env
+.env.*
+!.env.example
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+venv/
+.venv/
+ENV/
+env/
+
+# Testing, coverage, linting
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+
+# Jupyter
+.ipynb_checkpoints/
+
+# Docs build
+/site/
+
+# Personal working notes
+/planning.md
+/debug.ipynb
+
+# Example outputs
+examples/output/
+
+# IDE, Editor
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS specific
+.DS_Store
+Thumbs.db

portpy_quant-0.1.0/CHANGELOG.md

@@ -0,0 +1,50 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Pre-Release] - 2026-08-04
+
+## [0.1.0] - 2026-08-04
+
+First release. Metrics and core are implemented and tested; visualization, models, and
+strategies are designed but not yet built — see [docs/roadmap.md](https://github.com/Arthur-Faugeron/PortPy/blob/main/docs/roadmap.md).
+
+### Added
+
+- **`Portfolio`**: the single entry point over price/return data — weights (negative/short
+  positions supported), asset-class tags, and a `.metrics` namespace that auto-fills
+  `returns`/`prices`/`weights`/`rf`/`periods_per_year` from the portfolio's own state on
+  keyword-only calls.
+- **`portpy.metrics`**: `returns`, `risk`, `performance`, `drawdowns`, `rolling`, 
+  `distributions`, `benchmarks` (alpha/beta/capture ratios), `regressions` 
+  (OLS via statsmodels), `covariance`(portfolio-level risk decomposition: variance, 
+  diversification ratio, marginal/component contribution to risk), one-shot 
+  `summary` tables, and transaction-`costs` helpers. Most scalar metrics accept 
+  `as_result=True` to get a self-explaining `MetricResult` back.
+- **`portpy.core`**: `calendars` for combining assets that trade on different calendars 
+  (e.g. 24/7 crypto with Mon-Fri equities); `currency` for multi-currency portfolios; 
+  `weights` for weight validation (including long/short books); and `asset` to represent
+  individual assets.
+- **`portpy.explain`**: the explainability layer — `Explanation` knowledge cards registered
+  per metric (what it is, formula, how to read it, good vs. bad, caveats, a value-specific
+  verdict), `MetricResult` (a `float` subclass carrying its own name/unit/interpretation),
+  and `portpy.explain(name_or_result)` as the single dispatch point.
+- **Examples**: `01_yfinance_getting_started.py`, `02_alpaca_multiasset_calendar.py`, and
+  `tutorial.ipynb` — a full walkthrough of every metric function against three real
+  long/short, multi-asset portfolios built from live Alpaca (stocks/ETFs/crypto) and FRED
+  (risk-free rate) data.
+- **Tests**: unit coverage for every metric module, core of portpy, plus
+  `tests/validation/test_vs_empyrical_quantstats.py`, cross-checking PortPy's numbers
+  against `empyrical` and `quantstats` on synthetic and real (yfinance) market data.
+- **Docs**: a full guide + API reference site (`mkdocs` + `mkdocstrings`) covering the
+  `Portfolio` object, weights/shorts, calendar & currency alignment, the explainability
+  layer, and every function's API docs.
+- Project scaffolding: `pyproject.toml`, `src/` layout, CI (lint/type-check/test/build) and
+  PyPI-publish GitHub Actions workflows, MIT license.
+
+### Known limitations
+
+- `portpy.visualization`, `portpy.models`, and `portpy.strategies` are designed (see
+  [docs/architecture.md](https://github.com/Arthur-Faugeron/PortPy/blob/main/docs/architecture.md)) but not implemented in this release.

portpy_quant-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arthur Lino Faugeron Jacono
+
+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.

portpy_quant-0.1.0/PKG-INFO

@@ -0,0 +1,190 @@
+Metadata-Version: 2.4
+Name: portpy-quant
+Version: 0.1.0
+Summary: Portfolio analysis, optimization, and management with built-in, human-readable explanations of every metric, chart, model, and strategy.
+Project-URL: Homepage, https://github.com/Arthur-Faugeron/PortPy
+Project-URL: Documentation, https://Arthur-Faugeron.github.io/PortPy/
+Project-URL: Repository, https://github.com/Arthur-Faugeron/PortPy
+Project-URL: Issues, https://github.com/Arthur-Faugeron/PortPy/issues
+Project-URL: Changelog, https://github.com/Arthur-Faugeron/PortPy/blob/main/CHANGELOG.md
+Author-email: Arthur Lino Faugeron Jacono <faugeronarthur@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Arthur Lino Faugeron Jacono
+        
+        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.
+License-File: LICENSE
+Keywords: backtesting,finance,optimization,portfolio,quant,risk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=2.0
+Requires-Dist: scipy>=1.10
+Requires-Dist: statsmodels>=0.14
+Provides-Extra: all
+Requires-Dist: alpaca-py>=0.30; extra == 'all'
+Requires-Dist: arch>=6.3; extra == 'all'
+Requires-Dist: hmmlearn>=0.3.2; extra == 'all'
+Requires-Dist: kaleido>=0.2.1; extra == 'all'
+Requires-Dist: matplotlib>=3.7; extra == 'all'
+Requires-Dist: plotly>=5.18; extra == 'all'
+Requires-Dist: python-dotenv>=1.0; extra == 'all'
+Requires-Dist: scikit-learn>=1.3; extra == 'all'
+Requires-Dist: seaborn>=0.13; extra == 'all'
+Requires-Dist: yfinance>=0.2.40; extra == 'all'
+Provides-Extra: data
+Requires-Dist: alpaca-py>=0.30; extra == 'data'
+Requires-Dist: python-dotenv>=1.0; extra == 'data'
+Requires-Dist: yfinance>=0.2.40; extra == 'data'
+Provides-Extra: dev
+Requires-Dist: alpaca-py>=0.30; extra == 'dev'
+Requires-Dist: arch>=6.3; extra == 'dev'
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: empyrical-reloaded>=0.5.7; extra == 'dev'
+Requires-Dist: hmmlearn>=0.3.2; extra == 'dev'
+Requires-Dist: jupyter>=1.0; extra == 'dev'
+Requires-Dist: kaleido>=0.2.1; extra == 'dev'
+Requires-Dist: matplotlib>=3.7; extra == 'dev'
+Requires-Dist: mkdocs-material>=9.5; extra == 'dev'
+Requires-Dist: mkdocs>=1.5; extra == 'dev'
+Requires-Dist: mkdocstrings[python]>=0.24; extra == 'dev'
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: nbformat>=5.9; extra == 'dev'
+Requires-Dist: plotly>=5.18; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1; extra == 'dev'
+Requires-Dist: pytest>=7.4; extra == 'dev'
+Requires-Dist: python-dotenv>=1.0; extra == 'dev'
+Requires-Dist: quantstats>=0.0.62; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: scikit-learn>=1.3; extra == 'dev'
+Requires-Dist: seaborn>=0.13; extra == 'dev'
+Requires-Dist: yfinance>=0.2.40; extra == 'dev'
+Provides-Extra: models
+Requires-Dist: arch>=6.3; extra == 'models'
+Requires-Dist: hmmlearn>=0.3.2; extra == 'models'
+Requires-Dist: scikit-learn>=1.3; extra == 'models'
+Provides-Extra: viz
+Requires-Dist: kaleido>=0.2.1; extra == 'viz'
+Requires-Dist: matplotlib>=3.7; extra == 'viz'
+Requires-Dist: plotly>=5.18; extra == 'viz'
+Requires-Dist: seaborn>=0.13; extra == 'viz'
+Description-Content-Type: text/markdown
+
+# PortPy
+
+**Portfolio analysis that explains itself.**
+
+PortPy is a Python library for portfolio performance measurement and risk analysis, built around one object — `Portfolio` — and one idea: every number it gives you can explain, in plain language, what it is, how to read it, and whether it's good or bad.
+
+[![CI](https://github.com/Arthur-Faugeron/PortPy/actions/workflows/ci.yml/badge.svg)](https://github.com/Arthur-Faugeron/PortPy/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](pyproject.toml)
+
+```python
+import pandas as pd
+from portpy import Portfolio
+
+prices = pd.read_csv("prices.csv", index_col=0, parse_dates=True)  # columns = tickers
+
+portfolio = Portfolio(
+    prices,
+    weights={"AAPL": 0.4, "MSFT": 0.35, "GOOGL": 0.25},
+    name="Tech Portfolio",
+    risk_free_rate=0.04,
+)
+
+portfolio.metrics.sharpe_ratio(as_result=True).explain()
+```
+
+```text
+sharpe_ratio (metric)
+=====================
+
+What it is:
+  The most widely used risk-adjusted return measure: excess return earned per unit of total volatility taken on.
+
+Formula:
+  mean(r - rf) / std(r - rf, ddof=1) * sqrt(periods_per_year)
+
+How to read it:
+  A Sharpe of 1.0 means you earned, on average, one standard deviation of excess return for the volatility you took on.
+
+Good vs. bad:
+  Rules of thumb: <0 poor (lost money net of the risk-free rate), 0-1 sub-par, 1-2 good, 2-3 very good, >3 excellent (and worth double-checking for overfitting or a very short sample).
+
+Caveats:
+  Assumes returns are roughly symmetric - it penalizes upside volatility just as much as downside, and can be misleadingly high for strategies with rare, large negative tail events (e.g. option-selling). Pair with sortino_ratio and max_drawdown.
+
+This result:
+  sub-par
+```
+
+## Why PortPy
+
+- **One object, one namespace.** `portfolio.metrics.<name>()` auto-fills returns, weights,
+  risk-free rate, and annualization frequency from the portfolio itself — no re-threading
+  the same five arguments through every call.
+- **A real portfolio, not just a return stream.** Weights (negative/short included), asset-class
+  tags, and explicit calendar-alignment / currency-conversion helpers for combining assets that
+  don't trade on the same schedule (crypto, equities, bonds) or in the same currency.
+- **Explains itself.** `.explain()` on any result — a plain-language card covering what it is,
+  how to read it, good vs. bad, and known caveats.
+- **Numerically validated.** Cross-checked against [`empyrical`](https://github.com/stefan-jansen/empyrical-reloaded)
+  and [`quantstats`](https://github.com/ranaroussi/quantstats) on real market data — see
+  `tests/validation/`.
+
+## Install
+
+```bash
+pip install portpy-quant               # core: numpy, pandas, scipy, statsmodels
+pip install "portpy-quant[viz]"        # + plotly, matplotlib, seaborn
+pip install "portpy-quant[data]"       # + yfinance, alpaca-py (for the examples)
+pip install "portpy-quant[all]"        # everything
+```
+
+## Documentation
+
+- [Getting Started](https://github.com/Arthur-Faugeron/PortPy/blob/main/docs/getting-started.md)
+- [User Guide](https://github.com/Arthur-Faugeron/PortPy/blob/main/docs/index.md) — the `Portfolio` object, weights & shorts, calendar/currency
+  alignment, the explainability layer
+- [API Reference](https://github.com/Arthur-Faugeron/PortPy/blob/main/docs/api/index.md) — every function, by module
+- [Roadmap](https://github.com/Arthur-Faugeron/PortPy/blob/main/docs/roadmap.md) — what's implemented today vs. planned (`models`, `strategies`,
+  `visualization` are not yet built)
+- [`examples/`](https://github.com/Arthur-Faugeron/PortPy/blob/main/examples/) — runnable scripts and a full tutorial notebook exercising every
+  metric against live Alpaca + Fed (FRED) data
+
+## Status
+
+PortPy is pre-1.0 (`Development Status :: 4 - Beta`). **Metrics and core** (calendar/currency
+alignment, weights, the explainability layer) are implemented and tested. **Visualization,
+models/optimization, and strategies/backtesting** are designed but not yet built — see the
+[Roadmap](https://github.com/Arthur-Faugeron/PortPy/blob/main/docs/roadmap.md).
+
+## License
+
+[MIT](LICENSE) © Arthur Faugeron

portpy_quant-0.1.0/README.md

@@ -0,0 +1,93 @@
+# PortPy
+
+**Portfolio analysis that explains itself.**
+
+PortPy is a Python library for portfolio performance measurement and risk analysis, built around one object — `Portfolio` — and one idea: every number it gives you can explain, in plain language, what it is, how to read it, and whether it's good or bad.
+
+[![CI](https://github.com/Arthur-Faugeron/PortPy/actions/workflows/ci.yml/badge.svg)](https://github.com/Arthur-Faugeron/PortPy/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](pyproject.toml)
+
+```python
+import pandas as pd
+from portpy import Portfolio
+
+prices = pd.read_csv("prices.csv", index_col=0, parse_dates=True)  # columns = tickers
+
+portfolio = Portfolio(
+    prices,
+    weights={"AAPL": 0.4, "MSFT": 0.35, "GOOGL": 0.25},
+    name="Tech Portfolio",
+    risk_free_rate=0.04,
+)
+
+portfolio.metrics.sharpe_ratio(as_result=True).explain()
+```
+
+```text
+sharpe_ratio (metric)
+=====================
+
+What it is:
+  The most widely used risk-adjusted return measure: excess return earned per unit of total volatility taken on.
+
+Formula:
+  mean(r - rf) / std(r - rf, ddof=1) * sqrt(periods_per_year)
+
+How to read it:
+  A Sharpe of 1.0 means you earned, on average, one standard deviation of excess return for the volatility you took on.
+
+Good vs. bad:
+  Rules of thumb: <0 poor (lost money net of the risk-free rate), 0-1 sub-par, 1-2 good, 2-3 very good, >3 excellent (and worth double-checking for overfitting or a very short sample).
+
+Caveats:
+  Assumes returns are roughly symmetric - it penalizes upside volatility just as much as downside, and can be misleadingly high for strategies with rare, large negative tail events (e.g. option-selling). Pair with sortino_ratio and max_drawdown.
+
+This result:
+  sub-par
+```
+
+## Why PortPy
+
+- **One object, one namespace.** `portfolio.metrics.<name>()` auto-fills returns, weights,
+  risk-free rate, and annualization frequency from the portfolio itself — no re-threading
+  the same five arguments through every call.
+- **A real portfolio, not just a return stream.** Weights (negative/short included), asset-class
+  tags, and explicit calendar-alignment / currency-conversion helpers for combining assets that
+  don't trade on the same schedule (crypto, equities, bonds) or in the same currency.
+- **Explains itself.** `.explain()` on any result — a plain-language card covering what it is,
+  how to read it, good vs. bad, and known caveats.
+- **Numerically validated.** Cross-checked against [`empyrical`](https://github.com/stefan-jansen/empyrical-reloaded)
+  and [`quantstats`](https://github.com/ranaroussi/quantstats) on real market data — see
+  `tests/validation/`.
+
+## Install
+
+```bash
+pip install portpy-quant               # core: numpy, pandas, scipy, statsmodels
+pip install "portpy-quant[viz]"        # + plotly, matplotlib, seaborn
+pip install "portpy-quant[data]"       # + yfinance, alpaca-py (for the examples)
+pip install "portpy-quant[all]"        # everything
+```
+
+## Documentation
+
+- [Getting Started](https://github.com/Arthur-Faugeron/PortPy/blob/main/docs/getting-started.md)
+- [User Guide](https://github.com/Arthur-Faugeron/PortPy/blob/main/docs/index.md) — the `Portfolio` object, weights & shorts, calendar/currency
+  alignment, the explainability layer
+- [API Reference](https://github.com/Arthur-Faugeron/PortPy/blob/main/docs/api/index.md) — every function, by module
+- [Roadmap](https://github.com/Arthur-Faugeron/PortPy/blob/main/docs/roadmap.md) — what's implemented today vs. planned (`models`, `strategies`,
+  `visualization` are not yet built)
+- [`examples/`](https://github.com/Arthur-Faugeron/PortPy/blob/main/examples/) — runnable scripts and a full tutorial notebook exercising every
+  metric against live Alpaca + Fed (FRED) data
+
+## Status
+
+PortPy is pre-1.0 (`Development Status :: 4 - Beta`). **Metrics and core** (calendar/currency
+alignment, weights, the explainability layer) are implemented and tested. **Visualization,
+models/optimization, and strategies/backtesting** are designed but not yet built — see the
+[Roadmap](https://github.com/Arthur-Faugeron/PortPy/blob/main/docs/roadmap.md).
+
+## License
+
+[MIT](LICENSE) © Arthur Faugeron

portpy_quant-0.1.0/docs/api/core.md

@@ -0,0 +1,33 @@
+# core
+
+Asset-class tagging, calendar alignment, currency conversion, and weight 
+normalization — all opt-in helpers you call before constructing a Portfolio. 
+See the
+[Calendars & currencies](https://github.com/Arthur-Faugeron/PortPy/blob/main/docs/guide/calendars-and-currency.md) 
+and
+[Weights & short positions](https://github.com/Arthur-Faugeron/PortPy/blob/main/docs/guide/weights.md) 
+guides for worked examples.
+
+## Asset tagging
+
+::: portpy.core.asset.AssetClass
+
+::: portpy.core.asset.ALWAYS_ON_CLASSES
+
+## Calendar alignment
+
+::: portpy.core.calendar.detect_frequency
+
+::: portpy.core.calendar.calendar_coverage_report
+
+::: portpy.core.calendar.align_calendars
+
+## Currency conversion
+
+::: portpy.core.currency.convert_to_base_currency
+
+## Weights
+
+::: portpy.core.weights.equal_weights
+
+::: portpy.core.weights.normalize_weights

portpy_quant-0.1.0/docs/api/explain.md

@@ -0,0 +1,25 @@
+# explain
+
+See 
+[Explainability](https://github.com/Arthur-Faugeron/PortPy/blob/main/docs/guide/explainability.md) 
+for how the pieces below fit together, and
+where the explanation text itself actually lives (hint: not in this module).
+
+!!! note
+
+from portpy import Portfolio (or any import of the portpy package) binds the package
+attribute portpy.explain to the function below, not this module. Import the other
+names (available, get, register, Explanation, MetricResult) directly from
+portpy.explain as shown in each signature.
+
+::: portpy.explain.Explanation
+
+::: portpy.explain.MetricResult
+
+::: portpy.explain.explain
+
+::: portpy.explain.register
+
+::: portpy.explain.get
+
+::: portpy.explain.available

portpy_quant-0.1.0/docs/api/index.md

@@ -0,0 +1,17 @@
+# API Reference
+
+Generated from docstrings. Every function also documents its own parameters, return type,
+and — where relevant — the exact formula it computes.
+
+| Submodule | Covers |
+|---|---|
+| [Portfolio](https://github.com/Arthur-Faugeron/PortPy/blob/main/docs/api/portfolio.md) | the main entry point. |
+| [core](https://github.com/Arthur-Faugeron/PortPy/blob/main/docs/api/core.md) | asset-class tagging, calendar alignment, currency conversion, weight
+  normalization. |
+| [explain](https://github.com/Arthur-Faugeron/PortPy/blob/main/docs/api/explain.md) | Explanation, MetricResult, and the explain() dispatcher. |
+| [metrics](https://github.com/Arthur-Faugeron/PortPy/blob/main/docs/api/metrics/index.md) | every metric function, grouped by submodule: returns,
+  risk, performance, drawdowns, rolling, distributions, benchmarks,
+  regressions, covariance, summary, costs.
+
+Not yet implemented (see the [Roadmap](https://github.com/Arthur-Faugeron/PortPy/blob/main/docs/roadmap.md)): portpy.visualization,
+portpy.models, portpy.strategies.

portpy_quant-0.1.0/docs/api/metrics/benchmarks.md

@@ -0,0 +1,15 @@
+# benchmarks
+
+Functions for comparing portfolio performance against a benchmark. These metrics
+measure active return, market sensitivity, and relative performance.
+
+::: portpy.metrics.benchmarks
+    options:
+      members:
+        - alpha
+        - correlation
+        - r_squared
+        - up_capture_ratio
+        - down_capture_ratio
+        - capture_ratio
+        - batting_average

portpy_quant-0.1.0/docs/api/metrics/costs.md

@@ -0,0 +1,11 @@
+# costs
+
+PortPy assumes frictionless trading by default. These helpers layer transaction costs back
+in, either from an explicit weight-history (real turnover) or an assumed constant per-period
+turnover.
+
+::: portpy.metrics.costs
+    options:
+      members:
+        - turnover_from_weights
+        - net_of_costs_returns