monopyly 1.4.8__tar.gz → 1.5.0__tar.gz

{monopyly-1.4.8 → monopyly-1.5.0}/.gitignore

@@ -80,6 +80,7 @@ monopyly/_version.py
 monopyly/static/img/**/*.pptx
 monopyly/static/img/**/*.key
 monopyly/static/img/**/*.xcf
+monopyly/static/img/**/*.svg
 monopyly/static/favicon/*.ai
 
 # Flask instance files/data

{monopyly-1.4.8 → monopyly-1.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: monopyly
-Version: 1.4.8
+Version: 1.5.0
 Summary: A homemade personal finance manager.
 Project-URL: Download, https://pypi.org/project/monopyly
 Project-URL: Homepage, http://monopyly.com
@@ -29,6 +29,7 @@ Requires-Dist: flask==3.0.3
 Requires-Dist: fuisce==1.0.2
 Requires-Dist: gunicorn==22.0.0
 Requires-Dist: markdown==3.6
+Requires-Dist: nltk==3.8.1
 Requires-Dist: python-dateutil==2.9.0
 Requires-Dist: rich==13.7.1
 Requires-Dist: sqlalchemy==2.0.29

{monopyly-1.4.8 → monopyly-1.5.0}/monopyly/CHANGELOG.md

@@ -192,4 +192,11 @@
 - Fix bug in the ordering of balances in the bank account balance charts for transactions on duplicate dates
 
 
+## 1.5.0
+
+- Add categorical pie charts to credit card statement details
+- Provide mobile layouts for the application
+- Create a tool for reconciling credit card transactions with information collected from external resources (e.g., CSVs downloaded from a user's online credit card account)
+
+
 <a name="bottom" id="bottom"></a>

{monopyly-1.4.8 → monopyly-1.5.0}/monopyly/__init__.py

@@ -9,7 +9,7 @@ from monopyly.core.errors import render_error_template
 from monopyly.database import SQLAlchemy, register_db_cli_commands
 
 
-def create_app(test_config=None):
+def create_app(test_config=None, debug=None):
     # Create and configure the app
     app = Flask(__name__, instance_relative_config=True)
 
@@ -18,7 +18,7 @@ def create_app(test_config=None):
         config = test_config
     else:
         # Load the development/production config when not testing
-        if app.debug:
+        if app.debug or debug:
             config = DevelopmentConfig.configure_for_instance(app.instance_path)
         else:
             config = ProductionConfig.configure_for_instance(app.instance_path)

{monopyly-1.4.8 → monopyly-1.5.0}/monopyly/_version.py

@@ -1,4 +1,4 @@
 # file generated by setuptools_scm
 # don't change, don't track in version control
-__version__ = version = '1.4.8'
-__version_tuple__ = version_tuple = (1, 4, 8)
+__version__ = version = '1.5.0'
+__version_tuple__ = version_tuple = (1, 5, 0)

{monopyly-1.4.8 → monopyly-1.5.0}/monopyly/cli/apps.py

@@ -31,7 +31,7 @@ class LocalApplication:
             raise NotImplementedError(
                 f"Options besides `host` and `port` are not handled in {self.mode_name} mode."
             )
-        self.application = create_app()
+        self.application = create_app(debug=self._debug)
 
     def run(self):
         """Run the Monopyly application in development mode."""

{monopyly-1.4.8 → monopyly-1.5.0}/monopyly/cli/launch.py

@@ -16,6 +16,9 @@ from rich.console import Console
 
 from .apps import DevelopmentApplication, LocalApplication, ProductionApplication
 
+# Set the Flask environment variable (to specify the app to use)
+os.environ["FLASK_APP"] = "monopyly"
+
 
 def main(mode, host=None, port=None, backup=False, browser=False):
     app_launcher = Launcher(mode, host=host, port=port)

{monopyly-1.4.8 → monopyly-1.5.0}/monopyly/common/forms/_forms.py

@@ -31,7 +31,7 @@ class EntryForm(FlaskForm, metaclass=AbstractEntryFormMixinMeta):
     that follows the same naming schema.
     """
 
-    def prepopulate(self, entry):
+    def prepopulate(self, entry, data=None):
         """
         Generate a duplicate prepopulated form.
 
@@ -40,6 +40,11 @@ class EntryForm(FlaskForm, metaclass=AbstractEntryFormMixinMeta):
         entry : database.models.Model
             A database entry from which to pull information for
             prepopulating the form.
+        data : dict, optional
+            A dictionary containing extra data that will be joined with
+            data gathered from the given database entry. Fields defined
+            in this data dictionary will supersed fields defined on the
+            entry.
 
         Returns
         -------
@@ -57,7 +62,9 @@ class EntryForm(FlaskForm, metaclass=AbstractEntryFormMixinMeta):
         can not be used as a replacement for populating an existing
         form.
         """
-        data = self.gather_entry_data(entry)
+        entry_data = self.gather_entry_data(entry) if entry else {}
+        # Merge data parsed from the entry with any data provided directly
+        data = entry_data | (data or {})
         return self.__class__(data=data)
 
     @abstractmethod
@@ -175,6 +182,53 @@ class TransactionForm(EntryForm):
     # Define an autocompleter for the form (in a sublcass)
     _autocompleter = None
 
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.suggestions = {}
+
+    def prepopulate(self, entry, data=None, suggestion_fields=()):
+        """
+        Generate a duplicate prepopulated form.
+
+        Parameters
+        ----------
+        entry : database.models.Model
+            A database entry from which to pull information for
+            prepopulating the form.
+        data : dict, optional
+            A dictionary containing extra data that will be joined with
+            data gathered from the given database entry. Fields defined
+            in this data dictionary will supersed fields defined on the
+            entry.
+        suggestion_fields : list, optional
+            A list with form-specific parameters defining how the form
+            will extract and process a suggestion from the dictionary of
+            data which will be added to the form.
+
+        Returns
+        -------
+        form : TransactionForm
+            A duplicate form, prepopulated with the collected database
+            information.
+        """
+        self.suggestions |= self._extract_suggestions(data, suggestion_fields)
+        form = super().prepopulate(entry, data=data)
+        form.suggestions = self.suggestions
+        return form
+
+    def _extract_suggestions(self, data, suggestion_fields):
+        # Extract suggestion field values from the given data as specified
+        suggestions = {}
+        for field in suggestion_fields:
+            extraction_method = getattr(self, f"_extract_{field}_suggestion")
+            suggestions[field] = extraction_method(data)
+        return suggestions
+
+    @staticmethod
+    def _extract_suggestion(data, field):
+        # Pop the field value to provide a suggestion, rather than a deduction
+        return data.pop(field, None)
+
     def _prepare_transaction_data(self):
         subtransactions_data = [
             subform.subtransaction_data for subform in self["subtransactions"]

{monopyly-1.4.8 → monopyly-1.5.0}/monopyly/common/transactions.py

@@ -158,6 +158,15 @@ def _get_linked_credit_transaction(transaction_id, internal_transaction_id):
     return transaction
 
 
+def highlight_unmatched_transactions(transactions, unmatched_transactions):
+    """Highlight transactions that are unmatched."""
+    unmatched_transaction_ids = [_.id for _ in unmatched_transactions]
+    for transaction in transactions:
+        if transaction.id in unmatched_transaction_ids:
+            transaction.highlight = True
+        yield transaction
+
+
 class TransactionTagHandler(DatabaseHandler, model=TransactionTag):
     """
     A database handler for managing transaction tags.
@@ -349,3 +358,156 @@ class TransactionTagHandler(DatabaseHandler, model=TransactionTag):
         query = cls.model.select_for_user().where(*criteria)
         tag = cls._db.session.execute(query).scalar_one_or_none()
         return tag
+
+
+def categorize(transactions):
+    """
+    Categorize subtransactions into a tree of categories and subcategories.
+
+    Given a list of transactions, this function places each transaction
+    (technically each individual subtransaction of the transaction) into
+    categories based on its assigned tags. When a category is ambiguous
+    (e.g., multiple tags have been assigned from different branches in
+    the tag tree), the subtransaction is left uncategorized.
+
+    Parameters
+    ----------
+    transactions : list
+        The transactions (and corresponding subtransactions) to be
+        categorized.
+
+    Returns
+    -------
+    categories : CategoryTree
+        A tree-like structure of transaction categories, including
+        nested subcategories and subtotals at each level.
+    """
+    # Assign the subtransactions to categories
+    categories = RootCategoryTree()
+    for subtransaction in get_subtransactions(transactions):
+        categories.categorize_subtransaction(subtransaction)
+    return categories
+
+
+def get_subtransactions(transactions):
+    """Given a list of transactions, return all the corresponding subtransactions."""
+    return [
+        subtransaction
+        for transaction in transactions
+        for subtransaction in transaction.subtransactions
+    ]
+
+
+class CategoryTree:
+    """
+    Store a tree of categories.
+
+    Parameters
+    ----------
+    category : database.models.TransactionTag, str
+        The (root) category that this tree will represent.
+    subtransactions : list
+        A list of subtransactions that belong to this category, but
+        which are not included in any subcategory of this category.
+
+    Attributes
+    ----------
+    category : database.models.TransactionTag, str
+        The (root) category that this tree represents.
+    subtransactions : list
+        The subtransactions that belong to this category, but which are
+        not included in any subcategory of this category.
+    subcategories : dict
+        A mapping of subcategory names and trees that comprise this
+        category.
+    subtotal : float
+        The subtotal of all transactions in this category and all of its
+        subcategories.
+    """
+
+    def __init__(self, category, subtransactions=None):
+        self.category = category
+        self.subtransactions = subtransactions or []
+        self.subcategories = {}
+
+    @property
+    def subtotal(self):
+        subcategories = list(self.subcategories.values())
+        return sum(item.subtotal for item in self.subtransactions + subcategories)
+
+    def add_subcategory(self, tag):
+        """
+        Add a subcategory to the tree based on the given tag.
+
+        Add a subcategory tree to the mapping of subcategories based
+        on the given tag and return it. If the tag already has a
+        subcategory tree mapped to it, return that subcategory tree
+        instead.
+
+        Parameters
+        ----------
+        tag : database.models.TransactionTag
+            The tag for which a subcategory will be added.
+
+        Returns
+        -------
+        subcategory : CategoryTree
+            The subcategory tree matching the given tag.
+        """
+        return self.subcategories.setdefault(tag.tag_name, CategoryTree(tag))
+
+
+class RootCategoryTree(CategoryTree):
+    """A special class of category tree that forms the root of a categorization."""
+
+    def __init__(self, subtransactions=None):
+        super().__init__("root", subtransactions=subtransactions)
+
+    def categorize_subtransaction(self, subtransaction):
+        """
+        Add a subtransaction to the tree of nested categories by tag.
+
+        Given a subtransaction, add that subtransaction to the category
+        tree according to its tags. If multiple tags exist at the same
+        level of the tree (i.e., a subtransaction with tags in diverging
+        branches), the tag is determined to be "uncategorizable" and the
+        tag is listed only as a member of the root tree and not as a
+        member of any other subcategory tree.
+
+        Parameters
+        ----------
+        subtransaction :
+            The subtransaction to be categorized.
+        """
+        tree = self
+        if subtransaction.categorizable:
+            # Collect all the tags for the subtransaction (ordered by tag depth)
+            tags = sorted(subtransaction.tags, key=lambda tag: tag.depth)
+            for tag in tags:
+                tree = tree.add_subcategory(tag)
+        tree.subtransactions.append(subtransaction)
+
+    def assemble_chart_data(self, exclude=()):
+        """
+        Create a dataset of categories and subtotals that can be used in a chart.
+
+        Parameters
+        ----------
+        exclude : ...
+        """
+        labels, subtotals = [], []
+        # Add chart data for categorical information
+        for name, subcategory in self.subcategories.items():
+            if name not in exclude and subcategory.subtotal > 0:
+                labels.append(name)
+                subtotals.append(subcategory.subtotal)
+        # Add chart data for uncategorized transactions
+        if (other_subtotal := sum(_.subtotal for _ in self.subtransactions)) > 0:
+            labels.append("")
+            subtotals.append(other_subtotal)
+        # Return the data in a format similar to what is required by the chart app
+        subtotal_labels = zip(subtotals, labels, strict=True)
+        return {
+            "labels": [label for _, label in sorted(subtotal_labels, reverse=True)],
+            "subtotals": sorted(subtotals, reverse=True),
+        }

{monopyly-1.4.8 → monopyly-1.5.0}/monopyly/credit/actions.py

@@ -2,6 +2,7 @@
 
 from ..banking.transactions import record_new_transfer
 from ..common.forms.utils import execute_on_form_validation
+from ..common.utils import parse_date
 from .cards import CreditCardHandler
 from .statements import CreditStatementHandler
 from .transactions import CreditTransactionHandler
@@ -174,3 +175,31 @@ def make_payment(card_id, payment_account_id, payment_date, payment_amount):
         ],
     }
     CreditTransactionHandler.add_entry(**credit_mapping)
+
+
+def parse_request_transaction_data(request_args):
+    """
+    Parse transaction data given as arguments on the request.
+
+    Parameters
+    ----------
+    request_args : dict
+        A dictionary of URL arguments provided by the request.
+
+    Returns
+    -------
+    transaction_data : dict
+        A dictionary of transaction data parsed from the request
+        arguments.
+    """
+    if request_args:
+        transaction_data = {
+            "transaction_date": parse_date(request_args.get("transaction_date")),
+        }
+        if (subtotal := request_args.get("total")) is not None:
+            transaction_data["subtransactions"] = [{"subtotal": float(subtotal)}]
+        if (merchant := request_args.get("description")) is not None:
+            transaction_data["merchant"] = merchant
+    else:
+        transaction_data = {}
+    return transaction_data

{monopyly-1.4.8 → monopyly-1.5.0}/monopyly/credit/forms.py

@@ -36,6 +36,8 @@ from ..database.models import (
 from .accounts import CreditAccountHandler
 from .cards import CreditCardHandler
 from .statements import CreditStatementHandler
+from .transactions import CreditTransactionHandler
+from .transactions.activity.reconciliation import ActivityMatchmaker
 
 
 class CreditAccountSelectField(CustomChoiceSelectField):
@@ -297,6 +299,29 @@ class CreditTransactionForm(TransactionForm):
         statement = self.get_transaction_statement()
         return self._prepare_transaction_data(statement)
 
+    def _extract_merchant_suggestion(self, data):
+        # Use the merchant transaction data as a suggestion source
+        if merchant := self._extract_suggestion(data, "merchant"):
+            merchant_tokens = ActivityMatchmaker.tokenize(merchant)
+            # Suggest a known merchant with the closest distance to the activity merchant
+            score_records = []
+            for potential_merchant in CreditTransactionHandler.get_merchants():
+                test_tokens = ActivityMatchmaker.tokenize(potential_merchant)
+                score = ActivityMatchmaker.score_tokens(merchant_tokens, test_tokens)
+                # Only consider scores that have some similarity at all
+                if score < 1:
+                    score_records.append((score, potential_merchant))
+            suggested_merchant = min(score_records)[1] if score_records else None
+        else:
+            suggested_merchant = None
+        return suggested_merchant
+
+    def _extract_amount_suggestion(self, data):
+        # Use the first subtransaction subtotal as a suggestion
+        subtransactions = self._extract_suggestion(data, "subtransactions")
+        suggested_amount = subtransactions[0]["subtotal"] if subtransactions else None
+        return suggested_amount
+
     def get_transaction_statement(self):
         """Get the credit card statement associated with the transaction."""
         return self.statement_info.get_statement(self.transaction_date.data)

{monopyly-1.4.8 → monopyly-1.5.0}/monopyly/credit/routes.py

@@ -4,7 +4,16 @@ Routes for credit card financials.
 
 from itertools import islice
 
-from flask import flash, g, jsonify, redirect, render_template, request, url_for
+from flask import (
+    flash,
+    g,
+    jsonify,
+    redirect,
+    render_template,
+    request,
+    session,
+    url_for,
+)
 from fuisce.database import db_transaction
 from sqlalchemy.exc import MultipleResultsFound
 from werkzeug.exceptions import abort
@@ -16,7 +25,11 @@ from ..banking.banks import BankHandler
 from ..banking.transactions import BankTransactionHandler
 from ..common.forms import form_err_msg
 from ..common.forms.utils import extend_field_list_for_ajax
-from ..common.transactions import get_linked_transaction
+from ..common.transactions import (
+    categorize,
+    get_linked_transaction,
+    highlight_unmatched_transactions,
+)
 from ..common.utils import dedelimit_float, parse_date, sort_by_frequency
 from .accounts import CreditAccountHandler
 from .actions import (
@@ -24,6 +37,7 @@ from .actions import (
     get_potential_preceding_card,
     get_statement_and_transactions,
     make_payment,
+    parse_request_transaction_data,
     transfer_credit_card_statement,
 )
 from .blueprint import bp
@@ -31,6 +45,11 @@ from .cards import CreditCardHandler, save_card
 from .forms import CardStatementTransferForm, CreditCardForm, CreditTransactionForm
 from .statements import CreditStatementHandler
 from .transactions import CreditTagHandler, CreditTransactionHandler, save_transaction
+from .transactions.activity import (
+    ActivityMatchmaker,
+    TransactionActivities,
+    parse_transaction_activity_file,
+)
 
 
 @bp.route("/cards")
@@ -179,6 +198,7 @@ def update_statements_display():
 @login_required
 def load_statement_details(statement_id):
     statement, transactions = get_statement_and_transactions(statement_id)
+    categories = categorize(transactions)
     # Get bank accounts for potential payments
     bank_accounts = BankAccountHandler.get_accounts()
     return render_template(
@@ -186,6 +206,7 @@ def load_statement_details(statement_id):
         statement=statement,
         statement_transactions=transactions,
         bank_accounts=bank_accounts,
+        chart_data=categories.assemble_chart_data(exclude=["Credit payments"]),
     )
 
 
@@ -232,6 +253,68 @@ def pay_credit_card(card_id, statement_id):
     return jsonify((summary_template, transactions_table_template))
 
 
+@bp.route("/_reconcile_activity/<int:statement_id>")
+@login_required
+def reconcile_activity(statement_id):
+    return render_template(
+        "credit/statement_reconciliation/statement_reconciliation_inquiry.html",
+        statement_id=statement_id,
+    )
+
+
+@bp.route("/reconciliation/<int:statement_id>", methods=("GET", "POST"))
+@login_required
+def load_statement_reconciliation_details(statement_id):
+    if request.method == "POST":
+        activity_file = request.files.get("activity-file")
+        # Parse the data and match transactions to activities
+        if activities := parse_transaction_activity_file(activity_file):
+            session["reconciliation_info"] = (statement_id, activities.jsonify())
+    else:
+        activity_data = session.get("reconciliation_info", (None, []))[1]
+        activities = TransactionActivities(activity_data)
+    if activities:
+        statement, transactions = get_statement_and_transactions(statement_id)
+        matchmaker = ActivityMatchmaker(transactions, activities)
+        non_matches = matchmaker.unmatched_transactions
+        transactions = list(highlight_unmatched_transactions(transactions, non_matches))
+        # Calculate the amount charged/refunded during this statement timeframe
+        prior_statement = CreditStatementHandler.get_prior_statement(statement)
+        prior_statement_balance = prior_statement.balance if prior_statement else 0
+        statement_transaction_balance = statement.balance - prior_statement_balance
+        return render_template(
+            "credit/statement_reconciliation/statement_reconciliation_page.html",
+            statement=statement,
+            statement_transactions=transactions,
+            discrepant_records=matchmaker.match_discrepancies,
+            discrepant_amount=abs(statement_transaction_balance - activities.total),
+            unrecorded_activities=matchmaker.unmatched_activities,
+        )
+    else:
+        flash("ERROR")
+        return redirect(
+            url_for("credit.load_statement_details", statement_id=statement_id)
+        )
+
+
+@bp.before_app_request
+def clear_reconciliation_info():
+    exempt_endpoints = (
+        "credit.reconcile_activity",
+        "credit.load_statement_reconciliation_details",
+        "credit.expand_transaction",
+        "credit.add_transaction",
+        "credit.update_transaction",
+        "credit.infer_statement",
+        "credit.suggest_transaction_autocomplete",
+        "credit.delete_transacton",
+        "static",
+        None,
+    )
+    if request.endpoint not in exempt_endpoints:
+        session.pop("reconciliation_info", None)
+
+
 @bp.route("/transactions", defaults={"card_id": None})
 @bp.route("/transactions/<int:card_id>")
 @login_required
@@ -333,12 +416,16 @@ def add_transaction(card_id, statement_id):
             update=False,
         )
     else:
+        transaction_data = parse_request_transaction_data(request.args)
         if statement_id:
-            statement = CreditStatementHandler.get_entry(statement_id)
-            form = form.prepopulate(statement)
+            entry = CreditStatementHandler.get_entry(statement_id)
         elif card_id:
-            card = CreditCardHandler.get_entry(card_id)
-            form = form.prepopulate(card)
+            entry = CreditCardHandler.get_entry(card_id)
+        else:
+            entry = None
+        form = form.prepopulate(
+            entry, data=transaction_data, suggestion_fields=["merchant"]
+        )
     # Display the form for accepting user input
     return render_template(
         "credit/transaction_form/transaction_form_page_new.html", form=form
@@ -360,8 +447,11 @@ def update_transaction(transaction_id):
             update=True,
         )
     else:
+        transaction_data = parse_request_transaction_data(request.args)
         transaction = CreditTransactionHandler.get_entry(transaction_id)
-        form = form.prepopulate(transaction)
+        form = form.prepopulate(
+            transaction, data=transaction_data, suggestion_fields=["amount"]
+        )
     # Display the form for accepting user input
     return render_template(
         "credit/transaction_form/transaction_form_page_update.html",

{monopyly-1.4.8 → monopyly-1.5.0}/monopyly/credit/transactions/_transactions.py

@@ -81,6 +81,21 @@ class CreditTransactionHandler(
         )
         return transactions
 
+    @classmethod
+    @DatabaseViewHandler.view_query
+    def get_merchants(cls):
+        """
+        Get a credit card merchants from the database.
+
+        Returns
+        -------
+        merchants : sqlalchemy.engine.ScalarResult
+            All known credit card transaction merchants from the
+            database.
+        """
+        query = cls.model.select_for_user(cls.model.merchant).distinct()
+        return cls._db.session.scalars(query)
+
     @classmethod
     def add_entry(cls, **field_values):
         """

monopyly-1.5.0/monopyly/credit/transactions/activity/__init__.py

@@ -0,0 +1,3 @@
+from .data import TransactionActivities
+from .parser import parse_transaction_activity_file
+from .reconciliation import ActivityMatchmaker