owlplanner 2025.12.20__py3-none-any.whl → 2026.2.2__py3-none-any.whl

owlplanner/utils.py

@@ -1,17 +1,28 @@
 """
+Utility functions for data formatting and manipulation.
 
-Owl/utils
+This module provides helper functions for formatting currency, percentages,
+and other data transformations used throughout the retirement planner.
 
-This file contains functions for handling data.
+Copyright (C) 2025-2026 The Owlplanner Authors
 
-Copyright © 2024 - Martin-D. Lacasse
+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.
 
-Disclaimers: This code is for educational purposes only and does not constitute financial advice.
+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
+import pandas as pd
 
 
 def d(value, f=0, latex=False) -> str:
@@ -70,6 +81,15 @@ def getUnits(units) -> int:
     return fac
 
 
+def get_numeric_option(options, key, default, *, min_value=None) -> float:
+    value = options.get(key, default)
+    if not isinstance(value, (int, float)):
+        raise ValueError(f"{key} {value} is not a number.")
+    if min_value is not None and value < min_value:
+        raise ValueError(f"{key} must be >= {min_value}.")
+    return float(value)
+
+
 # Next two functions could be a one-line lambda functions.
 # e.g., krond = lambda a, b: 1 if a == b else 0
 def krond(a, b) -> int:
@@ -125,3 +145,158 @@ def parseDobs(dobs):
         tobs.append(ls[2])
 
     return np.array(yobs, dtype=np.int32), np.array(mobs, dtype=np.int32), np.array(tobs, dtype=np.int32)
+
+
+def is_row_active(row):
+    """
+    Check if a DataFrame row should be processed based on 'active' column.
+
+    This function handles the common pattern of checking whether a row in a DataFrame
+    should be processed based on its 'active' column value. The logic is:
+    - If 'active' column doesn't exist, the row is considered active (default behavior)
+    - If 'active' value is NaN or None, the row is considered active (default behavior)
+    - If 'active' value is explicitly False (or falsy), the row is considered inactive
+    - Otherwise (True or truthy), the row is considered active
+
+    Parameters
+    ----------
+    row : pd.Series
+        A pandas Series representing a row from a DataFrame. The row should have
+        an 'active' column (or index entry) if the active/inactive status is to be checked.
+
+    Returns
+    -------
+    bool
+        True if the row should be processed (is active), False if it should be skipped (is inactive).
+    """
+    if "active" not in row.index:
+        return True  # Default to active if column doesn't exist
+    active_value = row["active"]
+    if pd.isna(active_value) or active_value is None:
+        return True  # NaN/None means active
+    return bool(active_value)
+
+
+def is_dataframe_empty(df):
+    """
+    Check if a DataFrame is None or empty.
+
+    This function consolidates the common pattern of checking
+    `df is None or df.empty` throughout the codebase.
+
+    Parameters
+    ----------
+    df : pd.DataFrame or None
+        The DataFrame to check. Can be None or an empty DataFrame.
+
+    Returns
+    -------
+    bool
+        True if df is None or empty, False otherwise.
+    """
+    return df is None or df.empty
+
+
+def ensure_dataframe(df, default_empty=None):
+    """
+    Ensure DataFrame is not None or empty, return default if needed.
+
+    This function checks if a DataFrame is None or empty and returns a default
+    value if so. This consolidates the common pattern of checking
+    `df is None or df.empty` throughout the codebase.
+
+    Parameters
+    ----------
+    df : pd.DataFrame or None
+        The DataFrame to check. Can be None or an empty DataFrame.
+    default_empty : any, optional
+        The value to return if df is None or empty. Default is None.
+        Common values are 0.0, np.zeros(N_n), or a default DataFrame.
+
+    Returns
+    -------
+    any
+        Returns default_empty if df is None or empty, otherwise returns df.
+    """
+    if is_dataframe_empty(df):
+        return default_empty
+    return df
+
+
+def get_empty_array_or_value(N_n, default_value=0.0):
+    """
+    Return empty array or single value based on context.
+
+    This helper function returns either a numpy array of zeros with length N_n
+    if N_n is provided, or a single default value if N_n is None.
+
+    Parameters
+    ----------
+    N_n : int or None
+        Length of the array to create. If None, returns default_value instead.
+    default_value : float, optional
+        Default value to return if N_n is None. Default is 0.0.
+
+    Returns
+    -------
+    np.ndarray or float
+        Returns np.zeros(N_n) if N_n is not None, otherwise returns default_value.
+    """
+    if N_n is not None:
+        return np.zeros(N_n)
+    return default_value
+
+
+def convert_to_bool(val):
+    """
+    Convert various input types to boolean.
+
+    Handles conversion from strings, numbers, booleans, and NaN values.
+    Excel may read booleans as strings ("True"/"False") or numbers (1/0),
+    so this function provides robust conversion.
+
+    Parameters
+    ----------
+    val : any
+        Value to convert to boolean. Can be:
+        - bool: returned as-is
+        - str: "True", "False", "1", "0", "yes", "no", etc.
+        - numeric: 1/0 or other numeric values
+        - None/NaN: defaults to True
+
+    Returns
+    -------
+    bool
+        Boolean value. NaN/None and unknown values default to True.
+    """
+    # Check for None first (before pd.isna which can fail on some types)
+    if val is None:
+        return True  # Default to True for None
+
+    # Check for NaN, but handle cases where pd.isna might fail (e.g., empty lists)
+    try:
+        if pd.isna(val):
+            return True  # Default to True for NaN
+    except (ValueError, TypeError):
+        # pd.isna can raise ValueError for empty arrays/lists
+        # or TypeError for unhashable types - treat as non-NaN and continue
+        pass
+    if isinstance(val, bool):
+        return val
+    if isinstance(val, str):
+        # Handle string representations
+        val_lower = val.lower().strip()
+        if val_lower in ("true", "1", "yes", "y"):
+            return True
+        elif val_lower in ("false", "0", "no", "n"):
+            return False
+        else:
+            # Unknown string, default to True
+            return True
+    # Handle numeric values (1/0)
+    try:
+        num_val = float(val)
+        return bool(num_val) if num_val != 0 else False
+    except (ValueError, TypeError):
+        # Can't convert, default to True
+        return True

owlplanner/version.py

@@ -1 +1,20 @@
-__version__ = "2025.12.20"
+"""
+Package version information.
+
+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/>.
+"""
+
+__version__ = "2026.02.02"

{owlplanner-2025.12.20.dist-info → owlplanner-2026.2.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: owlplanner
-Version: 2025.12.20
+Version: 2026.2.2
 Summary: Owl - Optimal Wealth Lab: Retirement planner with great wisdom
 Project-URL: HomePage, https://github.com/mdlacasse/owl
 Project-URL: Repository, https://github.com/mdlacasse/owl
@@ -683,6 +683,7 @@ License:                     GNU GENERAL PUBLIC LICENSE
         the library.  If this is what you want to do, use the GNU Lesser General
         Public License instead of this License.  But first, please read
         <https://www.gnu.org/licenses/why-not-lgpl.html>.
+License-File: AUTHORS
 License-File: LICENSE
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: End Users/Desktop
@@ -691,8 +692,10 @@ Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Classifier: Topic :: Office/Business :: Financial :: Investment
 Requires-Python: >=3.10
+Requires-Dist: click>=8.3.1
 Requires-Dist: highspy
 Requires-Dist: jupyter>=1.1.1
+Requires-Dist: loguru>=0.7.3
 Requires-Dist: matplotlib
 Requires-Dist: numpy
 Requires-Dist: odfpy
@@ -712,7 +715,7 @@ Description-Content-Type: text/markdown
 
 ## A retirement exploration tool based on linear programming
 
-<img align=right src="https://github.com/mdlacasse/Owl/blob/main/docs/images/owl.png?raw=true" width="250">
+<img align="right" src="papers/images/owl.png" width="250">
 
 -------------------------------------------------------------------------------------
 
@@ -724,6 +727,10 @@ Users can select varying return rates to perform historical back testing,
 stochastic rates for performing Monte Carlo analyses,
 or fixed rates either derived from historical averages, or set by the user.
 
+Owl is designed for US retirees as it considers US federal tax laws,
+Medicare premiums, rules for 401k including required minimum distributions,
+maturation rules for Roth accounts and conversions, social security rules, etc.
+
 There are three ways to run Owl:
 
 - **Streamlit Hub:** Run Owl remotely as hosted on the Streamlit Community Server at
@@ -763,6 +770,7 @@ Follow these [instructions](INSTALL.md) to install from the source code and self
 It can also run on [MOSEK](https://mosek.com) if available on your computer.
 - Owl planner relies on the following [Python](https://python.org) packages:
     - [highspy](https://highs.dev),
+    [loguru](https://github.com/Delgan/loguru),
     [Matplotlib](https://matplotlib.org),
     [Numpy](https://numpy.org),
     [odfpy](https://https://pypi.org/project/odfpy),
@@ -789,7 +797,7 @@ your computer and can be used to reproduce a case at a later time.
 
 ---------------------------------------------------------------------
 
-Copyright &copy; 2024 - Martin-D. Lacasse
+Copyright &copy; 2024-2026 - Martin-D. Lacasse
 
 Disclaimers: This code is for educatonal purposes only and does not constitute financial advice.
 

owlplanner-2026.2.2.dist-info/RECORD

@@ -0,0 +1,35 @@
+owlplanner/__init__.py,sha256=X9u8PrfeTyfjuksYhx0eNrIACgX5Tg3Le7pz8qKkJXk,1341
+owlplanner/abcapi.py,sha256=5yWuiu5eBVO46V5vklO_zfCCrFZX9guRZ9XEemeJ878,7229
+owlplanner/config.py,sha256=uMP68aG-YnSL0Mqw9tqrxxh62rkUHhwExWzS6rpOIeo,20619
+owlplanner/debts.py,sha256=c-eLynjOFryYisae51Po6Iuh46_d_AGOUbOz3z96ZJY,9850
+owlplanner/fixedassets.py,sha256=ItFeXjIdhMVNyXY0xBW6P9ODRajVg1kDRaid9-Eu_Ww,11510
+owlplanner/mylogging.py,sha256=amQA0qWPsXMoJkYYF3nMaVtCDZMWxXJ1hbJS0TkMvf8,8269
+owlplanner/plan.py,sha256=yYIdSfjJfsuV5aij0xfI8jZkRCRLWc-NV6wAycM4Ef0,157402
+owlplanner/progress.py,sha256=ayqoRUMn6dtIxHDYaeX1mu7W2rAhkBYAi4Y2Y_NtdYA,2521
+owlplanner/rates.py,sha256=pN6J1aZsj_OaCuLrU4vRlQJOCg3dKhamPuAmvI3Ekls,15158
+owlplanner/socialsecurity.py,sha256=4vn76dUZ2P2fMKyy4eu2ramGNvPQymKzsNFZvwbFWOc,7595
+owlplanner/tax2026.py,sha256=CN4nvdxz7ZqhvM57SwYjO4jF6VtDBRMgFpdj1zVU6yk,15907
+owlplanner/timelists.py,sha256=4dBZVCgNIx0RwUfimp_k-m9KhRFj6BHX8Hon1vb8oo8,15032
+owlplanner/utils.py,sha256=l2-3HmZutFlEfJUp7gFblY3PBNYm7HiPPCGl0wFkVmA,9461
+owlplanner/version.py,sha256=8VDixj8vuzpLB0-WNUz9mZbrP9d1ufVm-oLGVHEzvPw,747
+owlplanner/cli/README.md,sha256=R-jwwiX5ZW6gCKaRPWVCgwKVoN2MKozrLAkKvfUT4vA,2292
+owlplanner/cli/_main.py,sha256=qAy_2oCLaa_EhvfGFnuh_sVXkCcgp70WMSL7_QKH5XI,1497
+owlplanner/cli/cli_logging.py,sha256=CTBaAMpJIG7ge9Gz44YykBiea3hMxdAXHyiLj1UyvDU,1690
+owlplanner/cli/cmd_list.py,sha256=lOpS_5LGR1IpJLOaHQOrwm1EtbGwv0tfIcZZ8QObmMM,2584
+owlplanner/cli/cmd_run.py,sha256=aLy-X6x_3MSO_yBQ1R4MWKzczfQgWuRQUsNTrVUaWj8,3009
+owlplanner/data/__init__.py,sha256=jpbWHd9n4F06pyfQj1kI3HQ3uiWXfZCjb5BYINOr9_M,850
+owlplanner/data/awi.csv,sha256=w9YwPEqhxqo1Czumh3ihLXLPtk8kJQgqWKClMysOq-c,1625
+owlplanner/data/bendpoints.csv,sha256=h0a7_XqTuyHWe5ZlS3mjIcAWqOMG_93GoiETS-1xxUY,746
+owlplanner/data/newawi.csv,sha256=w9YwPEqhxqo1Czumh3ihLXLPtk8kJQgqWKClMysOq-c,1625
+owlplanner/data/rates.csv,sha256=6Pr5cXFunZKRzB32--kWzhuRnTQMNFfZaww0QF1SIag,3898
+owlplanner/plotting/__init__.py,sha256=UrKO_zHTxZ-Wb2sQbyk2vNHe20Owzt6M1KJ2M6Z5GGw,944
+owlplanner/plotting/base.py,sha256=70-J5AWnHtWqrehVhCNojnTdfNT6PnEpxBKzDh3R57o,3298
+owlplanner/plotting/factory.py,sha256=sVZ0uAuGKBVVh1qkF2IS7xNZGUPIQRIfqgUt2s2Ncjk,1694
+owlplanner/plotting/matplotlib_backend.py,sha256=AILNOhXi_gsR__i1hKoHaEHvMUqQMyLeRAGCoCBfQBY,19222
+owlplanner/plotting/plotly_backend.py,sha256=OqMJRxAhpwIbKSV-Od1-q-tzOs66McZPbKD32be2qx0,34523
+owlplanner-2026.2.2.dist-info/METADATA,sha256=L4Dl5IrtC1_a9-2Ezk8FezJzf5YA6T8nAiYMgUtJTeg,46498
+owlplanner-2026.2.2.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+owlplanner-2026.2.2.dist-info/entry_points.txt,sha256=m2Ql-6VQbotl65wiqx35d3TIh-Tm6Wdjrz3hNdqZKKg,52
+owlplanner-2026.2.2.dist-info/licenses/AUTHORS,sha256=KD6uW6iEOHf51J8DEJ6az-gowFv3NWIpW4zRgqxwuAA,464
+owlplanner-2026.2.2.dist-info/licenses/LICENSE,sha256=IwGE9guuL-ryRPEKi6wFPI_zOhg7zDZbTYuHbSt_SAk,35823
+owlplanner-2026.2.2.dist-info/RECORD,,

owlplanner-2026.2.2.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+owlcli = owlplanner.cli._main:cli

owlplanner-2026.2.2.dist-info/licenses/AUTHORS

@@ -0,0 +1,15 @@
+# This is the list of Owlplanner's significant contributors.
+#
+# This does not necessarily list everyone who has contributed code.
+# To see the full list of contributors, see the revision history in
+# source control.
+Martin-D. Lacasse (mdlacasse, original author)
+Robert E. Anderson (NH-RedAnt)
+Clark Jefcoat (hubcity)
+kg333
+John Leonard (jleonard99)
+Benjamin Quinn (blquinn)
+Dale Seng (sengsational)
+Josh Williams (noimjosh)
+Gene Wood (gene1wood)
+