finflow-sankey 0.1.10__tar.gz

finflow_sankey-0.1.10/PKG-INFO

@@ -0,0 +1,239 @@
+Metadata-Version: 2.4
+Name: finflow-sankey
+Version: 0.1.10
+Summary: Polars-first financial statement Sankey visualization library
+Author: FinFlow Team
+License: MIT
+Project-URL: Homepage, https://github.com/finflow/finflow-sankey
+Project-URL: Repository, https://github.com/finflow/finflow-sankey
+Keywords: sankey,finance,visualization,polars,plotly
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: polars>=0.20.0
+Requires-Dist: plotly>=5.18.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.5; extra == "docs"
+Requires-Dist: mkdocs-material>=9.0; extra == "docs"
+
+# FinFlow Sankey
+
+Polars-first financial statement Sankey visualization library.
+
+## Features
+
+- **Polars-first**: Native support for `pl.DataFrame` and `pl.LazyFrame`
+- **Accounting-aware validation**: Period/currency checks, reconciliation validation
+- **Role-based color palette**: Revenue, costs, profit, cash flow each have distinct colors
+- **Customizable themes**: default, monochrome, colorblind-safe, minimal, dark, plus custom YAML palettes
+- **Runtime palette override**: Change colors via dict or YAML without modifying source
+- **Account mapping**: Map raw account names to standard sections via dict or YAML
+- **Consistent line styles**: Link widths proportional to values, but stroke widths uniform
+- **Node layout**: Level-based horizontal positioning, including reconciliation side-by-side view
+- **Rich hover metadata**: Original accounts, validation status, period, currency
+- **HTML export**: One-line export helper
+- **Multi-period comparison**: Compare two periods in a single Sankey
+- **Plotly renderer**: Returns `plotly.graph_objects.Figure` for Jupyter, Streamlit, Dash, HTML export
+
+## Quickstart
+
+```python
+import polars as pl
+from finflow_sankey import FinancialSankey
+
+df = pl.DataFrame({
+    "account": ["Revenue", "Cost of Revenue", "Operating Expenses", "Tax", "Net Income"],
+    "value": [100_000_000.0, -40_000_000.0, -30_000_000.0, -10_000_000.0, 20_000_000.0],
+    "period": ["FY2025"] * 5,
+    "currency": ["USD"] * 5,
+    "statement": ["income_statement"] * 5,
+    "section": ["revenue", "cost_of_revenue", "operating_expenses", "tax", "profit"],
+})
+
+fig = (
+    FinancialSankey
+    .income_statement(df, period="FY2025", currency="USD")
+    .validate()
+    .render(title="FY2025 Income Statement Flow")
+)
+
+fig.show()
+```
+
+### Cash Flow Statement
+
+```python
+df = pl.DataFrame({
+    "account": [
+        "Beginning Cash",
+        "Operating Cash Flow",
+        "Investing Cash Flow",
+        "Financing Cash Flow",
+        "FX Effect",
+        "Ending Cash",
+    ],
+    "value": [50_000_000.0, 25_000_000.0, -10_000_000.0, -5_000_000.0, 2_000_000.0, 62_000_000.0],
+    "period": ["FY2025"] * 6,
+    "currency": ["USD"] * 6,
+    "statement": ["cash_flow_statement"] * 6,
+    "section": [
+        "beginning_cash",
+        "operating_cash_flow",
+        "investing_cash_flow",
+        "financing_cash_flow",
+        "fx_effect",
+        "ending_cash",
+    ],
+})
+
+fig = (
+    FinancialSankey
+    .cash_flow_statement(df, period="FY2025", currency="USD")
+    .validate()
+    .render(title="FY2025 Cash Flow Bridge")
+)
+```
+
+### Balance Sheet Reconciliation
+
+```python
+df = pl.DataFrame({
+    "account": [
+        "Current Assets",
+        "Non-current Assets",
+        "Current Liabilities",
+        "Non-current Liabilities",
+        "Equity",
+    ],
+    "value": [60_000_000.0, 40_000_000.0, 30_000_000.0, 20_000_000.0, 50_000_000.0],
+    "period": ["2025-12-31"] * 5,
+    "currency": ["USD"] * 5,
+    "statement": ["balance_sheet"] * 5,
+    "section": [
+        "current_asset",
+        "non_current_asset",
+        "current_liability",
+        "non_current_liability",
+        "equity",
+    ],
+})
+
+fig = (
+    FinancialSankey
+    .balance_sheet_reconciliation(df, as_of="2025-12-31", currency="USD")
+    .validate()
+    .render(title="Balance Sheet Reconciliation")
+)
+```
+
+### Multi-Period Comparison
+
+```python
+df = pl.DataFrame({
+    "account": ["Revenue", "Revenue", "Operating Expenses", "Operating Expenses"],
+    "value": [100_000_000.0, 120_000_000.0, -40_000_000.0, -50_000_000.0],
+    "period": ["FY2024", "FY2025", "FY2024", "FY2025"],
+    "currency": ["USD"] * 4,
+    "statement": ["income_statement"] * 4,
+    "section": ["revenue", "revenue", "expense", "expense"],
+})
+
+fig = (
+    FinancialSankey
+    .multi_period_compare(df, currency="USD")
+    .validate()
+    .render(title="FY2024 vs FY2025")
+)
+```
+
+## Account Mapping
+
+Map raw account names to standard sections via dict or YAML:
+
+```python
+mapping = {
+    "revenue": ["Net Sales", "Sales Revenue"],
+    "cost_of_revenue": ["COGS", "Cost of Goods Sold"],
+    "operating_expenses": ["SG&A", "R&D"],
+    "tax": ["Income Tax Expense"],
+    "profit": ["Net Income"],
+}
+
+fig = FinancialSankey.income_statement(df, mapping=mapping).validate().render()
+```
+
+## Themes & Palettes
+
+```python
+# Built-in theme
+fig = FinancialSankey.income_statement(df).validate().render(theme="colorblind_safe")
+
+# Dark mode
+fig = FinancialSankey.income_statement(df).validate().render(theme="dark")
+
+# Custom YAML palette
+fig = FinancialSankey.income_statement(df).validate().render(palette="./my_palette.yaml")
+
+# Runtime dict override
+fig = FinancialSankey.income_statement(df).validate().render(
+    palette={"revenue": "#0055FF", "profit": "#00AA55"}
+)
+```
+
+## HTML Export
+
+```python
+(
+    FinancialSankey
+    .income_statement(df)
+    .validate()
+    .export_html("income_statement.html", title="FY2025 Income Statement")
+)
+```
+
+## Installation
+
+```bash
+pip install finflow-sankey
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Development
+
+```bash
+python -m pytest tests/ -v
+ruff check finflow_sankey tests
+```
+
+## Project Structure
+
+```
+finflow_sankey/
+  core/           # schema, validation, normalization, graph, palette, mapper
+  templates/      # income_statement, cash_flow, balance_sheet, multi_period
+  renderers/      # plotly renderer
+  palettes/       # YAML color palettes
+  mappings/       # YAML account mappings
+  examples/       # usage examples
+tests/            # pytest suite
+```
+
+## License
+
+MIT

finflow_sankey-0.1.10/README.md

@@ -0,0 +1,210 @@
+# FinFlow Sankey
+
+Polars-first financial statement Sankey visualization library.
+
+## Features
+
+- **Polars-first**: Native support for `pl.DataFrame` and `pl.LazyFrame`
+- **Accounting-aware validation**: Period/currency checks, reconciliation validation
+- **Role-based color palette**: Revenue, costs, profit, cash flow each have distinct colors
+- **Customizable themes**: default, monochrome, colorblind-safe, minimal, dark, plus custom YAML palettes
+- **Runtime palette override**: Change colors via dict or YAML without modifying source
+- **Account mapping**: Map raw account names to standard sections via dict or YAML
+- **Consistent line styles**: Link widths proportional to values, but stroke widths uniform
+- **Node layout**: Level-based horizontal positioning, including reconciliation side-by-side view
+- **Rich hover metadata**: Original accounts, validation status, period, currency
+- **HTML export**: One-line export helper
+- **Multi-period comparison**: Compare two periods in a single Sankey
+- **Plotly renderer**: Returns `plotly.graph_objects.Figure` for Jupyter, Streamlit, Dash, HTML export
+
+## Quickstart
+
+```python
+import polars as pl
+from finflow_sankey import FinancialSankey
+
+df = pl.DataFrame({
+    "account": ["Revenue", "Cost of Revenue", "Operating Expenses", "Tax", "Net Income"],
+    "value": [100_000_000.0, -40_000_000.0, -30_000_000.0, -10_000_000.0, 20_000_000.0],
+    "period": ["FY2025"] * 5,
+    "currency": ["USD"] * 5,
+    "statement": ["income_statement"] * 5,
+    "section": ["revenue", "cost_of_revenue", "operating_expenses", "tax", "profit"],
+})
+
+fig = (
+    FinancialSankey
+    .income_statement(df, period="FY2025", currency="USD")
+    .validate()
+    .render(title="FY2025 Income Statement Flow")
+)
+
+fig.show()
+```
+
+### Cash Flow Statement
+
+```python
+df = pl.DataFrame({
+    "account": [
+        "Beginning Cash",
+        "Operating Cash Flow",
+        "Investing Cash Flow",
+        "Financing Cash Flow",
+        "FX Effect",
+        "Ending Cash",
+    ],
+    "value": [50_000_000.0, 25_000_000.0, -10_000_000.0, -5_000_000.0, 2_000_000.0, 62_000_000.0],
+    "period": ["FY2025"] * 6,
+    "currency": ["USD"] * 6,
+    "statement": ["cash_flow_statement"] * 6,
+    "section": [
+        "beginning_cash",
+        "operating_cash_flow",
+        "investing_cash_flow",
+        "financing_cash_flow",
+        "fx_effect",
+        "ending_cash",
+    ],
+})
+
+fig = (
+    FinancialSankey
+    .cash_flow_statement(df, period="FY2025", currency="USD")
+    .validate()
+    .render(title="FY2025 Cash Flow Bridge")
+)
+```
+
+### Balance Sheet Reconciliation
+
+```python
+df = pl.DataFrame({
+    "account": [
+        "Current Assets",
+        "Non-current Assets",
+        "Current Liabilities",
+        "Non-current Liabilities",
+        "Equity",
+    ],
+    "value": [60_000_000.0, 40_000_000.0, 30_000_000.0, 20_000_000.0, 50_000_000.0],
+    "period": ["2025-12-31"] * 5,
+    "currency": ["USD"] * 5,
+    "statement": ["balance_sheet"] * 5,
+    "section": [
+        "current_asset",
+        "non_current_asset",
+        "current_liability",
+        "non_current_liability",
+        "equity",
+    ],
+})
+
+fig = (
+    FinancialSankey
+    .balance_sheet_reconciliation(df, as_of="2025-12-31", currency="USD")
+    .validate()
+    .render(title="Balance Sheet Reconciliation")
+)
+```
+
+### Multi-Period Comparison
+
+```python
+df = pl.DataFrame({
+    "account": ["Revenue", "Revenue", "Operating Expenses", "Operating Expenses"],
+    "value": [100_000_000.0, 120_000_000.0, -40_000_000.0, -50_000_000.0],
+    "period": ["FY2024", "FY2025", "FY2024", "FY2025"],
+    "currency": ["USD"] * 4,
+    "statement": ["income_statement"] * 4,
+    "section": ["revenue", "revenue", "expense", "expense"],
+})
+
+fig = (
+    FinancialSankey
+    .multi_period_compare(df, currency="USD")
+    .validate()
+    .render(title="FY2024 vs FY2025")
+)
+```
+
+## Account Mapping
+
+Map raw account names to standard sections via dict or YAML:
+
+```python
+mapping = {
+    "revenue": ["Net Sales", "Sales Revenue"],
+    "cost_of_revenue": ["COGS", "Cost of Goods Sold"],
+    "operating_expenses": ["SG&A", "R&D"],
+    "tax": ["Income Tax Expense"],
+    "profit": ["Net Income"],
+}
+
+fig = FinancialSankey.income_statement(df, mapping=mapping).validate().render()
+```
+
+## Themes & Palettes
+
+```python
+# Built-in theme
+fig = FinancialSankey.income_statement(df).validate().render(theme="colorblind_safe")
+
+# Dark mode
+fig = FinancialSankey.income_statement(df).validate().render(theme="dark")
+
+# Custom YAML palette
+fig = FinancialSankey.income_statement(df).validate().render(palette="./my_palette.yaml")
+
+# Runtime dict override
+fig = FinancialSankey.income_statement(df).validate().render(
+    palette={"revenue": "#0055FF", "profit": "#00AA55"}
+)
+```
+
+## HTML Export
+
+```python
+(
+    FinancialSankey
+    .income_statement(df)
+    .validate()
+    .export_html("income_statement.html", title="FY2025 Income Statement")
+)
+```
+
+## Installation
+
+```bash
+pip install finflow-sankey
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Development
+
+```bash
+python -m pytest tests/ -v
+ruff check finflow_sankey tests
+```
+
+## Project Structure
+
+```
+finflow_sankey/
+  core/           # schema, validation, normalization, graph, palette, mapper
+  templates/      # income_statement, cash_flow, balance_sheet, multi_period
+  renderers/      # plotly renderer
+  palettes/       # YAML color palettes
+  mappings/       # YAML account mappings
+  examples/       # usage examples
+tests/            # pytest suite
+```
+
+## License
+
+MIT

finflow_sankey-0.1.10/finflow_sankey/__init__.py

@@ -0,0 +1,100 @@
+"""FinFlow Sankey: Polars-first financial statement Sankey visualization."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import polars as pl
+
+from finflow_sankey.core.mapper import AccountMapper
+from finflow_sankey.core.pipeline import SankeyPipeline
+from finflow_sankey.templates.income_statement import IncomeStatementTemplate
+
+
+class FinancialSankey:
+    """Main entry point for FinFlow Sankey."""
+
+    @classmethod
+    def income_statement(
+        cls,
+        data: pl.DataFrame | pl.LazyFrame,
+        *,
+        period: str | None = None,
+        currency: str | None = None,
+        mapping: AccountMapper | dict[str, Any] | str | Path | None = None,
+    ) -> SankeyPipeline:
+        """Create an income statement Sankey pipeline."""
+        template = IncomeStatementTemplate()
+        return SankeyPipeline(
+            data=data,
+            template=template,
+            period=period,
+            currency=currency,
+            mapping=mapping,
+        )
+
+    @classmethod
+    def cash_flow_statement(
+        cls,
+        data: pl.DataFrame | pl.LazyFrame,
+        *,
+        period: str | None = None,
+        currency: str | None = None,
+        mapping: AccountMapper | dict[str, Any] | str | Path | None = None,
+    ) -> SankeyPipeline:
+        """Create a cash flow statement Sankey pipeline."""
+        from finflow_sankey.templates.cash_flow import CashFlowStatementTemplate
+
+        template = CashFlowStatementTemplate()
+        return SankeyPipeline(
+            data=data,
+            template=template,
+            period=period,
+            currency=currency,
+            mapping=mapping,
+        )
+
+    @classmethod
+    def balance_sheet_reconciliation(
+        cls,
+        data: pl.DataFrame | pl.LazyFrame,
+        *,
+        as_of: str | None = None,
+        currency: str | None = None,
+        mapping: AccountMapper | dict[str, Any] | str | Path | None = None,
+    ) -> SankeyPipeline:
+        """Create a balance sheet reconciliation Sankey pipeline."""
+        from finflow_sankey.templates.balance_sheet import BalanceSheetReconciliationTemplate
+
+        template = BalanceSheetReconciliationTemplate()
+        return SankeyPipeline(
+            data=data,
+            template=template,
+            period=as_of,
+            currency=currency,
+            mapping=mapping,
+        )
+
+    @classmethod
+    def multi_period_compare(
+        cls,
+        data: pl.DataFrame | pl.LazyFrame,
+        *,
+        currency: str | None = None,
+        mapping: AccountMapper | dict[str, Any] | str | Path | None = None,
+    ) -> SankeyPipeline:
+        """Create a multi-period comparison Sankey pipeline."""
+        from finflow_sankey.templates.multi_period import MultiPeriodComparisonTemplate
+
+        template = MultiPeriodComparisonTemplate()
+        return SankeyPipeline(
+            data=data,
+            template=template,
+            period=None,
+            currency=currency,
+            mapping=mapping,
+        )
+
+
+__all__ = ["FinancialSankey", "SankeyPipeline"]

finflow_sankey-0.1.10/finflow_sankey/core/__init__.py

@@ -0,0 +1 @@
+"""Core modules for FinFlow Sankey."""

finflow_sankey-0.1.10/finflow_sankey/core/exceptions.py

@@ -0,0 +1,107 @@
+"""FinFlow Sankey custom exceptions."""
+
+from __future__ import annotations
+
+
+class FinFlowError(Exception):
+    """Base exception for FinFlow Sankey."""
+
+    pass
+
+
+class SchemaError(FinFlowError):
+    """Raised when input schema is invalid."""
+
+    pass
+
+
+class MissingColumnError(SchemaError):
+    """Raised when a required column is missing."""
+
+    def __init__(self, column: str):
+        self.column = column
+        super().__init__(f"Required column '{column}' is missing from input data.")
+
+
+class PeriodMismatchError(FinFlowError):
+    """Raised when multiple periods are detected."""
+
+    pass
+
+
+class CurrencyMismatchError(FinFlowError):
+    """Raised when multiple currencies are detected."""
+
+    pass
+
+
+class MissingAccountError(FinFlowError):
+    """Raised when a required account role is missing."""
+
+    def __init__(self, role: str, statement: str, available: list[str] | None = None):
+        self.role = role
+        self.statement = statement
+        self.available = available or []
+        msg = f"Required role '{role}' is missing for statement '{statement}'."
+        if self.available:
+            msg += f" Available accounts: {', '.join(self.available)}"
+        super().__init__(msg)
+
+
+class ReconciliationError(FinFlowError):
+    """Raised when financial reconciliation fails."""
+
+    def __init__(
+        self,
+        rule: str,
+        expected: float,
+        actual: float,
+        difference: float,
+        period: str | None = None,
+        currency: str | None = None,
+        tolerance: float = 0.01,
+    ):
+        self.rule = rule
+        self.expected = expected
+        self.actual = actual
+        self.difference = difference
+        self.period = period
+        self.currency = currency
+        self.tolerance = tolerance
+        super().__init__(
+            f"Reconciliation failed: {rule}\n"
+            f"  Expected: {expected:,.2f}\n"
+            f"  Actual:   {actual:,.2f}\n"
+            f"  Difference: {difference:,.2f}\n"
+            f"  Tolerance: {tolerance}"
+        )
+
+
+class NullValueError(FinFlowError):
+    """Raised when null values are found in required fields."""
+
+    pass
+
+
+class DuplicateAccountError(FinFlowError):
+    """Raised when duplicate accounts are detected."""
+
+    pass
+
+
+class InvalidColorError(FinFlowError):
+    """Raised when an invalid color is provided."""
+
+    pass
+
+
+class MissingRoleColorError(FinFlowError):
+    """Raised when a required role color is missing from palette."""
+
+    pass
+
+
+class InvalidOpacityError(FinFlowError):
+    """Raised when opacity is out of valid range."""
+
+    pass