Skip to main content

FinFlow Sankey

PyPI version Python Docs

Polars-first financial statement Sankey visualization library.

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"],
})

FinancialSankey.income_statement(df, period="FY2025", currency="USD").validate().export_html(
    "income_statement.html", title="FY2025 Income Statement"
)

Installation

pip install finflow-sankey

Requires Python 3.9 or later.

Features

  • Polars-first: Native pl.DataFrame / pl.LazyFrame support. No pandas required.
  • 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.
  • Reference layout (opt-in): Detailed account nodes with fixed layout for presentations.
  • HTML export: One-line export helper.
  • Multi-period comparison: Compare two periods in a single Sankey.

Input Format

Your DataFrame must contain these columns:

Column Type Description
account str Account name shown on nodes.
value float Signed numeric value. Expenses are typically negative.
period str Period label (e.g. FY2025, 2024-12-31).
currency str Currency label (e.g. USD, KRW tn).
statement str One of income_statement, cash_flow_statement, balance_sheet.
section str Standard section. See table below.

Supported Sections

Statement Sections
Income statement revenue, cost_of_revenue, cost, expense, operating_expenses, tax, non_operating_items, profit
Cash flow beginning_cash, operating_cash_flow, investing_cash_flow, financing_cash_flow, fx_effect, ending_cash
Balance sheet asset, current_asset, non_current_asset, liability, current_liability, non_current_liability, equity

Quick Examples

Income Statement

fig = FinancialSankey.income_statement(df, period="FY2025", currency="USD").validate().render(
    title="FY2025 Income Statement"
)
fig.show()

Reference Layout (Detailed View)

fig = FinancialSankey.income_statement(df, layout="reference").validate().render(
    title="Detailed Income Statement"
)

Cash Flow Statement

fig = FinancialSankey.cash_flow_statement(df_cf, period="FY2025", currency="USD").validate().render(
    title="Cash Flow Bridge"
)

Balance Sheet Reconciliation

fig = FinancialSankey.balance_sheet_reconciliation(df_bs, as_of="2025-12-31", currency="USD").validate().render(
    title="Balance Sheet"
)

Multi-Period Comparison

fig = FinancialSankey.multi_period_compare(df_multi, currency="USD").validate().render(
    title="YoY Comparison"
)

Themes & Palettes

# Built-in theme
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"}
)

Account Mapping

Map raw account names to standard sections when your data uses different labels:

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()

HTML Export

FinancialSankey.income_statement(df).validate().export_html(
    "income_statement.html", title="FY2025 Income Statement"
)

Data Adapters

CSV

from finflow_sankey.adapters import load_income_statement_csv

df = load_income_statement_csv("data.csv", period="FY2025", currency="USD")
FinancialSankey.income_statement(df).validate().render()

Excel

from finflow_sankey.adapters import load_income_statement_excel

df = load_income_statement_excel("data.xlsx", sheet_name="IS", period="FY2025", currency="USD")
FinancialSankey.income_statement(df).validate().render()

Dartlab CLI

from finflow_sankey.adapters import DartlabAdapter

adapter = DartlabAdapter("005930")
df = adapter.load_income_statement()
FinancialSankey.income_statement(df).validate().render()

DART OpenAPI (dart-fss)

from finflow_sankey.adapters.dart_fss import DartFssAdapter

adapter = DartFssAdapter(corp_code="00126380")
df = adapter.load_income_statement()
FinancialSankey.income_statement(df).validate().render()

Requires DART_API_KEY environment variable and pip install dart-fss.

Real-World Data

See examples/dartlab_integration.py for fetching live Samsung Electronics data via Dartlab CLI.

Documentation

Full documentation is available at https://min9lin9.github.io/finflow-sankey/.

Roadmap

See ROADMAP.md for planned features and the path to v1.0.

Community

Development

cd finflow-sankey
pip install -e ".[dev,docs]"
python -m pytest tests/ -q
ruff check finflow_sankey tests
mkdocs build

Project Structure

finflow-sankey/
  finflow_sankey/  # package source
  tests/           # pytest suite
  docs/            # mkdocs documentation
  examples/        # usage examples

License

MIT

Metadata

Release files for finflow-sankey 0.3.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for finflow-sankey 0.3.1
File Size Uploaded Provenance Actions
finflow_sankey-0.3.1.tar.gz 35.9 kB With provenance Details for finflow_sankey-0.3.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for finflow-sankey 0.3.1
File Interpreter ABI Platform Actions
finflow_sankey-0.3.1-py3-none-any.whl Python 3 none any Details for finflow_sankey-0.3.1-py3-none-any.whl

Total release size: 80.6 kB

Release files / finflow_sankey-0.3.1.tar.gz

Download URL finflow_sankey-0.3.1.tar.gz
Size 35.9 kB
Tags Source
SHA-256 checksum
How to use checksums
34a067e91749bd7294539533cec7217034072bda79dfe7eff1a47f68c4abd46a
BLAKE2b-256 checksum
How to use checksums
4a613f04bd58dbd149c0fc6cb00d2ee62667713b84d00b9e79ca77b1288819fa
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jun 18, 2026.

Transparency log

Release files / finflow_sankey-0.3.1-py3-none-any.whl

Download URL finflow_sankey-0.3.1-py3-none-any.whl
Size 44.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
eda7dfe535aae6110ade4fa90f8a5d00b9eca30f7260f380fd64bc053c687ef1
BLAKE2b-256 checksum
How to use checksums
d4bff08306f47cc02c4d0acac89329901ab59d5e093f0f189c67d55877556cef
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jun 18, 2026.

Transparency log

Security for finflow-sankey 0.3.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for finflow_sankey-0.3.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jun 18, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page