monopyly 1.4.8__py3-none-any.whl → 1.5.1__py3-none-any.whl

monopyly/CHANGELOG.md

@@ -192,4 +192,22 @@
 - 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)
+
+
+### 1.5.1
+
+- Bump dependencies (including patching security vulnerability in NLTK)
+- Style credit transaction submissions as receipts
+- Style flash messages according to content
+- Return to statement details page after deleting a transaction (rather than returning to the general transactions page)
+- Allow users to change their password
+- Warn users before form submission if the configuration currently disallows registration
+- Increase the flexibility of the credit activity parser
+
+
 <a name="bottom" id="bottom"></a>

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/_version.py

@@ -1,4 +1,16 @@
 # 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)
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple, Union
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+else:
+    VERSION_TUPLE = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+
+__version__ = version = '1.5.1'
+__version_tuple__ = version_tuple = (1, 5, 1)

monopyly/auth/actions.py

@@ -1,5 +1,10 @@
 """Module describing logical authorization actions (to be used in routes)."""
 
+from flask import current_app
+from sqlalchemy import select
+
+from ..database.models import User
+
 
 def get_username_and_password(form):
     """
@@ -11,3 +16,10 @@ def get_username_and_password(form):
     username = form["username"].lower()
     password = form["password"]
     return username, password
+
+
+def identify_user(username):
+    """Identify the user in the database based on the username."""
+    user_query = select(User).where(User.username == username)
+    user = current_app.db.session.scalar(user_query)
+    return user

monopyly/auth/routes.py

@@ -5,6 +5,7 @@ Routes for site authentication.
 from flask import (
     current_app,
     flash,
+    g,
     redirect,
     render_template,
     request,
@@ -16,7 +17,7 @@ from sqlalchemy import select
 from werkzeug.security import check_password_hash, generate_password_hash
 
 from ..database.models import User
-from .actions import get_username_and_password
+from .actions import get_username_and_password, identify_user
 from .blueprint import bp
 
 
@@ -33,24 +34,17 @@ def register():
             error = "Username is required."
         elif not password:
             error = "Password is required."
+        elif user := identify_user(username):
+            error = f"User {username} is already registered."
         else:
-            # Get user information from the database
-            user_query = select(User).where(User.username == username)
-            user = current_app.db.session.scalar(user_query)
-            if user:
-                error = f"User {username} is already registered."
-            else:
-                error = None
-        # Add the username and hashed password to the database
-        if not error:
+            # Create a new user
             new_user = User(
                 username=username,
                 password=generate_password_hash(password),
             )
             current_app.db.session.add(new_user)
             return redirect(url_for("auth.login"))
-        else:
-            flash(error)
+        flash(error)
     # Display the registration page
     return render_template("auth/register.html")
 
@@ -60,23 +54,17 @@ def login():
     if request.method == "POST":
         # Get username and passwords from the form
         username, password = get_username_and_password(request.form)
-        # Get user information from the database
-        user_query = select(User).where(User.username == username)
-        user = current_app.db.session.scalar(user_query)
         # Check for errors in the accessed information
-        if user is None:
+        if (user := identify_user(username)) is None:
             error = "That user is not yet registered."
         elif not check_password_hash(user.password, password):
             error = "Incorrect username and password combination."
         else:
-            error = None
-        # Set the user ID securely for a new session
-        if not error:
+            # Set the user ID securely for a new session
             session.clear()
             session["user_id"] = user.id
             return redirect(url_for("core.index"))
-        else:
-            flash(error)
+        flash(error)
     # Display the login page
     return render_template("auth/login.html")
 
@@ -86,3 +74,24 @@ def logout():
     # End the session and clear the user ID
     session.clear()
     return redirect(url_for("core.index"))
+
+
+@bp.route("/change_password", methods=("GET", "POST"))
+@db_transaction
+def change_password():
+    if request.method == "POST":
+        current_password = request.form["current-password"]
+        new_password = request.form["new-password"]
+        if check_password_hash(g.user.password, current_password):
+            # Merge the user item (dissociated from the current session) for updating
+            g.user = current_app.db.session.merge(g.user)
+            g.user.password = generate_password_hash(new_password)
+            flash("Password updated successfully.", category="success")
+            return redirect(url_for("core.load_profile"))
+        else:
+            flash(
+                "The provided value for the current password does not match the "
+                "value of the current password set on this account.",
+                category="error",
+            )
+    return render_template("auth/change_password.html")

monopyly/auth/tools.py

@@ -14,8 +14,7 @@ from .blueprint import bp
 @bp.before_app_request
 def load_logged_in_user():
     # Match the user's information with the session
-    user_id = session.get("user_id")
-    if user_id is None:
+    if (user_id := session.get("user_id")) is None:
         g.user = None
     else:
         query = select(User).where(User.id == user_id)

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/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/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/common/forms/utils.py

@@ -145,7 +145,6 @@ def execute_on_form_validation(func):
         else:
             # Show an error to the user and print the errors for the admin
             flash(form_err_msg)
-            print(form.errors)
-            raise ValidationError("The form did not validate properly.")
+            raise ValidationError(f"The form did not validate properly: {form.errors}")
 
     return wrapper

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/core/routes.py

@@ -5,7 +5,6 @@ Routes for core functionality.
 from pathlib import Path
 
 from flask import g, render_template, render_template_string, session
-from werkzeug.exceptions import abort
 
 from ..auth.tools import login_required
 from ..banking.accounts import BankAccountHandler
@@ -85,8 +84,3 @@ def load_profile():
     banks = BankHandler.get_banks()
     # Return banks as a list to allow multiple reuse
     return render_template("core/profile.html", banks=list(banks))
-
-
-@bp.route("/change_password")
-def change_password():
-    abort(418)

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/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 := data.get("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)