folioflex 1.2.2__tar.gz → 1.4.0__tar.gz

{folioflex-1.2.2/folioflex.egg-info → folioflex-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: folioflex
-Version: 1.2.2
+Version: 1.4.0
 Summary: A collection of portfolio tracking capabilities
 Author-email: John Koestner <johnkoestner@outlook.com>
 License: The MIT License (MIT)
@@ -27,54 +27,55 @@ License: The MIT License (MIT)
 Project-URL: homepage, https://github.com/jkoestner/folioflex
 Project-URL: documentation, https://jkoestner.github.io/folioflex/
 Project-URL: repository, https://github.com/jkoestner/folioflex
-Requires-Python: >=3.8
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE.md
-Requires-Dist: ipywidgets>=8.1.0
-Requires-Dist: fredapi>=0.4.3
+Requires-Dist: ipywidgets>=8.1.5
+Requires-Dist: fredapi>=0.5.2
 Requires-Dist: jupyter-dash>=0.4.2
-Requires-Dist: jupyterlab>=4.0.10
+Requires-Dist: jupyterlab>=4.3.0
 Requires-Dist: kaleido<0.2.0,>=0.1.0
-Requires-Dist: numpy>=1.22.3
-Requires-Dist: openpyxl>=3.0.7
-Requires-Dist: pandas>=0.25.0
-Requires-Dist: pandas-market-calendars>=4.1.4
-Requires-Dist: pyxirr>=0.7.2
-Requires-Dist: sqlalchemy>=2.0.23
-Requires-Dist: yfinance>=0.2.32
+Requires-Dist: numpy>=1.26.4
+Requires-Dist: openpyxl>=3.1.5
+Requires-Dist: pandas>=2.2.3
+Requires-Dist: pandas-market-calendars>=4.4.1
+Requires-Dist: pyxirr>=0.10.6
+Requires-Dist: sqlalchemy>=2.0.36
+Requires-Dist: yfinance>=0.2.48
 Requires-Dist: tzlocal>=5.2
-Requires-Dist: dash>=1.0.2
+Requires-Dist: dash>=2.18.2
+Requires-Dist: dash-ag-grid>=31.2.0
 Requires-Dist: dash_bootstrap_components>=1.6.0
-Requires-Dist: dash-core-components>=1.0.0
-Requires-Dist: dash-html-components>=1.0.0
-Requires-Dist: dash-renderer>=1.0.0
-Requires-Dist: dash-table>=4.0.2
-Requires-Dist: Flask>=1.1.1
-Requires-Dist: Flask-Compress>=1.4.0
+Requires-Dist: dash-core-components>=2.0.0
+Requires-Dist: dash-html-components>=2.0.0
+Requires-Dist: dash-renderer>=1.9.1
+Requires-Dist: dash-table>=5.0.0
+Requires-Dist: Flask>=3.0.3
+Requires-Dist: Flask-Compress>=1.17
 Requires-Dist: Flask-Login>=0.6.3
-Requires-Dist: gunicorn>=19.9.0
-Requires-Dist: celery>=5.3.1
-Requires-Dist: flower>=2.0.0
-Requires-Dist: redis>=3.3.8
-Requires-Dist: g4f==0.2.4.1
-Requires-Dist: hugchat>=0.3.8
-Requires-Dist: openai>=1.3.7
-Requires-Dist: pyautogui>=0.9.53
-Requires-Dist: seleniumbase>=4.22.0
-Requires-Dist: emoji>=2.9.0
-Requires-Dist: gensim>=4.3.2
-Requires-Dist: scikit-learn>=1.3.2
-Requires-Dist: scipy==1.10.1
-Requires-Dist: psycopg2-binary
+Requires-Dist: gunicorn>=23.0.0
+Requires-Dist: celery>=5.4.0
+Requires-Dist: flower>=2.0.1
+Requires-Dist: redis>=5.2.0
+Requires-Dist: g4f>=0.3.3.3
+Requires-Dist: hugchat>=0.4.12
+Requires-Dist: openai>=1.54.3
+Requires-Dist: pyautogui>=0.9.54
+Requires-Dist: seleniumbase>=4.32.8
+Requires-Dist: emoji>=2.14.0
+Requires-Dist: gensim>=4.3.3
+Requires-Dist: scikit-learn>=1.5.2
+Requires-Dist: scipy<1.14
+Requires-Dist: psycopg2-binary>=2.9.10
 Provides-Extra: dev
-Requires-Dist: black>=23.7.0; extra == "dev"
+Requires-Dist: black>=24.10.0; extra == "dev"
 Requires-Dist: isort>=5.13.2; extra == "dev"
-Requires-Dist: jupyterlab-code-formatter>=2.2.1; extra == "dev"
-Requires-Dist: pytest>=7.4.0; extra == "dev"
-Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
-Requires-Dist: ruff>=0.1.5; extra == "dev"
-Requires-Dist: sphinx<7.2,>=6.0; extra == "dev"
-Requires-Dist: sphinx_rtd_theme>=1.2.2; extra == "dev"
+Requires-Dist: jupyterlab-code-formatter>=3.0.2; extra == "dev"
+Requires-Dist: pytest>=8.3.3; extra == "dev"
+Requires-Dist: pytest-cov>=6.0.0; extra == "dev"
+Requires-Dist: ruff>=0.7.3; extra == "dev"
+Requires-Dist: sphinx>=8.1; extra == "dev"
+Requires-Dist: sphinx_rtd_theme>=3.0.1; extra == "dev"
 
 <div align="center">
   <img src="https://user-images.githubusercontent.com/50647092/260895211-7e9a8e6e-9f85-48ed-bb61-49ff2ff805b6.png"><br>
@@ -118,13 +119,11 @@ Simple investment portfolio tool that will track stock and provide returns and o
 **🔧 Features:**
 
 - **Market Screener**: Filter and find trending stocks. 🔍
-![screener](docs/screenshots/screener.png)
-![heatmap](docs/screenshots/heatmap.png)
+![stock](docs/screenshots/ffx_stock.gif)
 - **Portfolio Management**: Organize and track, your investments. 💼
-![portfolio](docs/screenshots/portfolio.png)
+![portfolio](docs/screenshots/ffx_invest.gif)
 - **Budget Tool**: Create and monitor a budget. 💰
-![budget](docs/screenshots/budget.png)
-![budget_compare](docs/screenshots/budget_compare.png)
+![budget](docs/screenshots/ffx_budget.gif)
 
 **📚 Documentation:**
 
@@ -244,7 +243,7 @@ When using the portfolio class, the following code can be used to get the return
 
 ```python
 from folioflex.portfolio.portfolio import Portfolio
-config_path = "portfolio_demo.ini"
+config_path = "portfolio_demo.yml"
 pf = Portfolio(
     config_path=config_path, 
     portfolio='company_a'

{folioflex-1.2.2 → folioflex-1.4.0}/README.md

@@ -40,13 +40,11 @@ Simple investment portfolio tool that will track stock and provide returns and o
 **🔧 Features:**
 
 - **Market Screener**: Filter and find trending stocks. 🔍
-![screener](docs/screenshots/screener.png)
-![heatmap](docs/screenshots/heatmap.png)
+![stock](docs/screenshots/ffx_stock.gif)
 - **Portfolio Management**: Organize and track, your investments. 💼
-![portfolio](docs/screenshots/portfolio.png)
+![portfolio](docs/screenshots/ffx_invest.gif)
 - **Budget Tool**: Create and monitor a budget. 💰
-![budget](docs/screenshots/budget.png)
-![budget_compare](docs/screenshots/budget_compare.png)
+![budget](docs/screenshots/ffx_budget.gif)
 
 **📚 Documentation:**
 
@@ -166,7 +164,7 @@ When using the portfolio class, the following code can be used to get the return
 
 ```python
 from folioflex.portfolio.portfolio import Portfolio
-config_path = "portfolio_demo.ini"
+config_path = "portfolio_demo.yml"
 pf = Portfolio(
     config_path=config_path, 
     portfolio='company_a'

{folioflex-1.2.2 → folioflex-1.4.0}/folioflex/budget/budget.py

@@ -13,14 +13,14 @@ Some methods that are included are:
 """
 
 import re
+from typing import Any, Dict, List, Optional, Union
 
 import emoji
 import numpy as np
 import pandas as pd
 import plotly.express as px
-import sqlalchemy as sa
 
-from folioflex.utils import config_helper, custom_logger
+from folioflex.utils import config_helper, custom_logger, database
 
 logger = custom_logger.setup_logging(__name__)
 
@@ -40,16 +40,23 @@ class Budget:
 
     def __init__(
         self,
-        config_path,
-        budget,
-    ):
+        config_path: str,
+        budget: str,
+    ) -> None:
         """Initialize the Portfolio class."""
         logger.info("Initializing Budget class.")
-        self.config_dict = config_helper.get_config_options(config_path, budget)
+        self.config_path = config_path
+        self.config_dict = config_helper.get_config_options(
+            config_path, "budgets", budget
+        )
         self.budgets = self.config_dict["budgets"]
         self.default = self.config_dict["default"]
+        self.budget = budget
+        self.model = self.config_dict.get("model", None)
 
-    def get_transactions(self, engine=None):
+    def get_transactions(
+        self, engine: Optional[Any] = None, user: Optional[str] = None
+    ) -> pd.DataFrame:
         """
         Get the transactions for the budget.
 
@@ -59,6 +66,8 @@ class Budget:
         ----------
         engine : SQLAlchemy engine
             The engine to connect to the database.
+        user : str, optional
+            The user to get the transactions for.
 
         Returns
         -------
@@ -79,16 +88,16 @@ class Budget:
 
         """
         if engine is None:
-            engine = self._create_engine()
+            engine = database.Engine(self.config_path)
+        if user is None:
+            user = self.config_dict.get("user", None)
         logger.info("Getting transactions.")
         # creating a dataframe of transactions that include
         # the account name, item name, and transaction name
-        with engine.connect() as conn, conn.begin():
-            tx_df = pd.read_sql_table("transactions_table", conn)
-        with engine.connect() as conn, conn.begin():
-            item_df = pd.read_sql_table("items_table", conn)
-        with engine.connect() as conn, conn.begin():
-            account_df = pd.read_sql_table("accounts_table", conn)
+        user_df = engine.read_table("users_table")
+        item_df = engine.read_table("items_table")
+        account_df = engine.read_table("accounts_table")
+        tx_df = engine.read_table("transactions_table")
         # creating a grouped dataset
         tx_df = pd.merge(
             tx_df,
@@ -100,12 +109,22 @@ class Budget:
         )
         tx_df = pd.merge(
             tx_df,
-            item_df[["id", "plaid_institution_id"]],
+            item_df[["id", "plaid_institution_id", "user_id"]],
             left_on="item_id",
             right_on="id",
             how="left",
             suffixes=[None, "_tmp"],
         )
+        tx_df = pd.merge(
+            tx_df,
+            user_df[["id", "username"]],
+            left_on="user_id",
+            right_on="id",
+            how="left",
+            suffixes=[None, "_tmp"],
+        )
+        if user is not None:
+            tx_df = tx_df[tx_df["username"] == user]
         tx_df = tx_df[
             [
                 "id",
@@ -136,6 +155,12 @@ class Budget:
         """
         Modify the transactions for the budget.
 
+        The modifications include:
+          - Zero out the amount for the given columns
+          - Extract the text between quotes
+          - Preprocess the emoji in the text
+          - Remove the pending transactions.
+
         Parameters
         ----------
         tx_df : DataFrame
@@ -285,6 +310,74 @@ class Budget:
             return "Incoming Transfer"
         return "OTHER"
 
+    def identify_subscriptions(self, tx_df):
+        """
+        Identify possible subscriptions in the transactions.
+
+        The subscriptions are identified by the name and also the amount. If
+        the amount is similar for multiple transactions, and there are at least
+        a set amount of transcations, then it is likely a subscription.
+
+        Parameters
+        ----------
+        tx_df : DataFrame
+            The transactions to identify subscriptions for.
+
+        Returns
+        -------
+        subscriptions : DataFrame
+            The subscriptions identified in the transactions.
+
+        """
+        # default values
+        min_transactions = 3
+        interval_std_threshold = 5
+        amount_std_threshold = 0.1
+
+        # group data by name
+        grouped_df = tx_df.groupby("name")
+
+        # identify subscriptions
+        subscriptions = []
+        for name, group in grouped_df:
+            if len(group) < min_transactions:
+                continue
+
+            # calculating the intervals and ensure they are regular
+            intervals = group["date"].diff().dropna().dt.days
+            regular = intervals.std() <= interval_std_threshold
+
+            # calculate the amount and ensure it is consistent
+            amount_mean = group["amount"].mean()
+            if amount_mean == 0:
+                continue
+            relative_std = group["amount"].std() / amount_mean
+            consistent_amount = relative_std <= amount_std_threshold
+
+            # get the last date and amount
+            last_date = group["date"].max()
+            last_amount = group[group["date"] == last_date]["amount"].values[0]
+
+            if regular and consistent_amount:
+                subscriptions.append(
+                    {
+                        "Description": name,
+                        "Occurrences": len(group),
+                        "Mean Interval (Days)": intervals.mean(),
+                        "Amount Mean": group["amount"].mean(),
+                        "Amount Std Dev": group["amount"].std(),
+                        "Last Date": last_date,
+                        "Last Amount": last_amount,
+                    }
+                )
+
+        subscriptions_df = pd.DataFrame(subscriptions)
+        subscriptions_df = subscriptions_df.sort_values(
+            by="Occurrences", ascending=False
+        )
+
+        return subscriptions_df
+
     def budget_view(self, tx_df, target_date, exclude_labels=None):
         """
         Provide a view of categories and their budget status.
@@ -308,6 +401,7 @@ class Budget:
         if exclude_labels is not None:
             tx_df = tx_df[~tx_df["label"].isin(exclude_labels)]
             budgets = {k: v for k, v in budgets.items() if k not in exclude_labels}
+
         # grouping transactions
         grouped_transactions = (
             tx_df[tx_df["date"].dt.to_period("M") == target_date]
@@ -316,6 +410,7 @@ class Budget:
             .reset_index()
             .sort_values("amount", ascending=True)
         )
+
         # adding in the budget
         unused_keys = set(budgets.keys()) - set(grouped_transactions["label"])
         unused_keys_df = pd.DataFrame({"label": list(unused_keys)})
@@ -327,6 +422,7 @@ class Budget:
         grouped_transactions["budget"] = grouped_transactions["budget"].fillna(
             float(self.config_dict["default"])
         )
+
         # providing a total
         totals = grouped_transactions.sum(numeric_only=True).to_frame().T
         totals["label"] = "TOTAL"
@@ -517,7 +613,81 @@ class Budget:
 
         return fig
 
-    def category_tx_view(self, tx_df, target_date, category):
+    def display_category_trend(self, tx_df, category):
+        """
+        Display the category trend view as a bar chart.
+
+        Parameters
+        ----------
+        tx_df : DataFrame
+            The transactions to view income status for.
+        category : str
+            The category to view the trend for.
+
+        Returns
+        -------
+        fig : Figure
+            The category trend view as a line chart.
+
+        """
+        # filter data for category
+        category_df = tx_df[tx_df["label"] == category]
+        category_df = category_df.groupby(["month"])["amount"].sum().reset_index()
+        if len(category_df) == 0:
+            logger.warning(f"No transactions found for category: {category}")
+            return None
+
+        # budgets
+        category_budget = self.budgets.get(category, 0)
+        average_budget = category_df["amount"].mean()
+        twelve_month_avg = category_df["amount"].rolling(window=12).mean()
+
+        # create bar chart
+        fig = px.bar(
+            category_df,
+            x="month",
+            y="amount",
+            title=f"'{category}' Spending Trend",
+            labels={"month": "Month", "amount": "Amount"},
+            color_discrete_sequence=["blue"],
+        )
+
+        # add budget line
+        fig.add_scatter(
+            x=category_df["month"],
+            y=[category_budget] * len(category_df),
+            mode="lines",
+            line={"color": "red", "dash": "dash"},
+            name="Budget",
+        )
+
+        # add average line
+        fig.add_scatter(
+            x=category_df["month"],
+            y=[average_budget] * len(category_df),
+            mode="lines",
+            line={"color": "black", "dash": "dash"},
+            name="Average",
+        )
+
+        # add 12 month average line
+        fig.add_scatter(
+            x=category_df["month"],
+            y=twelve_month_avg,
+            mode="lines",
+            line={"color": "green", "dash": "dash"},
+            name="12-Month Average",
+        )
+
+        return fig
+
+    def category_tx_view(
+        self,
+        tx_df,
+        target_date,
+        category,
+        columns=None,
+    ):
         """
         Display the transactions view as a table.
 
@@ -529,6 +699,8 @@ class Budget:
             The date to view transactions for. Format: YYYY-MM.
         category : str
             The category to view transactions for.
+        columns : list (optional)
+            The columns to view in the table.
 
         Returns
         -------
@@ -536,10 +708,20 @@ class Budget:
             The category of transactions view as a table.
 
         """
+        if columns is None:
+            columns = [
+                "date",
+                "amount",
+                "name",
+                "label",
+                "official_name",
+            ]
+
         cat_tx_df = tx_df[
             (tx_df["date"].dt.to_period("M") == target_date)
             & (tx_df["label"].str.contains(category))
-        ].sort_values(by="amount", ascending=False)
+        ].sort_values(by="date", ascending=False)
+        cat_tx_df = cat_tx_df[columns]
         return cat_tx_df
 
     def update_labels_db(self, tx_df, engine=None, label_column="label"):
@@ -561,68 +743,15 @@ class Budget:
 
         """
         if engine is None:
-            engine = self._create_engine()
+            engine = database.Engine(self.config_path)
         logger.info("Updating labels in database.")
-        rows_updated = 0
-        with engine.connect() as conn:
-            for _, row in tx_df.iterrows():
-                if pd.isna(row[label_column]):
-                    update_label_query = sa.text(
-                        """
-                        UPDATE public.transactions_table
-                        SET "label" = NULL
-                        WHERE id = :id;
-                    """
-                    )
-                    executed = conn.execute(update_label_query, {"id": row["id"]})
-                else:
-                    update_label_query = sa.text(
-                        """
-                        UPDATE public.transactions_table
-                        SET "label" = :label
-                        WHERE id = :id;
-                    """
-                    )
-                    executed = conn.execute(
-                        update_label_query,
-                        {"label": row[label_column], "id": row["id"]},
-                    )
-                rows_updated = rows_updated + executed.rowcount
-            conn.commit()
-        logger.info(f"Rows updated: {rows_updated}")
-
-    def _create_engine(self):
-        """
-        Create an engine.
 
-        Returns
-        -------
-        engine : SQLAlchemy engine
-            The engine to connect to the database.
+        # filter the table
+        tx_df = tx_df[[label_column, "id"]]
 
-        """
-        db_user = self.config_dict.get("db_user", None)
-        db_pass = self.config_dict.get("db_pass", None)
-        db_host = self.config_dict.get("db_host", None)
-        db_name = self.config_dict.get("db_name", None)
-        db_port = self.config_dict.get("db_port", None)
-
-        config_values = {
-            "db_user": db_user,
-            "db_pass": db_pass,
-            "db_host": db_host,
-            "db_name": db_name,
-            "db_port": db_port,
-        }
-        missing_values = [key for key, value in config_values.items() if value is None]
-        if missing_values:
-            raise ValueError(
-                f"The following configuration values are missing: "
-                f"{', '.join(missing_values)}"
-            )
-
-        logger.info("Connecting to database.")
-        engine = sa.create_engine(
-            f"postgresql://{db_user}:{db_pass}@{db_host}:{db_port}/{db_name}"
+        tx_df = tx_df.rename(columns={label_column: "label"})
+        engine.bulk_update(
+            tx_df=tx_df, table_name="transactions_table", where_column="id"
         )
-        return engine
+
+        logger.info(f"Rows updated: {len(tx_df)}")