monopyly 1.4.7__py3-none-any.whl → 1.5.0__py3-none-any.whl

monopyly/CHANGELOG.md

@@ -184,4 +184,19 @@
 - Refresh the table of transactions after making a payment on a credit card statement
 - Use SVG to handle long values in account/statement summary boxes; fixes bugs in page rendering (long value overflow) and hover actions not happening because of conflicting overlap with the sidebar
 
+
+### 1.4.8
+
+- Set username collection to be case insensitive
+- Use Flask/Gunicorn APIs (rather than subprocess CLI calls) to launch the app
+- 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/README.md

@@ -22,7 +22,7 @@ To install the app, simply run
 $ pip install monopyly
 ```
 
-The package requires a recent version of Python (3.9+).
+The package requires a recent version of Python (3.10+).
 
 
 ## Getting started

monopyly/__init__.py

@@ -1,5 +1,5 @@
 """
-Run a development server for the Monopyly app.
+Run the Monopyly app.
 """
 
 from flask import Flask
@@ -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,4 @@
 # file generated by setuptools_scm
 # don't change, don't track in version control
-__version__ = version = '1.4.7'
-__version_tuple__ = version_tuple = (1, 4, 7)
+__version__ = version = '1.5.0'
+__version_tuple__ = version_tuple = (1, 5, 0)

monopyly/auth/actions.py

@@ -2,7 +2,12 @@
 
 
 def get_username_and_password(form):
-    """Get username and password from a form."""
-    username = form["username"]
+    """
+    Get username and password from a form.
+
+    Get the username and password from the given form. Username should
+    be case insensitive.
+    """
+    username = form["username"].lower()
     password = form["password"]
     return username, password

monopyly/banking/actions.py

@@ -1,5 +1,7 @@
 """Module describing logical banking actions (to be used in routes)."""
 
+from collections import UserList, namedtuple
+
 from ..common.utils import convert_date_to_midnight_timestamp
 from .accounts import BankAccountHandler, BankAccountTypeHandler
 
@@ -29,16 +31,55 @@ def get_balance_chart_data(transactions):
     Returns
     -------
     chart_data : list
-        A list of sorted (x, y) pairs consisting of the Unix timestamp
-        (in milliseconds) and the bank account balance.
+        A list containing (x, y) pairs, each consisting of the Unix
+        timestamp (in milliseconds) and the bank account balance.
+    """
+    return list(_BalanceChartData(transactions))
+
+
+class _BalanceChartData(UserList):
     """
-    chart_data = sorted(map(_make_transaction_balance_ordered_pair, transactions))
-    return chart_data
+    A list of balances to be passed to a `chartist.js` chart constructor.
+
+    A special list-like object containing transaction data formatted for
+    use in a balance chart created by the `chartist.js` library. This
+    converts each transaction into an (x, y) pair consisting of a Unix
+    timestamp (in milleseconds) and a corresponding bank account
+    balance. For transactions occurring on the same day (the finest
+    granularity recorded by the Monopyly app), a slight offset is
+    added to each timestamp to guarantee a smooth representation in the
+    rendered chart.
+
+    Parameters
+    ----------
+    transactions : list
+        A list of transactions to be used for generating the chart data.
+    """
+
+    _DAILY_MILLISECONDS = 86_400_000
+    offset = 1
+    point = namedtuple("DataPoint", ["timestamp", "balance"])
+
+    def __init__(self, transactions):
+        super().__init__()
+        transaction_groups = self._group_transactions_by_date(transactions)
+        self._prepare_chart_data(transaction_groups)
 
+    @staticmethod
+    def _group_transactions_by_date(transactions):
+        date_groups = {}
+        for transaction in transactions:
+            group = date_groups.setdefault(transaction.transaction_date, [])
+            group.append(transaction)
+        return date_groups
 
-def _make_transaction_balance_ordered_pair(transaction):
-    # Create an ordered pair of date (timestamp) and account balance
-    timestamp = convert_date_to_midnight_timestamp(
-        transaction.transaction_date, milliseconds=True
-    )
-    return timestamp, transaction.balance
+    def _prepare_chart_data(self, transaction_groups):
+        # Assign chart data to the list as tuples, adding offsets for duplicated dates
+        for transaction_date, transaction_group in transaction_groups.items():
+            base_timestamp = convert_date_to_midnight_timestamp(
+                transaction_date, milliseconds=True
+            )
+            offset = self._DAILY_MILLISECONDS / len(transaction_group)
+            for i, transaction in enumerate(transaction_group):
+                adjusted_timestamp = base_timestamp + (i * offset)
+                self.data.append((adjusted_timestamp, transaction.balance))

monopyly/banking/routes.py

@@ -79,7 +79,8 @@ def load_account_details(account_id):
         "banking/account_page.html",
         account=account,
         account_transactions=transactions[:100],
-        chart_data=get_balance_chart_data(transactions),
+        # Reverse the chart transactions to be chronologically ascending
+        chart_data=get_balance_chart_data(reversed(transactions)),
     )
 
 

monopyly/cli/apps.py

@@ -21,25 +21,25 @@ class LocalApplication:
 
     mode_name = "local"
     default_port = "5001"
-    command = ["flask"]
+    _debug = None
 
     def __init__(self, host=None, port=None, **options):
         """Initialize the application in development mode."""
         self._host = host
-        self._port = port
+        self._port = port or self.default_port
         if options:
             raise NotImplementedError(
                 f"Options besides `host` and `port` are not handled in {self.mode_name} mode."
             )
+        self.application = create_app(debug=self._debug)
 
     def run(self):
         """Run the Monopyly application in development mode."""
-        instruction = self.command + ["run"]
-        if self._host:
-            instruction += ["--host", self._host]
-        if self._port:
-            instruction += ["--port", self._port]
-        server = subprocess.Popen(instruction)
+        self.application.run(
+            host=self._host,
+            port=self._port,
+            debug=self._debug,
+        )
 
 
 class DevelopmentApplication(LocalApplication):
@@ -52,8 +52,8 @@ class DevelopmentApplication(LocalApplication):
     """
 
     mode_name = "development"
-    default_port = "5000"
-    command = LocalApplication.command + ["--debug"]
+    default_port = None  # traditionally 5000
+    _debug = True
 
 
 class ProductionApplication(BaseApplication):
@@ -64,31 +64,33 @@ class ProductionApplication(BaseApplication):
     Gunicorn server instead of the built-in Python server.
     """
 
-    default_port = "8000"
+    default_port = None  # traditionally 8000
     _default_worker_count = (multiprocessing.cpu_count() * 2) + 1
 
     def __init__(self, host=None, port=None, **options):
         """Initialize the application in production mode."""
-        options["bind"] = self._parse_binding(host, port, options.get("bind"))
-        options.setdefault("workers", self._default_worker_count)
+        if port and not host:
+            raise ValueError("A host must be specified when the port is given.")
+        self._host = host
+        self._port = port or self.default_port
         self.options = options
+        self.options["bind"] = self._determine_binding(options.get("bind"))
+        self.options.setdefault("workers", self._default_worker_count)
         self.application = create_app()
         super().__init__()
 
-    @staticmethod
-    def _parse_binding(host, port, bind_option):
+    def _determine_binding(self, bind_option):
         # Parse any socket binding options
-        if (host or port) and bind_option:
+        if self._host and bind_option:
             raise ValueError(
-                "Neither `host` nor `port` parameters can be specified if the "
-                "`bind` option is given."
+                "The `host` may not be specified directly if the `bind` option is used."
             )
-        bind_values = []
-        if host:
-            bind_values.append(host)
-        if port:
-            bind_values.append(port)
-        return bind if (bind := ":".join(bind_values)) else bind_option
+        if self._host:
+            bind_values = [self._host]
+            if self._port:
+                bind_values.append(self._port)
+            bind_option = ":".join(bind_values)
+        return bind_option
 
     def load_config(self):
         config = {

monopyly/cli/{run.py → launch.py}

@@ -16,26 +16,37 @@ from rich.console import Console
 
 from .apps import DevelopmentApplication, LocalApplication, ProductionApplication
 
-# Set the Flask environment variable
+# Set the Flask environment variable (to specify the app to use)
 os.environ["FLASK_APP"] = "monopyly"
 
 
-def main():
-    args = parse_arguments()
-    app_launcher = Launcher(args.mode, host=args.host, port=args.port)
+def main(mode, host=None, port=None, backup=False, browser=False):
+    app_launcher = Launcher(mode, host=host, port=port)
     # Initialize the database and run the app
     app_launcher.initialize_database()
-    if args.backup:
+    if backup:
         app_launcher.backup_database()
     app_launcher.launch()
-    if args.mode in ("development", "local"):
+    if mode in ("development", "local"):
         # Enable browser viewing in development mode
-        if args.browser:
+        if browser:
             app_launcher.open_browser(delay=1)
         # Wait for the exit command to stop
         app_launcher.wait_for_exit()
 
 
+def main_cli():
+    """Run the app as a command line program."""
+    args = parse_arguments()
+    main(
+        args.mode,
+        host=args.host,
+        port=args.port,
+        backup=args.backup,
+        browser=args.browser,
+    )
+
+
 def parse_arguments():
     parser = argparse.ArgumentParser(description=__doc__)
     parser.add_argument("--host", help="the host address where the app will be run")
@@ -121,4 +132,4 @@ class Launcher:
 
 
 if __name__ == "__main__":
-    main()
+    main_cli()

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/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/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 := 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)