amortize_over beancount plugin. move meta to posting and add optional different start date, support more than 2 postings

amortize_over.py

# Copyright (c) 2017 Cary Kempston

# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to deal
# in the Software without restriction, including without limitation the rights
# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
# copies of the Software, and to permit persons to whom the Software is
# furnished to do so, subject to the following conditions:

# The above copyright notice and this permission notice shall be included in all
# copies or substantial portions of the Software.

# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
# SOFTWARE.

from collections import namedtuple

from beancount.core.data import Account, Transaction, Entries, Posting
from beancount.core.amount import Amount

from datetime import date
from dateutil.relativedelta import relativedelta

__plugins__ = ('amortize_over',)


AmortizationError = namedtuple('AmortizationError', 'source message entry')


def amortize_over(entries : Entries, unused_options_map, amortize_account="Assets:Prepaid-Expenses"):
    """Repeat a transaction based on metadata.
    Args:
      entries: A list of directives. We're interested only in the
               Transaction instances.
      unused_options_map: A parser options dict.
    Returns:
      A list of entries and a list of errors.
    Example use:
    This plugin will convert the following transactions
        2017-06-01 * "Amortize car insurance over six months"
            Assets:Bank:Checking            -600.00 USD
            Expenses:Insurance:Auto
                amortize_months: 3
    into the following transactions over six months:
        2017-06-01 * Pay car insurance
            Assets:Bank:Checking               -600.00 USD
            Assets:Prepaid-Expenses             600.00 USD
        2017-06-01 * Amortize car insurance over six months
            Assets:Prepaid-Expenses            -200.00 USD
            Expenses:Insurance:Auto             200.00 USD
        2017-07-01 * Amortize car insurance over six months
            Assets:Prepaid-Expenses            -200.00 USD
            Expenses:Insurance:Auto             200.00 USD
        2017-08-01 * Amortize car insurance over six months
            Assets:Prepaid-Expenses            -200.00 USD
            Expenses:Insurance:Auto             200.00 USD
    """

    new_entries = []
    errors = []

    for entry in entries:
        if isinstance(entry, Transaction):
            for i, posting in enumerate(entry.postings):
                if posting.meta is not None and "amortize_months" in posting.meta:
                    a_entires, a_errors = amortize_transaction(entry, posting, amortize_account)
                    new_entries.extend(a_entires)
                    errors.extend(a_errors)

                    # change posting to amotize_account
                    entry.postings[i] = posting._replace(account=amortize_account)

        new_entries.append(entry)

    return new_entries, errors


def split_amount(amount, periods):
    if periods == 1:
        return [amount]
    amount_this_period = amount / periods
    amount_this_period = amount_this_period.quantize(amount)
    return [amount_this_period] + split_amount(amount - amount_this_period, periods - 1)


def amortize_transaction(entry, posting_to_amortize: Posting, amortize_account: str):

    new_entries = []
    errors = []
    
    if sum(['amortize_months' in p.meta for p in entry.postings]) > 1:
        error = AmortizationError(
            entry.meta,
            'Can only amortized one of the postings.',
            entry
        )
        errors.append(error)
        return new_entries, errors

    periods = posting_to_amortize.meta['amortize_months']
    start_date = entry.date
    if 'amortize_start' in posting_to_amortize.meta:
        start_date = date.fromisoformat(posting_to_amortize.meta.get('amortize_start'))

    amount = abs(entry.postings[0].units.number)
    currency = entry.postings[0].units.currency

    monthly_amounts = split_amount(amount, periods)

    for (n_month, monthly_number) in enumerate(monthly_amounts):
        new_postings = []
        # posting_to_amortize change amount
        new_monthly_number = monthly_number
        if posting_to_amortize.units.number < 0:
            new_monthly_number = -monthly_number
        amortized_posting = posting_to_amortize._replace(units=Amount(number=new_monthly_number,
                                                                      currency=currency))
        new_postings.append(amortized_posting)
        amortize_account_posting = posting_to_amortize._replace(account=amortize_account,
                                                                units=Amount(number=-new_monthly_number,
                                                                             currency=currency))
        new_postings.append(amortize_account_posting)

        new_narration = f'{entry.narration} ({n_month + 1}/{periods})'
        new_entry = entry._replace(
            narration=new_narration,
            postings=new_postings,
            date=start_date + relativedelta(months=n_month),
        )
        #if new_entry.date <= date.today():
        new_entries.append(new_entry)
    return new_entries, errors

example.beancount

plugin "amortize_over"

2017-06-01 open Assets:Bank:Checking
2017-06-01 open Assets:Prepaid-Expenses
2017-06-01 open Expenses:Insurance:Auto

2017-06-01 * "Amortize car insurance over six months"
    
    Assets:Prepaid-Expenses       -600.00 USD
    Expenses:Insurance:Auto
      amortize_months: 6
      amortize_start: "2017-06-15"