pyproforma 0.2.0__tar.gz → 0.2.1__tar.gz

{pyproforma-0.2.0/pyproforma.egg-info → pyproforma-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyproforma
-Version: 0.2.0
+Version: 0.2.1
 Summary: A Python package for financial modeling and reporting
 Author-email: Robert Hannay <rhannay@gmail.com>
 Maintainer-email: Robert Hannay <rhannay@gmail.com>
@@ -146,7 +146,6 @@ class FlexModel(ProformaModel):
     gross_profit = FormulaLine(formula=lambda li, t: li.revenue[t] - li.cogs[t])
 
 base = FlexModel(periods=[2024, 2025])
-# InputAssumption lets callers override at instantiation time — coming soon
 ```
 
 Use `ModelComparison` to diff two model instances:

{pyproforma-0.2.0 → pyproforma-0.2.1}/README.md

@@ -109,7 +109,6 @@ class FlexModel(ProformaModel):
     gross_profit = FormulaLine(formula=lambda li, t: li.revenue[t] - li.cogs[t])
 
 base = FlexModel(periods=[2024, 2025])
-# InputAssumption lets callers override at instantiation time — coming soon
 ```
 
 Use `ModelComparison` to diff two model instances:

{pyproforma-0.2.0 → pyproforma-0.2.1}/pyproforma/__init__.py

@@ -1,13 +1,21 @@
 """
-PyProforma v2 - Simplified modeling framework
-
-Version 2 provides a cleaner, Pydantic-inspired API for building financial models.
+PyProforma - A lightweight financial modeling framework.
 """
 
-from .assumption import Assumption
-from .assumption_result import AssumptionResult
-from .assumption_values import AssumptionValues
-from .input_assumption import InputAssumption
+from .charts.chart_def import ChartDef
+from .tables.table_def import TableDef
+from .tables.row_types import (
+    BlankRow,
+    CumulativeChangeRow,
+    CumulativePercentChangeRow,
+    HeaderRow,
+    ItemRow,
+    LabelRow,
+    LineItemsTotalRow,
+    PercentChangeRow,
+    TagItemsRow,
+    TagTotalRow,
+)
 from .line_items import (
     DebtCalculator,
     DebtInterestLine,
@@ -30,18 +38,26 @@ from .tags_namespace import ModelTagNamespace
 
 __all__ = [
     "ProformaModel",
+    "ChartDef",
+    "TableDef",
+    "HeaderRow",
+    "ItemRow",
+    "LabelRow",
+    "BlankRow",
+    "TagItemsRow",
+    "TagTotalRow",
+    "LineItemsTotalRow",
+    "PercentChangeRow",
+    "CumulativeChangeRow",
+    "CumulativePercentChangeRow",
     "FixedLine",
     "FormulaLine",
     "InputLine",
-    "InputAssumption",
     "DebtPrincipalLine",
     "DebtInterestLine",
     "DebtCalculator",
     "create_debt_lines",
-    "Assumption",
-    "AssumptionResult",
     "LineItem",
-    "AssumptionValues",
     "LineItemValues",
     "LineItemValue",
     "LineItemResult",

{pyproforma-0.2.0 → pyproforma-0.2.1}/pyproforma/calculation_engine.py

@@ -1,49 +1,32 @@
 """
-Calculation engine for v2 ProformaModel.
+Calculation engine for ProformaModel.
 
-This module contains the logic for calculating line item values from formulas,
-handling dependencies, and resolving values across periods.
+Calculates line item values from formulas, handling dependencies and resolving
+values across periods.
 """
 
 from typing import TYPE_CHECKING, Any
 
 if TYPE_CHECKING:
-    from .assumption_values import AssumptionValues
     from .line_items.line_item_values import LineItemValues
 
 
 def calculate_line_items(
     model: Any,
-    av: "AssumptionValues",
+    scalars: dict,
     periods: list[int],
 ) -> "LineItemValues":
     """
     Calculate all line item values for the given model.
 
-    This function processes formulas in dependency order, evaluates them for
-    each period, and returns a populated LineItemValues container.
-
-    Formulas receive three parameters:
-    - a (AssumptionValues): Access assumptions via a.tax_rate, a.growth_rate, etc.
-    - li (LineItemValues): Access line items via li.revenue[t], li.revenue[t-1], etc.
-    - t (int): Current period being calculated
-
-    This function processes each period in order, calculating all line items
-    for that period before moving to the next. This allows for time-offset
-    references (e.g., li.revenue[t-1]) to work correctly.
-
     Args:
         model: The ProformaModel instance containing line item definitions.
-        av (AssumptionValues): Assumption values for the model.
-        periods (list[int]): List of periods to calculate.
+        scalars: Dict of scalar line item values (FixedLine(value=) or scalar InputLine).
+        periods: List of periods to calculate.
 
     Returns:
         LineItemValues: Populated container with all calculated values.
-
-    Raises:
-        ValueError: If line items are not found or calculation fails.
     """
-    # Import here to avoid circular imports
     from .line_items.debt_line import DebtBase
     from .line_items.fixed_line import FixedLine
     from .line_items.formula_line import FormulaLine
@@ -51,10 +34,8 @@ def calculate_line_items(
     from .line_items.line_item_values import LineItemValues
     from .model_namespace import ModelNamespace
 
-    # Initialize line item values with registered names for validation
     li = LineItemValues(periods=periods, names=model.line_item_names, model=model)
 
-    # Separate fixed and formula line items
     fixed_items = []
     formula_items = []
 
@@ -65,18 +46,14 @@ def calculate_line_items(
         elif isinstance(line_item, (FormulaLine, DebtBase)):
             formula_items.append(name)
 
-    # Calculate values for each period
     for period in periods:
-        # Build a unified namespace for formula evaluation this period
-        ns = ModelNamespace(li, av)
+        ns = ModelNamespace(li, scalars)
 
-        # First, calculate all fixed line items (they don't depend on other line items)
         for name in fixed_items:
             line_item = getattr(model.__class__, name)
             value = _calculate_single_line_item(line_item, ns, period, model)
             li.set(name, period, value)
 
-        # Then calculate formula items with dependency resolution
         remaining = formula_items.copy()
         max_iterations = len(formula_items) + 1
         iteration = 0
@@ -91,32 +68,21 @@ def calculate_line_items(
                     value = _calculate_single_line_item(line_item, ns, period, model)
                     li.set(name, period, value)
                 except AttributeError as e:
-                    # AttributeError means accessing unregistered line item (typo)
-                    # LineItemValues now raises helpful error with available names
                     error_msg = str(e)
                     if "is not registered" in error_msg:
-                        # This is a typo - raise immediately with helpful message
                         raise ValueError(
                             f"Error in formula for '{line_item.name}': {e}"
                         ) from e
-                    # Otherwise, it's some other AttributeError - retry
                     still_pending.append(name)
                 except KeyError as e:
-                    # KeyError could mean:
-                    # 1. Dependency not yet calculated for current period (retry)
-                    # 2. Accessing a period not in the model (fatal error)
-                    # Check if the error is about the current period
                     error_msg = str(e)
                     if f"Period {period}" in error_msg:
-                        # Dependency not yet calculated for current period - retry
                         still_pending.append(name)
                     else:
-                        # Accessing a period outside the model - wrap in ValueError
                         raise ValueError(
                             f"Error evaluating formula for '{line_item.name}' in period {period}: {e}"
                         ) from e
 
-            # If we made no progress, we have a circular reference
             if len(still_pending) == len(remaining):
                 raise ValueError(
                     f"Circular reference detected for period {period}. "
@@ -133,36 +99,12 @@ def _calculate_single_line_item(
     ns: Any,
     period: int,
     model: Any = None,
-) -> float:
-    """
-    Calculate the value of a single line item for a specific period.
-
-    This is a pure function that computes and returns a value without modifying
-    the LineItemValues container. The caller is responsible for storing the result.
-
-    Args:
-        line_item: The line item definition (FixedLine, FormulaLine, etc.).
-            Must have a .name attribute set by __set_name__.
-        ns (ModelNamespace): Unified namespace giving formulas access to both
-            line items and assumptions via a single object.
-        period (int): The period to calculate for.
-        model: The ProformaModel instance (needed for InputLine value lookup).
-
-    Returns:
-        float: The calculated value.
-
-    Raises:
-        ValueError: If calculation fails.
-        AttributeError: If a dependency is not yet calculated.
-        KeyError: If accessing a period not yet calculated.
-    """
-    # Import here to avoid circular imports
+) -> Any:
     from .line_items.debt_line import DebtBase
     from .line_items.fixed_line import FixedLine
     from .line_items.formula_line import FormulaLine
     from .line_items.input_line import InputLine
 
-    # Handle InputLine — values live on the model instance
     if isinstance(line_item, InputLine):
         input_values = getattr(model, "_input_line_values", {})
         period_values = input_values.get(line_item.name, {})
@@ -171,9 +113,8 @@ def _calculate_single_line_item(
             raise ValueError(
                 f"No input value for '{line_item.name}' in period {period}"
             )
-        return float(value)
+        return value
 
-    # Handle FixedLine
     if isinstance(line_item, FixedLine):
         value = line_item.get_value(period)
         if value is None:
@@ -182,50 +123,36 @@ def _calculate_single_line_item(
             )
         return value
 
-    # Handle FormulaLine
     if isinstance(line_item, FormulaLine):
-        # Check for override value first
         if period in line_item.values:
             return line_item.values[period]
-
         try:
             value = line_item.eval(ns, period)
         except (AttributeError, KeyError):
-            # Re-raise these - indicate missing dependencies or periods
-            # The caller will decide whether to retry or raise ValueError
             raise
         except Exception as e:
             raise ValueError(
                 f"Error evaluating formula for '{line_item.name}' in period {period}: {e}"
             ) from e
-
-        # Validate the result type
-        if not isinstance(value, (int, float)):
+        if value is None:
             raise ValueError(
-                f"Formula for '{line_item.name}' returned invalid type: {type(value)}"
+                f"Formula for '{line_item.name}' returned None"
             )
+        return value
 
-        return float(value)
-
-    # Handle DebtBase (DebtPrincipalLine, DebtInterestLine)
     if isinstance(line_item, DebtBase):
         try:
             value = line_item.eval(ns, period)
         except (AttributeError, KeyError):
-            # Re-raise these - indicate missing dependencies or periods
-            # The caller will decide whether to retry or raise ValueError
             raise
         except Exception as e:
             raise ValueError(
                 f"Error evaluating debt line for '{line_item.name}' in period {period}: {e}"
             ) from e
-
-        # Validate the result type
         if not isinstance(value, (int, float)):
             raise ValueError(
                 f"Debt line '{line_item.name}' returned invalid type: {type(value)}"
             )
-
         return float(value)
 
     raise ValueError(f"Unknown line item type for '{line_item.name}'")

pyproforma-0.2.1/pyproforma/chart/__init__.py

@@ -0,0 +1,3 @@
+from .chart import Chart, ChartSeries, ChartSpec, ChartType
+
+__all__ = ["Chart", "ChartSeries", "ChartSpec", "ChartType"]

pyproforma-0.2.1/pyproforma/chart/chart.py

@@ -0,0 +1,107 @@
+"""
+Chart — generic chart data class, rendering-backend agnostic.
+
+Chart and ChartSeries are the intermediate representation between any data
+source and a rendering backend. They are not specific to ProformaModel —
+anything that can populate a list of ChartSeries can produce a Chart.
+
+Rendering backends:
+  - MatplotlibRenderer  → .show() / .figure() for Jupyter and scripts
+  - .to_apexcharts()    → JSON-ready dict for ApexCharts in web apps
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Literal
+
+if TYPE_CHECKING:
+    from pyproforma.table.format_value import NumberFormatSpec
+
+ChartType = Literal["line", "bar", "stacked_bar"]
+
+
+@dataclass
+class ChartSeries:
+    """A single data series for a chart."""
+
+    label: str
+    x_values: list[int]
+    y_values: list[float]
+    color: str | None = None
+
+
+@dataclass
+class Chart:
+    """
+    Intermediate representation of a chart — pure data, rendering-backend agnostic.
+
+    Build one via model.charts.line_item() or model.charts.line_items(), then
+    render it with .show() / .figure() (matplotlib) or .to_apexcharts() (web/JSON).
+    """
+
+    series: list[ChartSeries]
+    chart_type: ChartType = "line"
+    title: str | None = None
+    x_label: str | None = None
+    y_label: str | None = None
+    value_format: "NumberFormatSpec | None" = None
+
+    # ------------------------------------------------------------------
+    # Matplotlib convenience (lazy import — matplotlib not required at import time)
+    # ------------------------------------------------------------------
+
+    def figure(self, figsize: tuple[float, float] = (10, 6)):
+        """Return a matplotlib Figure for this chart."""
+        from pyproforma.chart.renderers.matplotlib_renderer import MatplotlibRenderer
+        return MatplotlibRenderer().render(self, figsize=figsize)
+
+    def show(self, figsize: tuple[float, float] = (10, 6)) -> None:
+        """Render and display this chart via matplotlib."""
+        import matplotlib.pyplot as plt
+        self.figure(figsize=figsize)
+        plt.show()
+
+    # ------------------------------------------------------------------
+    # Web / serialisation
+    # ------------------------------------------------------------------
+
+    def to_apexcharts(self) -> dict:
+        """Return a dict of ApexCharts options ready for JSON serialization."""
+        result = {
+            "series": [
+                {"name": s.label, "data": s.y_values}
+                for s in self.series
+            ],
+            "categories": self.series[0].x_values if self.series else [],
+            "title": self.title or "",
+            "chart_type": self.chart_type,
+            "yaxis_format": self.value_format.to_dict() if self.value_format else None,
+        }
+        colors = [s.color for s in self.series]
+        if any(c is not None for c in colors):
+            result["colors"] = colors
+        return result
+
+    def to_dict(self) -> dict:
+        """Serialise this Chart to a plain dict suitable for JSON / web renderers."""
+        return {
+            "chart_type": self.chart_type,
+            "title": self.title,
+            "x_label": self.x_label,
+            "y_label": self.y_label,
+            "series": [
+                {
+                    "label": s.label,
+                    "x_values": s.x_values,
+                    "y_values": s.y_values,
+                    "color": s.color,
+                }
+                for s in self.series
+            ],
+            "value_format": self.value_format.to_dict() if self.value_format else None,
+        }
+
+
+# Backwards compatibility alias
+ChartSpec = Chart

pyproforma-0.2.1/pyproforma/chart/renderers/__init__.py

@@ -0,0 +1,4 @@
+from .base import ChartRenderer
+from .matplotlib_renderer import MatplotlibRenderer
+
+__all__ = ["ChartRenderer", "MatplotlibRenderer"]

pyproforma-0.2.1/pyproforma/chart/renderers/base.py

@@ -0,0 +1,17 @@
+"""
+ChartRenderer — abstract base for rendering a Chart to a specific backend.
+
+Implement render(chart, **kwargs) to add a new backend (plotly, charts.js, etc.).
+"""
+
+from abc import ABC, abstractmethod
+
+from pyproforma.chart.chart import Chart
+
+
+class ChartRenderer(ABC):
+    """Base class for rendering a Chart to a specific backend."""
+
+    @abstractmethod
+    def render(self, chart: Chart, **kwargs):
+        """Render the Chart and return the backend's figure/output object."""

pyproforma-0.2.1/pyproforma/chart/renderers/matplotlib_renderer.py

@@ -0,0 +1,115 @@
+"""
+MatplotlibRenderer — renders a Chart to a matplotlib Figure.
+
+Called by Chart.show() and Chart.figure(). Supports line, bar, and stacked_bar
+chart types. Applies NumberFormatSpec to y-axis tick labels when set.
+"""
+
+from __future__ import annotations
+
+from pyproforma.chart.renderers.base import ChartRenderer
+from pyproforma.chart.chart import Chart as ChartSpec
+
+
+class MatplotlibRenderer(ChartRenderer):
+    """Renders a ChartSpec to a matplotlib Figure."""
+
+    def render(self, spec: ChartSpec, figsize: tuple[float, float] = (10, 6)):
+        """
+        Render a ChartSpec and return a matplotlib Figure.
+
+        Args:
+            spec: The chart specification to render.
+            figsize: (width, height) in inches. Defaults to (10, 6).
+
+        Returns:
+            matplotlib.figure.Figure
+        """
+        import matplotlib.pyplot as plt
+        import numpy as np
+
+        fig, ax = plt.subplots(figsize=figsize)
+
+        if spec.chart_type == "line":
+            self._render_line(ax, spec)
+        elif spec.chart_type == "bar":
+            self._render_bar(ax, spec)
+        elif spec.chart_type == "stacked_bar":
+            self._render_stacked_bar(ax, spec)
+
+        self._apply_labels(ax, spec)
+        self._apply_y_format(ax, spec)
+
+        if len(spec.series) > 1:
+            ax.legend()
+
+        ax.grid(True, alpha=0.3)
+        plt.tight_layout()
+
+        return fig
+
+    # ------------------------------------------------------------------
+    # Chart type renderers
+    # ------------------------------------------------------------------
+
+    def _render_line(self, ax, spec: ChartSpec) -> None:
+        for series in spec.series:
+            ax.plot(
+                series.x_values,
+                series.y_values,
+                label=series.label,
+                color=series.color,
+                marker="o",
+                linewidth=2,
+                markersize=5,
+            )
+
+    def _render_bar(self, ax, spec: ChartSpec) -> None:
+        import numpy as np
+
+        n = len(spec.series)
+        x = np.arange(len(spec.series[0].x_values))
+        width = 0.8 / n
+
+        for i, series in enumerate(spec.series):
+            offset = (i - n / 2 + 0.5) * width
+            ax.bar(x + offset, series.y_values, width, label=series.label, color=series.color)
+
+        ax.set_xticks(x)
+        ax.set_xticklabels([str(v) for v in spec.series[0].x_values])
+
+    def _render_stacked_bar(self, ax, spec: ChartSpec) -> None:
+        import numpy as np
+
+        x = np.arange(len(spec.series[0].x_values))
+        bottom = np.zeros(len(spec.series[0].x_values))
+
+        for series in spec.series:
+            y = np.array(series.y_values)
+            ax.bar(x, y, bottom=bottom, label=series.label, color=series.color)
+            bottom += y
+
+        ax.set_xticks(x)
+        ax.set_xticklabels([str(v) for v in spec.series[0].x_values])
+
+    # ------------------------------------------------------------------
+    # Shared helpers
+    # ------------------------------------------------------------------
+
+    def _apply_labels(self, ax, spec: ChartSpec) -> None:
+        if spec.title:
+            ax.set_title(spec.title)
+        if spec.x_label:
+            ax.set_xlabel(spec.x_label)
+        if spec.y_label:
+            ax.set_ylabel(spec.y_label)
+
+    def _apply_y_format(self, ax, spec: ChartSpec) -> None:
+        if spec.value_format is None:
+            return
+
+        from matplotlib.ticker import FuncFormatter
+        from pyproforma.table.format_value import format_value
+
+        fmt = spec.value_format
+        ax.yaxis.set_major_formatter(FuncFormatter(lambda val, _pos: format_value(val, fmt)))

pyproforma-0.2.1/pyproforma/charts/__init__.py

@@ -0,0 +1,3 @@
+from .charts import Charts
+
+__all__ = ["Charts"]

pyproforma-0.2.1/pyproforma/charts/chart_def.py

@@ -0,0 +1,45 @@
+"""
+ChartDef — declarative definition of a chart to build from a model.
+
+Used with model.charts.build() to produce a Chart. Holds the line item names,
+chart type, title, and optional per-series colors. Accepts either the dataclass
+form (IDE autocomplete, validation) or a plain dict (JSON-serializable configs).
+"""
+
+from dataclasses import dataclass, field
+from typing import Union
+
+from pyproforma.chart.chart import ChartType
+
+
+@dataclass
+class ChartDef:
+    """
+    Declarative definition of a chart to build from a model.
+
+    Used with model.charts.from_template() to produce a ChartSpec.
+    Accepts either the dataclass form (for Python code with IDE support)
+    or a plain dict (for JSON-serializable configs).
+
+    Examples:
+        >>> ChartDef(names=["revenue", "expenses"])
+        >>> ChartDef(names=["revenue"], chart_type="bar", title="Revenue")
+        >>> ChartDef(names=["revenue", "expenses"], colors=["#206bc4", "#d63939"])
+
+    The dict form is equivalent:
+        >>> {"names": ["revenue"], "chart_type": "bar", "colors": ["#206bc4"]}
+    """
+
+    names: list[str]
+    chart_type: ChartType = "line"
+    title: str | None = None
+    colors: list[str] | None = None
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "ChartDef":
+        return cls(
+            names=data["names"],
+            chart_type=data.get("chart_type", "line"),
+            title=data.get("title"),
+            colors=data.get("colors"),
+        )