owlplanner 2025.12.5__py3-none-any.whl → 2026.1.26__py3-none-any.whl

owlplanner/plotting/__init__.py

@@ -1,10 +1,23 @@
 """
-Plotting backends for Owl.
+Plotting backends package for Owl retirement planner.
 
-Copyright © 2025 - Martin-D. Lacasse
+This package provides a factory pattern for creating plot backends (matplotlib,
+plotly) for visualizing retirement planning results.
 
-Disclaimers: This code is for educatonal purposes only and does not constitute financial advice.
+Copyright (C) 2025-2026 The Owlplanner Authors
 
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <https://www.gnu.org/licenses/>.
 """
 
 from .factory import PlotFactory

owlplanner/plotting/base.py

@@ -1,10 +1,24 @@
 """
-Base classes for plot backends.
+Abstract base classes for plot backends.
 
-Copyright © 2025 - Martin-D. Lacasse
+This module defines the abstract base class interface that all plotting
+backends must implement for consistent plotting functionality across
+different visualization libraries.
 
-Disclaimers: This code is for educatonal purposes only and does not constitute financial advice.
+Copyright (C) 2025-2026 The Owlplanner Authors
 
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <https://www.gnu.org/licenses/>.
 """
 
 from abc import ABC, abstractmethod

owlplanner/plotting/factory.py

@@ -1,10 +1,23 @@
 """
-Factory for creating plot backends.
+Factory for creating plot backend instances.
 
-Copyright © 2025 - Martin-D. Lacasse
+This module provides a factory class to create plot backends (matplotlib or
+plotly) based on the specified backend type.
 
-Disclaimers: This code is for educatonal purposes only and does not constitute financial advice.
+Copyright (C) 2025-2026 The Owlplanner Authors
 
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <https://www.gnu.org/licenses/>.
 """
 
 from .base import PlotBackend

owlplanner/plotting/matplotlib_backend.py

@@ -1,10 +1,23 @@
 """
-Matplotlib implementation of plot backend.
+Matplotlib backend implementation for plotting retirement planning results.
 
-Copyright © 2025 - Martin-D. Lacasse
+This module provides the Matplotlib-based implementation of the plot backend
+interface for creating static visualizations of retirement planning data.
 
-Disclaimers: This code is for educatonal purposes only and does not constitute financial advice.
+Copyright (C) 2025-2026 The Owlplanner Authors
 
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <https://www.gnu.org/licenses/>.
 """
 
 import numpy as np
@@ -65,10 +78,20 @@ class MatplotlibBackend(PlotBackend):
         """Core function for stacked plots."""
         nonzeroSeries = {}
         for sname in snames:
-            for i in irange:
-                tmp = series[sname][i]
-                if sum(tmp) > 1.0:
-                    nonzeroSeries[sname + " " + inames[i]] = tmp
+            source_data = series[sname]
+            # Check if this is a household-level source (shape (1, N_n) when N_i > 1)
+            is_household = source_data.shape[0] == 1 and len(inames) > 1
+            if is_household:
+                # Show household total once without individual name
+                tmp = source_data[0]
+                if abs(sum(tmp)) > 1.0:  # Use abs for debts
+                    nonzeroSeries[sname] = tmp
+            else:
+                # Show per individual
+                for i in irange:
+                    tmp = source_data[i]
+                    if abs(sum(tmp)) > 1.0:  # Use abs for debts
+                        nonzeroSeries[sname + " " + inames[i]] = tmp
 
         if len(nonzeroSeries) == 0:
             return None, None

owlplanner/plotting/plotly_backend.py

@@ -1,10 +1,23 @@
 """
-Plotly implementation of plot backend.
+Plotly backend implementation for plotting retirement planning results.
 
-Copyright © 2025 - Martin-D. Lacasse
+This module provides the Plotly-based implementation of the plot backend
+interface for creating interactive visualizations of retirement planning data.
 
-Disclaimers: This code is for educatonal purposes only and does not constitute financial advice.
+Copyright (C) 2025-2026 The Owlplanner Authors
 
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <https://www.gnu.org/licenses/>.
 """
 
 import numpy as np
@@ -749,7 +762,7 @@ class PlotlyBackend(PlotBackend):
 
                 # Add each individual's data as a separate series
                 for i in range(len(inames)):
-                    if np.sum(values[i]) > 1.0:  # Only show non-zero series
+                    if np.abs(np.sum(values[i])) > 1.0:  # Only show non-zero series (use abs for debts)
                         stack_data.append((values[i], f"{namek} {inames[i]}"))
 
             # Add stacked area traces
@@ -829,7 +842,7 @@ class PlotlyBackend(PlotBackend):
                     stack_data.append(data)
 
                 # Add stacked area traces
-                for data, name in zip(stack_data, stack_names):
+                for data, name in zip(stack_data, stack_names, strict=True):
                     fig.add_trace(go.Scatter(
                         x=year_n,
                         y=data,
@@ -887,7 +900,7 @@ class PlotlyBackend(PlotBackend):
         for sname in savings:
             for i in range(len(inames)):
                 data = savings[sname][i] / 1000
-                if np.sum(data) > 1.0e-3:  # Only show non-zero series
+                if np.abs(np.sum(data)) > 1.0e-3:  # Only show non-zero series (use abs for debts)
                     nonzero_series[f"{sname} {inames[i]}"] = data
 
         # Add stacked area traces for each account type
@@ -942,10 +955,20 @@ class PlotlyBackend(PlotBackend):
         # Filter out zero series and create individual series names
         nonzero_series = {}
         for sname in sources:
-            for i in range(len(inames)):
-                data = sources[sname][i] / 1000
-                if np.sum(data) > 1.0e-3:  # Only show non-zero series
-                    nonzero_series[f"{sname} {inames[i]}"] = data
+            source_data = sources[sname]
+            # Check if this is a household-level source (shape (1, N_n) when N_i > 1)
+            is_household = source_data.shape[0] == 1 and len(inames) > 1
+            if is_household:
+                # Show household total once without individual name
+                data = source_data[0] / 1000
+                if np.abs(np.sum(data)) > 1.0e-3:  # Only show non-zero series (use abs for debts)
+                    nonzero_series[sname] = data
+            else:
+                # Show per individual
+                for i in range(len(inames)):
+                    data = source_data[i] / 1000
+                    if np.abs(np.sum(data)) > 1.0e-3:  # Only show non-zero series (use abs for debts)
+                        nonzero_series[f"{sname} {inames[i]}"] = data
 
         # Add stacked area traces for each source type
         for source_name, data in nonzero_series.items():

owlplanner/progress.py

@@ -1,24 +1,81 @@
 """
-A simple object to display progress.
+Progress indicator for long-running operations.
 
-Copyright © 2024 - Martin-D. Lacasse
+This module provides a simple progress indicator class that displays
+progress as a percentage on a single line that updates in place.
 
-Disclaimers: This code is for educational purposes only and does not constitute financial advice.
+Copyright (C) 2025-2026 The Owlplanner Authors
 
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <https://www.gnu.org/licenses/>.
 """
 
+from typing import Optional
 from owlplanner import utils as u
 
 
-class Progress(object):
-    def __init__(self, mylog):
+class Progress:
+    """
+    A simple progress indicator for long-running operations.
+
+    Displays progress as a percentage (0-100%) on a single line that updates
+    in place using carriage return.
+
+    Example:
+        prog = Progress(mylog)
+        prog.start()
+        for i in range(100):
+            prog.show(i / 100)
+        prog.finish()
+    """
+
+    def __init__(self, mylog: Optional[object] = None):
+        """
+        Initialize the progress indicator.
+
+        Args:
+            mylog: Logger object with a print() method. If None, progress
+                   updates will be silently ignored (useful for Streamlit UI).
+        """
         self.mylog = mylog
 
     def start(self):
-        self.mylog.print("|--- progress ---|")
+        """
+        Display the progress header.
+        """
+        if self.mylog is not None:
+            self.mylog.print("|--- progress ---|")
+
+    def show(self, x: float):
+        """
+        Display the current progress percentage.
+
+        Args:
+            x: Progress value between 0.0 and 1.0 (will be clamped to this range).
+               Values outside this range will be clamped.
+        """
+        if self.mylog is None:
+            return
+
+        # Clamp x to [0, 1] range
+        x = max(0.0, min(1.0, x))
 
-    def show(self, x):
-        self.mylog.print(f"\r\r{u.pc(x, f=0)}", end="")
+        # Use single \r for carriage return (double \r\r is unnecessary)
+        self.mylog.print(f"\r{u.pc(x, f=0)}", end="")
 
     def finish(self):
-        self.mylog.print()
+        """
+        Finish the progress display by printing a newline.
+        """
+        if self.mylog is not None:
+            self.mylog.print()